Basic Ext

C:\Program Files\Adobe\FrameMaker7.0\UniVerse 10.
2\basicext\Front September 22, 2006 4:10 pm
Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta
UniVerse
UniVerse BASIC Extensions
Version 10.2 September, 2006
C:\Program Files\Adobe\FrameMaker7.0\UniVerse 10.2\basicext\Front September 22, 2006 4:10 pm
Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta
IBM Corporation 555 Bailey Avenue San Jose, CA 95141 Licensed Materials Property of IBM Copyright International Business Machines Corporation 2006. All rights reserved. AIX, DB2, DB2 Universal Database, Distributed Relational Database Architecture, NUMA-Q, OS/2, OS/390, and OS/400, IBM Informix, C-ISAM, Foundation.2000 , IBM Informix 4GL, IBM Informix DataBlade module, Client SDK, Cloudscape, Cloudsync, IBM Informix Connect, IBM Informix Driver for JDBC, Dynamic Connect, IBM Informix Dynamic Scalable Architecture (DSA), IBM Informix Dynamic Server, IBM Informix Enterprise Gateway Manager (Enterprise Gateway Manager), IBM Informix Extended Parallel Server, i.Financial Services, J/Foundation, MaxConnect, Object Translator, Red Brick Decision Server, IBM Informix SE, IBM Informix SQL, InformiXML, RedBack, SystemBuilder, U2, UniData, UniVerse, wIntegrate are trademarks or registered trademarks of International Business Machines Corporation. Java and all Java-based trademarks and logos are trademarks or registered trademarks of Sun Microsystems, Inc. in the United States and other countries. Windows, Windows NT, and Excel are either registered trademarks or trademarks of Microsoft Corporation in the United States and/or other countries. UNIX is a registered trademark in the United States and other countries licensed exclusively through X/Open Company Limited. Other company, product, and service names used in this publication may be trademarks or service marks of others. This product includes cryptographic software written by Eric Young (eay@cryptosoft.com). This product includes software written by Tim Hudson (tjh@cryptosoft.com). Documentation Team: Claire Gustafson, Shelley Thompson
US GOVERNMENT USERS RESTRICTED RIGHTS Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.
ii
UniVerse BASIC
Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta
Table of Contents
Table of Contents
Preface
Documentation Conventions. UniVerse Documentation . . Related Documentation . . API Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . x xii xiv xv
Chapter 1
Using the Socket Interface

Socket Function Error Return Codes . . . . . . . . . Getting a Socket Error Message . . . . . . . . . . Opening a Socket . . . . . . . . . . . . . . . Opening a Secure Socket . . . . . . . . . . . . . Closing a Socket . . . . . . . . . . . . . . . Getting Information From a Socket . . . . . . . . . Reading From a Socket . . . . . . . . . . . . . Writing to a Socket . . . . . . . . . . . . . . Setting the Value for a Socket Option . . . . . . . . . Getting the Value of a Socket Option . . . . . . . . . Initializing a Server Side Socket Connection . . . . . . Initializing a Secure Server Side Socket Connection . . . . Accepting an Incoming Connection Attempt on the Server Side Protocol Logging . . . . . . . . . . . . . . . Socket API Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-3 1-7 1-8 1-9 1-11 1-12 1-14 1-16 1-18 1-20 1-23 1-24 1-26 1-28 1-30
Chapter 2
Using CallHTTP
Configuring the Default HTTP Settings . Getting the Current HTTP Default Settings Creating an HTTP Request . . . . . Creating a Secure HTTP Request . . . Setting Additional Headers for a Request. Adding a Parameter to the Request. . . Submitting a Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-3 2-6 2-7 2-10 2-12 2-14 2-16
C:\Program Files\Adobe\FrameMaker7.0\UniVerse 10.2\basicext\BasicExtTOC.fm (bookTOC.template) September 22, 2006 3:24 pm
Chapter 3
Using WebSphere MQ with UniVerse

In This Chapter . . . . . . . . . . . . . . . . Preface . . . . . . . . . . . . . . . . . . . Overview of Messaging . . . . . . . . . . . . . . Overview of IBM WebSphere MQ . . . . . . . . . . WebSphere MQ API for UniData and UniVerse . . . . . . MQSeries Application Messaging Interface . . . . . . Session . . . . . . . . . . . . . . . . . Services . . . . . . . . . . . . . . . . . Policies . . . . . . . . . . . . . . . . . Message Objects . . . . . . . . . . . . . . Messaging Styles . . . . . . . . . . . . . . Setup and Configuration for the WebSphere MQ API . . . . Requirements . . . . . . . . . . . . . . . Platform Availability . . . . . . . . . . . . . Setting up the Environment for UniData and WebSphere MQ Configurations . . . . . . . . . . . . . . . WebSphere MQ API Programmatic Interfaces . . . . . . . Initialize an AMI Session . . . . . . . . . . . . . Receiving a Message. . . . . . . . . . . . . . . Receiving a Request . . . . . . . . . . . . . . . Sending a Message . . . . . . . . . . . . . . . Sending a Request . . . . . . . . . . . . . . . Sending a Response . . . . . . . . . . . . . . . Terminating a Session . . . . . . . . . . . . . . Programming Examples . . . . . . . . . . . . . . Additional Reading . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-2 3-3 3-4 3-5 3-7 3-7 3-8 3-8 3-9 3-9 3-10 3-12 3-12 3-12 3-12 3-14 3-18 3-19 3-21 3-25 3-29 3-31 3-33 3-35 3-37 3-47
Chapter 4
Creating XML Documents

XML for IBM UniVerse. . . . . . . . Document Type Definitions . . . . . The Document Object Model (DOM) . . Well-Formed and Valid XML Documents Creating an XML Document from RetrieVe . Create the &XML& File . . . . . . Mapping Modes . . . . . . . . The Mapping File. . . . . . . . . . Distinguishing Elements . . . . . . Root Element Attributes . . . . . . Association Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-2 4-2 4-3 4-3 4-4 4-4 4-4 4-6 4-7 4-7 4-11
iv UniVerse BASIC Extensions
Mapping File Example . . . . . . . . . . . How Data is Mapped . . . . . . . . . . . Mapping Example . . . . . . . . . . . . Creating an XML Document . . . . . . . . . Examples . . . . . . . . . . . . . . . Creating an XML Document with UniVerse SQL . . . . Create the &XML& File . . . . . . . . . . Processing Rules for UniVerse SQL SELECT Statements XML Limitations in UniVerse SQL . . . . . . . Examples . . . . . . . . . . . . . . . UniVerse BASIC Example . . . . . . . . . . .
. . . . . . . . . . .
. . . . . . . . . . .
. . . . . . . . . . .
. . . . . . . . . . .
. . . . . . . . . . .
4-12 4-19 4-20 4-21 4-22 4-36 4-36 4-38 4-39 4-39 4-62
Chapter 5
Receiving XML Documents

XML for IBM UniVerse . . . . . . . . . . . . Document Type Definitions . . . . . . . . . The Document Object Model (DOM) . . . . . . Well-Formed and Valid XML Documents . . . . . Creating an XML Document from RetrieVe . . . . . . Create the &XML& File . . . . . . . . . . Mapping Modes . . . . . . . . . . . . . The Mapping File . . . . . . . . . . . . . . Distinguishing Elements . . . . . . . . . . Root Element Attributes . . . . . . . . . . Association Elements . . . . . . . . . . . Mapping File Example . . . . . . . . . . . How Data is Mapped . . . . . . . . . . . Mapping Example . . . . . . . . . . . . Creating an XML Document . . . . . . . . . Examples . . . . . . . . . . . . . . . Creating an XML Document with UniVerse SQL . . . . Create the &XML& File . . . . . . . . . . Processing Rules for UniVerse SQL SELECT Statements XML Limitations in UniVerse SQL . . . . . . . Examples . . . . . . . . . . . . . . . UniVerse BASIC Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-2 5-2 5-3 5-3 5-4 5-4 5-4 5-6 5-7 5-7 5-11 5-12 5-19 5-20 5-21 5-22 5-36 5-36 5-38 5-39 5-39 5-62
Chapter 6
The Simple Object Access Protocol

SOAP Components . . . . . . The SOAP API for BASIC . . . . . Sending a SOAP Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-2 6-4 6-4
Table of Contents v
SOAP API for BASIC Programmatic Interfaces SOAPSetDefault . . . . . . . . SOAPGetDefault . . . . . . . . SOAPCreateRequest . . . . . . . SOAPSetParameters . . . . . . . SOAPSetRequestHeader . . . . . . SOAPSetRequestBody . . . . . . SOAPSetRequestContent. . . . . . SOAPRequestWrite . . . . . . . SOAPSubmitRequest . . . . . . . SOAPGetResponseHeader . . . . . SOAPGetFault . . . . . . . . . protocolLogging . . . . . . . . SOAP API for BASIC Example . . . . .
. . . . . . . . . . . . . .
. . . . . . . . . . . . . .
. . . . . . . . . . . . . .
. . . . . . . . . . . . . .
. . . . . . . . . . . . . .
. . . . . . . . . . . . . .
. . . . . . . . . . . . . .
. . . . . . . . . . . . . .
. . . . . . . . . . . . . .
6-5 6-5 6-6 6-7 6-10 6-12 6-13 6-14 6-15 6-17 6-18 6-19 6-21 6-23
Chapter 7
The Document Object Model

XPath and the Document Object Model . . . A Sample XML document . . . . . Opening and Closing a DOM Document . Navigating the DOM Tree . . . . . Building DOM Trees from Scratch. . . Transforming XML documents . . . . XML for BASIC API Programmatic Interfaces XDOMOpen. . . . . . . . . . XDOMCreateNode . . . . . . . XDOMCreateRoot . . . . . . . . XDOMWrite. . . . . . . . . . XDOMClose . . . . . . . . . XDOMValidate . . . . . . . . . XDOMLocate . . . . . . . . . XDOMLocateNode . . . . . . . XDOMRemove . . . . . . . . . XDOMAppend . . . . . . . . . XDOMInsert . . . . . . . . . XDOMReplace . . . . . . . . . XDOMAddChild . . . . . . . . XDOMClone . . . . . . . . . XDOMTransform . . . . . . . . XDOMGetNodeValue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-3 7-3 7-3 7-4 7-5 7-7 7-11 7-11 7-12 7-13 7-14 7-15 7-16 7-18 7-19 7-25 7-26 7-28 7-29 7-31 7-32 7-33 7-35
vi UniVerse BASIC Extensions
XDOMGetNodeType . . XDOMGetAttribute . . . XDOMGetOwnerDocument XDOMGetUserData . . . XDOMSetNodeValue . . XDOMSetUserData . . . XMLGetError . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
7-36 7-37 7-38 7-39 7-40 7-41 7-42
Chapter 8
Data Transfer Between XML Documents and UniVerse Files

Transferring Data From XML to the Database . . . . . . Populating the Database . . . . . . . . . . . . . . . Populating the Database from TCL . . . . . . . . . . Populating the Database Using the UniVerse BASIC XMAP API The XMAP API. . . . . . . . . . . . . . . . . . XMAPOpen Function . . . . . . . . . . . . . . XMAPClose Function . . . . . . . . . . . . . . XMAPCreate Function . . . . . . . . . . . . . . XMAPReadNext Function . . . . . . . . . . . . . XMAPAppendRec Function . . . . . . . . . . . . XMAPToXMLDoc Function . . . . . . . . . . . . Examples . . . . . . . . . . . . . . . . . . Transferring Data from the Database to XML . . . . . . . . Creating an XML Document from TCL. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-3 8-11 8-11 8-13 8-14 8-14 8-15 8-16 8-17 8-18 8-19 8-20 8-23 8-23
Chapter 9
The XML/DB Tool

Installing the XML/DB Tool . . . . . Create the DTD or XML Schema . . . Using the XML/DB Tool . . . . . . Create Server Definition . . . . Connect to Server . . . . . . Creating a DTD . . . . . . . . . Creating or Displaying an XML Schema . Create a Mapping File . . . . . . . Create Relationship . . . . . . Mapping All Matching Elements . . Mapping to Multiple UniVerse Files . Defining Related Tables . . . . Options . . . . . . . . . . . Define How to Treat Empty Strings . Define Date Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-3 9-9 9-10 9-11 9-13 9-16 9-18 9-20 9-25 9-27 9-29 9-31 9-35 9-35 9-36
Table of Contents vii
Specify How to Treat Namespace . . Define Namespace . . . . . . . Define Cascade Rules . . . . . . Choose How To Treat Existing Records Importing and Exporting Mapping Files. . Importing a Mapping File . . . . Exporting a Mapping File . . . . XML/DB Tool Logging . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
9-36 9-36 9-36 9-37 9-38 9-39 9-41 9-43
Appendix A Appendix B
MQSeries API for UniData and UniVerse Reason Codes The U2XMAP File
Mapping Root . . . . . . . . . . . . . . . . . . A-2
viii UniVerse BASIC Extensions
C:\Program Files\Adobe\FrameMaker7.0\UniVerse
Preface
This manual describes the following extensions to UniVerse BASIC: Chapter 1, Using the Socket Interface, discusses the UniVerse BASIC Socket API, which provides the capability of interacting with an application running on another mafhine via the sockets interface. Chapter 2, Using CallHTTP, discusses using CallHTTP with UniVerse. CallHTTP provides customers with the capability of interacting with a web server from UniVerse BASIC through the standard HTTP protocol. In order to effectively use the CallHTTP functions, you should have a working knowledge of the HTTP standard. Chapter 3, Using WebSphere MQ with UniVerse, describes how to set up and configure the WebSphere MQ API for UniVerse. Chapter 4, Creating XML Documents, describes how to create XML documents from RetrieVe, UniVerse BASIC, and UniVerse SQL Chapter 5, Receiving XML Documents, describes how to receive an XML document, then read the document through UniVerse BASIC, and execute UniVerse BASIC commands against the XML data. Chapter 6, The Simple Object Access Protocol, describes how to use the Simple Object Access Protocol (SOAP), an XML-based protocol for exchanging structured information in a distributed environment, with UniData. Chapter 7, The Document Object Model, describes the Document Object Model (DOM), a standard way for you to manipulate XML documents. You can use the DOM API to delete, remove, and update an XML document, as well as create new XML documents. Chapter 8, Data Transfer Between XML Documents and UniVerse Files, describes the XMLDB data transfer capability, which extends the existing XML support in UniData. It consists of the data transfer utilities and the UniBasic XMAP API. The data transfer utilities consist of two TCL commands, XML.TODB and DB.TOXML, and two UniBasic functions, XMLTODB() and DBTOXML(). Chapter 9, The XML/DB Tool, describes the XML/DB tool, which enables you to create a mapping file to use when creating XML documents from the UniVerse database, or when extracting data from an XML document and updating the UniVerse database.
ix
C:\Program Files\Adobe\FrameMaker7.0\UniVerse 10.2\basicext\Preface 9/22/06
Documentation Conventions
This manual uses the following conventions:
Convention Bold Usage In syntax, bold indicates commands, function names, and options. In text, bold indicates keys to press, function names, menu selections, and MS-DOS commands. In syntax, uppercase indicates UniVerse commands, keywords, and options; BASIC statements and functions; and SQL statements and keywords. In text, uppercase also indicates UniVerse identifiers such as filenames, account names, schema names, and Windows platform filenames and pathnames. In syntax, italic indicates information that you supply. In text, italic also indicates UNIX commands and options, filenames, and pathnames. Courier indicates examples of source code and system output. In examples, courier bold indicates characters that the user types or keys the user presses (for example, <Return>). Brackets enclose optional items. Do not type the brackets unless indicated. Braces enclose nonoptional items from which you must select at least one. Do not type the braces. A vertical bar separating items indicates that you can choose only one item. Do not type the vertical bar. Three periods indicate that more of the same type of item can optionally follow. A right arrow between menu options indicates you should choose each option in sequence. For example, Choose File Exit means you should choose File from the menu bar, then choose Exit from the File pull-down menu. Item mark. For example, the item mark ( I ) in the following string delimits elements 1 and 2, and elements 3 and 4: 1I2F3I4V5 Documentation Conventions x UniVerse BASIC Extensions
UPPERCASE
Italic
Courier Courier Bold
[] {}
itemA | itemB ...
Convention
F
Usage Field mark. For example, the field mark ( F ) in the following string delimits elements FLD1 and VAL1: FLD1FVAL1VSUBV1SSUBV2 Value mark. For example, the value mark ( V ) in the following string delimits elements VAL1 and SUBV1: FLD1FVAL1VSUBV1SSUBV2 Subvalue mark. For example, the subvalue mark ( S ) in the following string delimits elements SUBV1 and SUBV2: FLD1FVAL1VSUBV1SSUBV2 Text mark. For example, the text mark ( T ) in the following string delimits elements 4 and 5: 1F2S3V4T5 Documentation Conventions (Continued)
The following conventions are also used: Syntax definitions and examples are indented for ease in reading. All punctuation marks included in the syntaxfor example, commas, parentheses, or quotation marksare required unless otherwise indicated. Syntax lines that do not fit on one line in this manual are continued on subsequent lines. The continuation lines are indented. When entering syntax, type the entire syntax entry, including the continuation lines, on the same input line.
xi
UniVerse Documentation
UniVerse documentation includes the following: UniVerse Installation Guide: Contains instructions for installing UniVerse 10.2. UniVerse New Features Version 10.2: Describes enhancements and changes made in the UniVerse 10.2 release for all UniVerse products. UniVerse BASIC: Contains comprehensive information about the UniVerse BASIC language. It includes reference pages for all BASIC statements and functions. It is for experienced programmers. UniVerse BASIC Commands Reference: Provides syntax, descriptions, and examples of all UniVerse BASIC commands and functions. UniVerse BASIC Extensions: Describes the following extensions to UniVerse BASIC: UniVerse BASIC Socket API, Using CallHTTP, Using WebSphere MQ with UniVerse, using XML with UniVerse, and the XML/DB Tool. UniVerse BASIC SQL Client Interface Guide: Describes how to use the BASIC SQL Client Interface (BCI), an interface to UniVerse and non-UniVerse databases from UniVerse BASIC. The BASIC SQL Client Interface uses ODBC-like function calls to execute SQL statements on local or remote database servers such as UniVerse, IBM, SYBASE, or INFORMIX. This book is for experienced SQL programmers. Administering UniVerse: Describes tasks performed by UniVerse administrators, such as starting up and shutting down the system, system configuration and maintenance, system security, maintaining and transferring UniVerse accounts, maintaining peripherals, backing up and restoring files, and managing file and record locks, and network services. This book includes descriptions of how to use the UniVerse Admin program on a Windows client and how to use shell commands on UNIX systems to administer UniVerse. Using UniAdmin: Describes the UniAdmin tool, which enables you to configure UniVerse, configure and manager servers and databases, and monitor UniVerse performance and locks. UniVerse Transaction Logging and Recovery: Describes the UniVerse transaction logging subsystem, including both transaction and warmstart logging and recovery. This book is for system administrators.
xii
UniVerse Security Features: Describes security features in UniVerse, including configuring SSL through UniAdmin, using SSL with the CallHttp and Socket interfaces, using SSL UniObjects for Java, and automatic date encryption. UniVerse System Description: Provides detailed and advanced information about UniVerse features and capabilities for experienced users. This book describes how to use UniVerse commands, work in a UniVerse environment, create a UniVerse database, and maintain UniVerse files. UniVerse User Reference: Contains reference pages for all UniVerse commands, keywords, and user records, allowing experienced users to refer to syntax details quickly. Guide to RetrieVe: Describes RetrieVe, the UniVerse query language that lets users select, sort, process, and display data in UniVerse files. This book is for users who are familiar with UniVerse. Guide to ProVerb: Describes ProVerb, a UniVerse processor used by application developers to execute prestored procedures called procs. This book describes tasks such as relational data testing, arithmetic processing, and transfers to subroutines. It also includes reference pages for all ProVerb commands. Guide to the UniVerse Editor: Describes in detail how to use the Editor, allowing users to modify UniVerse files or programs. This book also includes reference pages for all UniVerse Editor commands. UniVerse NLS Guide: Describes how to use and manage UniVerses National Language Support (NLS). This book is for users, programmers, and administrators. UniVerse SQL Administration for DBAs: Describes administrative tasks typically performed by DBAs, such as maintaining database integrity and security, and creating and modifying databases. This book is for database administrators (DBAs) who are familiar with UniVerse. UniVerse SQL User Guide: Describes how to use SQL functionality in UniVerse applications. This book is for application developers who are familiar with UniVerse. UniVerse SQL Reference: Contains reference pages for all SQL statements and keywords, allowing experienced SQL users to refer to syntax details quickly. It includes the complete UniVerse SQL grammar in Backus Naur Form (BNF).
xiii
Related Documentation
The following documentation is also available: UniVerse GCI Guide: Describes how to use the General Calling Interface (GCI) to call subroutines written in C, C++, or FORTRAN from BASIC programs. This book is for experienced programmers who are familiar with UniVerse. UniVerse ODBC Guide: Describes how to install and configure a UniVerse ODBC server on a UniVerse host system. It also describes how to use UniVerse ODBC Config and how to install, configure, and use UniVerse ODBC drivers on client systems. This book is for experienced UniVerse developers who are familiar with SQL and ODBC. UV/NET II Guide: Describes UV/Net II, the UniVerse transparent database networking facility that lets users access UniVerse files on remote systems. This book is for experienced UniVerse administrators. UniVerse Guide for Pick Users: Describes UniVerse for new UniVerse users familiar with Pick-based systems. Moving to UniVerse from PI/open: Describes how to prepare the PI/open environment before converting PI/open applications to run under UniVerse. This book includes step-by-step procedures for converting INFO/BASIC programs, accounts, and files. This book is for experienced PI/open users and does not assume detailed knowledge of UniVerse.
xiv UniVerse BASIC Extensions
API Documentation
The following books document application programming interfaces (APIs) used for developing client applications that connect to UniVerse and UniData servers. Administrative Supplement for APIs: Introduces IBMs seven common APIs, and provides important information that developers using any of the common APIs will need. It includes information about the UniRPC, the UCI Config Editor, the ud_database file, and device licensing. UCI Developers Guide: Describes how to use UCI (Uni Call Interface), an interface to UniVerse and UniData databases from C-based client programs. UCI uses ODBClike function calls to execute SQL statements on local or remote UniVerse and UniData servers. This book is for experienced SQL programmers. IBM JDBC Driver for UniData and UniVerse: Describes UniJDBC, an interface to UniData and UniVerse databases from JDBC applications. This book is for experienced programmers and application developers who are familiar with UniData and UniVerse, Java, JDBC, and who want to write JDBC applications that access these databases. InterCall Developers Guide: Describes how to use the InterCall API to access data on UniVerse and UniData systems from external programs. This book is for experienced programmers who are familiar with UniVerse or UniData. UniObjects Developers Guide: Describes UniObjects, an interface to UniVerse and UniData systems from Visual Basic. This book is for experienced programmers and application developers who are familiar with UniVerse or UniData, and with Visual Basic, and who want to write Visual Basic programs that access these databases. UniObjects for Java Developers Guide: Describes UniObjects for Java, an interface to UniVerse and UniData systems from Java. This book is for experienced programmers and application developers who are familiar with UniVerse or UniData, and with Java, and who want to write Java programs that access these databases. UniObjects for .NET Developers Guide: Describes UniObjects, an interface to UniVerse and UniData systems from .NET. This book is for experienced programmers and application developers who are familiar with UniVerse or UniData, and with .NET, and who want to write .NET programs that access these databases.
xv
Using UniOLEDB: Describes how to use UniOLEDB, an interface to UniVerse and UniData systems for OLE DB consumers. This book is for experienced programmers and application developers who are familiar with UniVerse or UniData, and with OLE DB, and who want to write OLE DB programs that access these databases.
xvi UniVerse BASIC Extensions
1Administering UniData on Windows NT or Windows 2000 0
Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta
Chapter
Using the Socket Interface
1
. . . . . . . . . . . . . . . 1-3 1-7 1-8 1-9 1-11 1-12 1-14 1-16 1-18 1-20 1-23 1-24 1-26 1-28 1-30
Socket Function Error Return Codes . . . . . . . . Getting a Socket Error Message . . . . . . . . . . Opening a Socket . . . . . . . . . . . . . . Opening a Secure Socket . . . . . . . . . . . . Closing a Socket . . . . . . . . . . . . . . . Getting Information From a Socket . . . . . . . . . Reading From a Socket . . . . . . . . . . . . . Writing to a Socket . . . . . . . . . . . . . . Setting the Value for a Socket Option . . . . . . . . Getting the Value of a Socket Option . . . . . . . . Initializing a Server Side Socket Connection . . . . . . Initializing a Secure Server Side Socket Connection. . . . Accepting an Incoming Connection Attempt on the Server Side Protocol Logging. . . . . . . . . . . . . . . Socket API Example . . . . . . . . . . . . .
. . . . . . . . . . . . . . .
. . . . . . . . . . . . . . .
. . . . . . . . . . . . . . .
C:\Program Files\Adobe\FrameMaker7.0\UniVerse 10.2\basicext\Ch1TOC.fm September 22, 2006 3:24 pm Administering UniData on Windows NT or Windows 2000
C:\Program Files\Adobe\FrameMaker7.0\UniVerse 10.2\basicext\Ch1.fm 9/22/06
The UniVerse BASIC Socket API provides the user with the capability of interacting with an application running on another machine via the sockets interface. The Socket API enables you to write distributed UniVerse applications. For example, one application, written in the server side socket interface can function as the server while others can function as clients. The server and the clients can cooperate on tasks through socket communication. This is an efficient way for UniVerse BASIC applications to communicate, and is easy to implement. The Socket functions are not in order of how they would normally be implemented. Refer to Socket API Example for more information on using the Socket API functions.
1-2 UniVerse BASIC Extensions
Socket Function Error Return Codes

The following error return codes are used for all socket-related functions described below. Note that only numeric code should be used in UniVerse BASIC programs. The following table describes each error code and its meaning.
Error Code 0 -SCK_ENOERROR 1 - SCK_ENOINITIALISED Definition No error. On Windows platforms, a successful WSAStartup() call must occur before using this function. The network subsystem has failed. The addrlen parameter is too small or addr is not a valid part of the user address space. The socket is not connected. The (blocking) call was cancelled. (NT: through WSACancelBlockign-Call). A blocking Windows Sockets 1.1 call is in progress, or the service provider is still processing a callback function. This can be caused by several conditions. The listen function was not invoked prior to accept, the socket has not been bound with bind, an unknown flag was specified, or MSG_OOB was specified for a socket with SO_OOBINLINE enabled or (for byte stream sockets only) len was zero or negative. The queue is nonempty upon entry to accept and there are no descriptors available. No buffer space is available. The descriptor is not a socket. Socket Function Error Return Codes
2 - SCK_ENETDOWN 3 - SCK_EFAULT 4 - SCK_ENOTCONN 5 - SCK_EINTR 6 - SCK_EINPROGRESS
7 - SCK_EINVAL
8 - SCK_EMFILE 9 - SCK_ENOBUFS 10 - SCK_ENOTSOCK
1-3
Error Code 11 - SCK_EOPNOTSUPP 12 - SCK_EWOULDBLOCK 13 - SCK_ENETRESET
Definition The referenced socket is not a type that supports connection-oriented service. The socket is marked as nonblocking and the requested operation would block. The connection has been broken due to the keepalive activity detecting a failure while the operation was in progress. The socket has been shut down. (For recv()) The message was too large to fit into the specified buffer and was truncated, or (for send()) the socket is message oriented, and the message is larger than the maximum supported by the underlying transport. The virtual circuit was terminated due to a timeout or other failure. The connection has been dropped, because of a network failure or because the system on the other end went down without notice. The virtual circuit was reset by the remote side executing a hard or abortive close. For UPD sockets, the remote host was unable to deliver a previously sent UDP datagram and responded with a Port Unreachable ICMP packet. The application should close the socket as it is no longer usable. The requested address is a broadcast address, but the appropriate flag was not set. Call setSocketOption() with the BROADCAST parameter to allow the use of the broadcast address. The remote host cannot be reached from this host at this time. The option is unknown or unsupported for the specified provider or socket.
14 - SCK_ESHUTDOWN 15 - SCK_EMSGSIZE
16 - SCK_ETIMEDOUT 17 - SCK_ECONNABORTED
18 - SCK_ECONNRESET
19 - SCK_EACCES
20 - SCK_EHOSTUNREACH 21 - SCK_ENOPROTOOPT
Socket Function Error Return Codes (Continued) 1-4 UniVerse BASIC Extensions
Error Code 22 - SCK_ESYSNOTREADY 23 -SCK_EVER NOTSUPPORTED
Definition Indicates that the underlying network subsystem is not ready for network communication. The version of Windows Sockets support requested is not provided by this particular Windows Sockets implementation. Limit on the number of tasks supported by the Windows Sockets implementation has been reached. The specified address family is not supported. The specifed protocol is not supported. The specified protocol is the wrong type for this socket. The specified socket type is not supported in this address family. Descriptor socket is not valid. Authoritative Answer Host not found. Nonauthoritative Host not found, or server failure. A nonrecoverable error occurred. Valid name, no data record of requested type. Attempt to connect datagram socket to broadcast address failed because setSocketOption() BROADCAST is not enabled. A process on the machine is already bound to the same fully-qualified address and the socket has not been marked to allow address reuse with REUSEADDR. (See the REUSEADDR socket option under setSocketOption()). The specified address is not a valid address for this machine.
24 - SCK_EPROCLIM
25 - SCK_EAFNOSUPPORT 26 - SCK_EPROTONOSUPPORT 27 - SCK_EPROTOTYPE 28 - SCK_ESOCKTNOSUPPORT 29 - SCK_EBADF 30 - SCK_EHOST_NOT_FOUND 31 - SCK_ETRY_AGAIN 32 - SCK_ENO_RECOVERY 33 - SCK_ENO_RECOVERY 34 - SCK_EACCESS
35 - SCK_EADDRINUSE
36 - SCK_EADDRNOTAVAIL
Socket Function Error Return Codes (Continued)
1-5
Error Code 37 - SCK_EISCONN 38 - SCK_EALREADY 39 - SCK_ECONNREFUSED 40 - SCK_EMALLOC 41 - SCK_ENSLMAP 42 - SCK_EUNKNOWN 101 102 103 104 105 106 107 108
Definition The socket is already connected. A nonblocking connect call is in progress on the specified socket. The attempt to connect was forcefully rejected. Memory allocation error. NLS map not found, or unmapped characters encountered. Other unknown errors. Invalid security context handle. SSL/TLS handshake failure (unspecified, peer is not SSL aware). Requires client authentication but does not have a certificate in context. Unable to authenticate server. Client authentication failure. Peer not speaking SSL. Encryption error. Decryption error. Socket Function Error Return Codes (Continued)
Getting a Socket Error Message

Use the getSocketErrorMessage() function to translate an error code into a text error message. This function works with all socket functions. The return status of those functions can be passed into this function to get ther corresponding error message.
Syntax
getSocketErrorMessage(errCode, errMsg)
Parameters
The following table describes each parameter of the syntax.
Parameter errCode errMsg Description The status return code sent by the socket functions. A string containing corresponding error text. getSocketErrorMessage Parameters
The following table describes the return status of each mode.

Return Code 0 1 Description Success. Invalid error code. Return Code Status
1-7
Opening a Socket
Use the openSocket() function to open a socket connection in a specified mode and return the status.
Syntax
openSocket(name_or_IP, port, mode, timeout, socket_handle)
Parameters
Parameter name_or_IP port mode Description DNS name (x.com) or IP address of a server. Port number. If the port number is specified as a value <= 0, CallHTTP defaults to a port number of 40001. 2: non-blocking mode 1: blocking mode timeout socket_handle The timeout value, expressed in milliseconds. If you specify mode as 0, timeout will be ignored. A handle to the open socket. openSocket Parameters

Return Code 0 Non-zero Description Success. See Socket Function Error Return Codes. Return Code Status
Opening a Secure Socket

Use the openSecureSocket() function to open a secure socket connection in a specified mode and return the status. This function behaves exactly the same as the openSocket() function, except that it returns the handle to a socket that transfers data in a secured mode (SSL/TLS). All parameters (with the exception of context) have the exact meaning as the openSocket() parameters. Context must be a valid security context handle. Once the socket is opened, any change in the associated security context will not affect the established connection.
Syntax
openSecureSocket(name_or_IP, port, mode, timeout, socket_handle, context)
Parameters
Parameter name_or_IP port mode Description DNS name (x.com) or IP address of a server. Port number. If the port number is specified as a value <= 0, CallHTTP defaults to a port number of 40001. 0:non-blocking mode 1:blocking mode timeout socket_handle context The timeout value, expressed in milliseconds. If you specify mode as 0, timeout will be ignored. A handle to the open socket. A handle to the security context openSecureSocket Parameters
1-9

Return Code 0 1-41 101 102 103 104
Description Success. See Socket Function Error Return Codes. Invalid security context handle. SSL/TLS handshake failure (unspecified, peer is not SSL aware). Requires client authentication but does not have a certificate in the security context. Unable to authenticate server. Return Code Status
1-10
Closing a Socket
Use the closeSocket() function to close a socket connection.
Syntax
closeSocket(socket_handle) Where socket_handle is the handle to the socket you want to close. The following table describes the status of each return code.
Return Code 0 Non-zero Description Success. See Socket Function Error Return Codes. Return Code Status
1-11
Getting Information From a Socket

Use the getSocketInformation() function to obtain information about a socket connection.
Syntax
getSocketInformation(socket_handle, self_ or_ peer, socket_info)
Parameters
Parameter socket_handle self_ or_ peer Description The handle to the open socket. Get information on the self end or the peer end of the socket. Specify 0 to return information from the peer end and non-zero for information from the self end. Dynamic Array containing information about the socket connection. Forinformation about the elements of this dynamic array, see the following table. getSocketInformation Parameters
socket_info
1-12
The following table describes each element of the socket_info dynamic array. The Element 1 2 3 4 5 Description Open or closed Name or IP Port number Secure or nonsecure Blocking mode
following table describes the status of each return code.

Element 1 2 3 4 5 Description Open or closed Name or IP Port number Secure or nonsecure Blocking mode Return Code Status
1-13
Reading From a Socket

Use the readSocket() function to read data in the socket buffer up to max_read_size characters.
Syntax
readSocket(socket_handle, socket_data, max_read_size, time_out, blocking_mode, actual_read_size)
Parameters
Parameter socket_handle socket_data max_read_size time_out blocking_mode Description The handle to the open socket. The data to be read from the socket. The maximum mumber of characters to return. If this is 0, then the entire buffer should be returned. The time (in milliseconds) before a return in blocking mode. This is ignored for non-blocking read. 0:using current mode 1:blocking 2:non-blocking actual_read_size The number of characters actually read. -1 if error. readSocket Parameters
1-14

Mode Non-Blocking Return Status The function will return immediately if there is no data in the socket. If themax_read_size parameter is greater than the socket buffer then just the socket buffer will be returned. If there is no data in the socket, the function will block until data is put into the socket on the other end. It will return up to the max_read_size character setting. Return Mode Status
Blocking
The following table describes the status of each return code.

Return Code 0 1-41 107 108 Status Success. See Socket Function Error Return Codes. Encryption error. Decryption error. Return Code Status
1-15
Writing to a Socket
Use the writeSocket() function to write data to a socket connection.
Syntax
writeSocket(socket_handle, socket_data, time_out, blocking_mode, actual_write_size)
Parameters
Parameter socket_handle socket_data time_out blocking_mode Description The handle to the open socket. The data to be written to the socket. The allowable time (in milliseconds) for blocking. This is ignored for a nonblocking write. 0:using current mode 1:blocking 2:nonblocking actual_write_size The number of characters actually written. writeSocket Parameters

Mode Blocking Non-Blocking Return Status The function will return only after all characters in socket_data are written to the socket. The function may return with fewer character written than the actual length (in the case that the socket is full). Return Mode Status
1-16

Return Code 0 1-41 107 108 Status Success. See Socket Function Error Return Codes. Encryption error. Decryption error. Return Code Status
1-17
Setting the Value for a Socket Option

The setSocketOptions() function sets the current value for a socket option associated with a socket of any type.
Syntax
setSocketOptions(socket_handle, options)
Parameters
Parameter socket_handle Description The socket handle from openSocket(), acceptSocket(), or initServerSocket(). Dynamic Array containing information about the socket options and their current settings. The dynamic array is configured as: optName1<VM>optValue1a[<VM>optValue1b]<FM> optName2<VM>optValue2a[<VM>optValue2b]<FM> optName3... Where optName is specified by the caller and must be an option name string listed below. The first optValue specifies if the option is ON or OFF and must be one of two possible values: 1 for ON or 2 for OFF. The second optValue is optional and may hold additional data for a specific option. Currently, for the LINGER option it contains the delayed time (in milliseconds) before closing the socket. For all other options, it should not be specified as it will be ignored. setSocketOptions Parameters
options
1-18
The following table describes the available options (case-sensitive) for setSocketOptions.
Option DEBUG REUSEADDR KEEPALIVE DONTROUTE LINGER BROADCAST OOBINLINE SNDBUF RCVBUF Description Enable/disable recording of debug information. Enable/disable the reuse of a location address (default) Enable/disable keeping connections alive. Enable/disable routing bypass for outgoing messages. Linger on close if data is present. Enable/disable permission to transmit broadcast messages. Enable/disable reception of out-of-band data in band. Set buffer size for output (the default value depends on OS type). Set buffer size for input (the default value depends on OS type). setSocketOptions Options

Return Code 0 Non-zero Status Success. See Socket Function Error Return Codes. Return Code Status
1-19
Getting the Value of a Socket Option

The getSocketOptions() function gets the current value for a socket option associated with a socket of any type.
Syntax
getSocketOptions(socket_handle, Options)
1-20
Parameters
Parameter socket_handle options Description The socket handle from openSocket(), acceptSocket(), or initServer-Socket(). A dynamic array containing information about the socket options and their current settings. When querying for options, the dynamic array is configured as: optName1<FM> optName2<FM> optName... When the options are returned, the dynamic array is configured as: optName1<VM>optValue1a[<VM>optValue1b]<FM> optName2<VM>optValue2a[<VM>optValue2b]<FM> optName3... Where optName contains an option name string listed below. The first optValue describes if the option is ON or OFF and must be one of two possible values: 1 for ON or 2 for OFF. The second optValue is optional and may hold additional data for a specific option. Currently, for option LINGER, it contains the delayed time (in milliseconds) before closing the socket. getSocketOptions Parameters
1-21
The following table describes the available options (case-sensitive) for getSocketOptions().
Option DEBUG REUSEADDR KEEPALIVE DONTROUTE LINGER BROADCAST OOBINLINE SNDBUF RCVBUF TYPE ERROR Description Enable/disable recording of debug information. Enable/disable the reuse of a location address (default). Enable/disable keeping connections alive. Enable/disable routing bypass for outgoing messages. Linger on close if data is present. Enable/disable permission to transmit broadcast messages. Enable/disable reception of out-of-band data in band. Get buffer size for output (default 4KB). Get buffer size for input (default 4KB). Get the type of the socket. Refer to the socket.h file for more information. Get and clear error on the socket. getSocketOptions Options

Return Code 0 Non-zero Status Success. See Socket Function Error Return Codes. Return Code Status
1-22
Initializing a Server Side Socket Connection

Use the initServerSocket() function to create a connection-oriented (stream) socket. Associate this socket with an address (name_or_IP) and port number (port), and specify the maximum length the queue of pending connections may grow to.
Syntax
initServerSocket(name_or_IP, port, backlog, svr_socket)
Parameters
Parameter name_or_IP Description DNS name (x.com) or IP address of a server or empty. Empty is equivalent to INADDR_ANY which means the system will choose one for you. Generally, this parameter should be left empty. Port number. If the port number is specified as a value <= 0, CallHTTP defaults to a port number of 40001. The maximum length of the queue of pending connections (for example, concurrent client-side connections). The handle to the server side socket. initServerSocket Parameters
port backlog svr_socket

Return Code 0 Nonzero Status Success. See Socket Function Error Return Codes. Return Code Status
1-23
Initializing a Secure Server Side Socket Connection

Use the initSecureServerSocket() function to create a secured connection-oriented stream server socket. It does exactly the same as the initServerSocket() function except that the connection will be secure. Once the server socket is opened, any change in the associated security context will not affect the opened socket.
Syntax
initSecureServerSocket(name_or_IP, port, backlog, svr_socket, context)
Parameters
Parameter name_or_IP Description DNS name (x.com) or IP address of a server or empty. Empty is equivalent to INADDR_ANY which means the system will choose one for you. Generally, this parameter should be left empty. Port number. If the port number is specified as a value <= 0, CallHTTP defaults to a port number of 40001. The maximum length of the queue of pending connections (for example, concurrent client-side connections). The handle to the server side socket. The handle to the security context. initSecureServerSocket Parameters
port backlog svr_socket context
1-24

Return Code 0 1 - 41 101 Status Success. See Socket Function Error Return Codes. Invalid security context handle. Return Code Status
1-25
Accepting an Incoming Connection Attempt on the Server Side

Use the acceptConnection() function to accept an incoming connection attempt on the server side socket.
Syntax
acceptConnection(svr_socket, blocking_mode, timeout, in_addr, in_name, socket_handle)
Parameters
Parameter svr_socket blocking_mode Description The handle to the server side socket which is returned by initServerSocket(). blocking_mode is one of the following: 0 default (blocking) 1 blocking. If this mode and the current blocking mode of svr_socket is set to blocking, acceptConnection() blocks the caller until a connection request is received or the specified time_out has expired. 2 nonblocking. In this mode, if there are no pending connections present in the queue, acceptConnection() returns an error status code. If this mode, time_out is ignored. time_out Timeout in milliseconds. acceptConnection Parameters
1-26
Parameter in_addr in_name socket_handle
Description The buffer that receives the address of the incoming connection. If NULL, it will return nothing. The variable that receives the name of the incoming connection. If NULL, it will return nothing. The handle to the newly created socket on which the actual connection will be made. The server will use readSocket(), writeSocket(), and so forth with this handle to communicate with the client. acceptConnection Parameters (Continued)

Return Code 0 1-41 102 103 105 106 Status Success. See Socket Function Error Return Codes. SSL Handshake failure. No client certificate. Client authentication failure. Peer not speaking SSL. Return Code Status
1-27
Protocol Logging
This function will start or stop logging and can be used for both the Socket API and CallHTTP API.
Syntax
protocolLogging(log_file, log_action, log_level)
Parameters
Parameter log_file log_action log_level Description The name of the file the logs will be recorded to. The default log file name is httplog and will be created under the current directory. Either ON or OFF. The default is OFF. The detail level of logging from 0 - 10. See table below. protocolLogging Parameters
Level 0 1 2 3 4-10
Detail No logging. Socket open/read/write/close action (no real data) HTTP request: hostinfo(URL) Level 1 logging plus socket data statistics (size, and so forth). Level 2 logging plus all data actually transferred. More detailed status data to assist debugging. protocolLogging Log Levels
1-28

Return Code 0 1 Status Success. Failed to start logging. Return Status
1-29
Socket API Example

The BASIC code example below demonstrates how each function can be used and their order in a typical implementation. The following functions are used in this example: protocolLogging() initServerSocket() openSocket() getSocketInformation() acceptConnection() writeSocket() readSocket() getSocketOptions() setSockeOptions() closeSocket()
1-30
**** Declare variables * reoptVar="DEBUG,REUSEADDR,KEEPALIVE,DONTROUTE,LINGER,OOBINLINE,SND BUF,RCVBUF,TYPE,ERROR" REUSEADDR="1" CONVERT "," TO @FM IN reoptVar POP3=@(0,0) * * * **** Specify Protocol Logging information * RESULT=protocolLogging("","ON",10) CRT "Logging started = ":RESULT * INADDR="" INNAME="" * **** Specify server name and assign handles to each socket * SERVER.IP.ADDRESS="127.0.0.1" ;*myHostName SOCKET.PORT="8555" MODE="1"; * 0=non-blocking, 1=blocking SOCKETHANDLE1="";* Client handle SOCKETHANDLE2="";* Server handle SOCKETHANDLE3="";* Acceptor handle TIMEOUT=10000; * milliseconds * BACKLOG="2048" CRT SERFLAG="-1";* Self end = Server CRT "Starting Servers" * **** Initialize the Server Socket * RESULT=initServerSocket(SERVER.IP.ADDRESS,SOCKET.PORT,BACKLOG,SOCK ETHANDLE2) CRT "Init server 1 result = ":RESULT * **** Get information from the socket * RESULT=getSocketInformation(SOCKETHANDLE2,SERFLAG,SOCKETINFO) CRT "Server Socket Info" CRT "-----------" CRT "Status : ":SOCKETINFO<1,1> CRT "Host : ":SOCKETINFO<1,2> CRT "Port :":SOCKETINFO<1,3> CRT "Secure : ":SOCKETINFO<1,4> CRT "Mode :":SOCKETINFO<1,5> * PEERFLAG="0" * **** Open a Client Socket
1-31
* CRT "Opening Client" RESULT=openSocket(SERVER.IP.ADDRESS,SOCKET.PORT,MODE,TIMEOUT,SOCKE THANDLE1) CRT "Result of client open = ":RESULT * **** Get information from the Client Socket * RESULT=getSocketInformation(SOCKETHANDLE1,PEERFLAG,SOCKETINFO) CRT "Client Socket Info" CRT "-----------" CRT "Status : ":SOCKETINFO<1,1> CRT "Host : ":SOCKETINFO<1,2> CRT "Port :":SOCKETINFO<1,3> CRT "Secure : ":SOCKETINFO<1,4> CRT "Mode :":SOCKETINFO<1,5> CRT "" * **** Accept Connections on Server * CRT "Server Accepting connections" RESULT=acceptConnection(SOCKETHANDLE2,MODE,TIMEOUT,INADDR,INNAME,S OCKETHANDLE3) CRT "Connection ACCEPT Status = ":RESULT CRT * **** Write to and Read from the Socket * SDATLEN="" CDATLEN="" SRDATA="Hello Server with this test to see the display and count" CLDATA="" ACTSIZ="" * RESULT=writeSocket(SOCKETHANDLE1,SRDATA,TIMEOUT,MODE,SDATLEN) CRT "Wrote status = ":RESULT RESULT=readSocket(SOCKETHANDLE3,CLDATA,CDATLEN,TIMEOUT,MODE,ACTSIZ ) CRT "Read status = ":RESULT *CRT CRT " Value of inbuf = ":CLDATA CRT " Actual size of data = ":ACTSIZ CRT " Value of in_addr = ":INADDR CRT " Value of in_name = ":INNAME CRT * **** Set the socket options * *wroptVar=SNDBUF:@VM:8192:@FM:RCVBUF:@VM:16384 RESULT=setSocketOptions(SOCKETHANDLE2, wroptVar) CRT " Set options is : ":RESULT * **** Get the socket options *
1-32
RESULT=getSocketOptions(SOCKETHANDLE1, reoptVar) PRINT "Result of get socket handle Options is : ":RESULT PRINT "get socket options list" LIMIT = DCOUNT(reoptVar,@FM) FOR I = 1 TO LIMIT PRINT FMT(reoptVar<I,1>,"L#10"),reoptVar<I,2>,reoptVar<I,3> NEXT I CRT * **** Close each of the Sockets * RESULT=closeSocket(SOCKETHANDLE1) CRT "result of close client = ":RESULT RESULT=closeSocket(SOCKETHANDLE2) CRT "result of close server = ":RESULT RESULT=closeSocket(SOCKETHANDLE3) CRT "result of close Acceptor = ":RESULT CRT END
1-33
Chapter
Using CallHTTP
2
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-3 2-6 2-7 2-10 2-12 2-14 2-16
Configuring the Default HTTP Settings . Getting the Current HTTP Default Settings Creating an HTTP Request . . . . . Creating a Secure HTTP Request . . . Setting Additional Headers for a Request . Adding a Parameter to the Request . . . Submitting a Request . . . . . . .
CallHTTP provides users with the capability of interacting with a web server from UniVerse BASIC through the standard HTTP protocol. In order to effectively use the CallHTTP functions, you should have a working knowledge of the HTTP standard. Internet and web technologies have rapidly changed the way business is conducted by enterprises of all categories. E-commerce is increasingly becoming an essential part of any business. Many companies desire the capability to call out to the web from UniVerse BASIC so that their now stand-alone applications can be integrated with other applications through the web. There are many scenarios where this capability can be beneficial. For example, you may want to integrate a general ledger application with a third-party application that has already been web-enabled. When an account number is given, the general ledger application has to send it to the web application through an HTTP request for validation. The web application then returns a confirmation to the UniVerse BASIC application. HTTP is a complex standard with a large number of components and methods. The goal for CallHTTP is to provide a basic yet general implementation that enables UniVerse BASIC to act as an HTTP client so that data can be exchanged between a UniVerse BASIC application and a web server. CallHTTP provides the plumbing for users to build a specific client, not make UniVerse BASIC a browser of its own. CallHTTP is implemented with the Socket Interface as its network transport, and this lower level API is also available for direct access by the user.
6-2
Configuring the Default HTTP Settings

The setHTTPDefault function configures the default HTTP settings, including proxy server and port, buffer size, authentication credential, HTTP version, and request header values. These settings are used with every HTTP request that follows.
Syntax
setHTTPDefault(option, value) If you require all outgoing network traffic to go through a proxy server, setHTTPDefault() should be called with value containing the proxy server name or IP address, as well as the port (if other than the default of 80).
Parameters
Parameter option value Description A string containing an option name. See the table below for the options currently defined. A string containing the appropriate option value. setHTTPDefault Parameters
The following table describes the available options for setHTTPDefault.

Option Description PROXY_NAME PROXY_PORT VERSION Name or IP address of the proxy server. The port number to be used on the proxy server. This only needs to be specified if the port is other than the default of 80. The version of HTTP to be used. The default version is 1.0, but it can be set to 1.1 for web servers that understand the newer protocol. The string should be 1.0 or 1.1. setHTTPDefault Options
6-3 UniVerse BASIC
Option Description BUFSIZE The size of the buffer for HTTP data transfer between UniVerse and the web server. The default is 4096. The buffer size can be increased to improve performance. It should be entered as an integer greater than or equal to 4096. The user name and password to gain access. The string should be user-name:password. Default Basic authentication can also be set. If a request is denied (HTTP status 401/407), UniVerse BASIC will search for the default credential to automatically resubmit the request. The header to be sent with the HTTP request. If default_headers contains an empty string, any current userspecified default header will be cleared. Currently, the only default header UniVerse BASIC sets automatically is UserAgent UniVerse 9.6. If you do not want to send out this header you should overwrite it with setHTTPDefault(). Per RFC 2616, for net politeness, an HTTP client should always send out this header. UniBasic will also send a date/time stamp with every HTTP request. According to RFC 2616, the stamp represents time in Universal Time (UT) format. A header should be entered as a dynamic array in the form of <Header-Name>@ VM<HeaderValue>@Fm<HeaderName>@VM<HeaderValue>. setHTTPDefault Options (Continued)
AUTHENTICATE
HEADERS

Return Code 0 1 2
Status Success Invalid option. Invalid value.
Return Code Status
6-4
Note: All defaults set by setHTTPDefault() will be in effect until the end of the current UniVerse session. If you do not want the setting to affect subsequent programs, you will need to clear it before exiting the current program. If the user wishes to set the Authorization or Proxy-Authorization header as defaults, see the description under setRequestHeader(). To clear the default settings, pass an empty string with PROXY_NAME, AUTHENTICATE and HEADERS, and 0 for PROXY_PORT and BUFSIZE.
6-5 UniVerse BASIC
Getting the Current HTTP Default Settings

The getHTTPDefault function returns the default values of the HTTP settings. See the section under setHTTPDefault for additional information.
Syntax
getHTTPDefault(option, value)
Parameters
The following table describes each parameter of the syntax:
Parameter option Description Currently, the following options are defined: PROXY_NAME PROXY_PORT VERSION BUFSIZE AUTHENTICATE HEADERS value A string containing the appropriate option value. getHTTPDefault Parameters

Return Code 0 1 Status Success. Invalid option. Return Code Status
6-6
Creating an HTTP Request

The createRequest function creates an HTTP request and returns a handle to the request.
Syntax
createRequest(URL, http_method, request_handle)
Parameters
Parameter URL Description A string containing the URL for a resource on a web server. An accepted URL must follow the specified syntax defined in RFC 1738. The general format is: http://<host>:<port>/<path>?<searchpart>. The host can be either a name string or IP address. The port is the port number to connect to, which usually defaults to 80 and is often omitted, along with the preceding colon. The path tells the web server which file you want, and, if omitted, means home page for the system. The searchpart can be used to send additional information to a web server. A string which indicates the method to be performed on the resource. See the table below for the available (case-sensitive) methods. A handle to the request object. createRequest Parameters
http_method request_handle
6-7 UniVerse BASIC
The following table describes the available methods for http_method.
Method GET
Description Retrieves whatever information, in the form of an entity, identified by the Request-URI. If the Request-URI refers to a data-producing process, it is the produced data which shall be returned as the entity in the response and not the source text of the process, unless that text happens to be the output of the process. [:<MIME-type>] For this method, it can also have an optional MIMEtype to indicate the content type of the data the request intends to send. If no MIME-type is given, the default content type will be application/x-www-form-urlencoded. Currently, only multipart/formdata is internally supported, as described in function addRequestParameter() and submitRequest(), although other multipart/* data can also be sent if the user can assemble it on his/her own. (The multipart/form-data format itself is thoroughly described in RFC 2388).
POST
HEAD
The HEAD method is identical to GET except that the server MUST NOT return a message-body in the response. The metainformation contained in the HTTP headers in response to a HEAD request SHOULD be identical to the information sent in response to a GET request. This method can be used for obtaining metainformation about the entity implied by the request without transferring the entity-body itself. This method is often used for testing hypertext links for validity, accessibility, and recent modification. The OPTIONS method represents a request for information about the communication options available on the request/response chain identified by the Request-URI. This method allows the client to determine the options and/or requirements associated with a resource, or the capabilities of a server, without implying a resource action or initiating a resource retrieval. HTTP 1.1 and later.
OPTIONS
DELETE
The DELETE method requests that the origin server delete the resource identified by the Request-URI. HTTP 1.1 and later. http_method Methods
6-8
Method TRACE PUT CONNECT
Description The TRACE method is used to invoke a remote, application-layer loopback of the request message. HTTP 1.1 and later. The PUT method requests that the enclosed entity be stored under the supplied Request-URI. HTTP 1.1 and later but not supported. /* HTTP/1.1 and later but not supported */ http_method Methods (Continued)

Return Code 0 1 2 Status Success. Invalid URL (Syntactically). Invalid method (For HTTP 1.0, only GET/POST/HEAD) Return Code Status
Note: If URL does include a searchpart, it must be in its encoded format (space is converted into +, and other non-alphanumeric characters are converted into %HH format. See addRequestParameter() for more details). However, host and path are allowed to have these unsafe characters. UniVerse BASIC will encode them before communicating with the web server.
6-9 UniVerse BASIC
Creating a Secure HTTP Request

The createSecureRequest function behaves exactly the same as the createRequest() function, except for the fourth parameter, a handle to a security context, which is used to associate the security context with the request. If the URL does not start with https then the parameter is ignored. If the URL starts with https but an invalid context handle or no handle is provided, the function will abort and return with an error status.
Syntax
createSecureRequest(URL, http_method, request_handle, security_context)
Parameters
Parameter URL Description A string containing the URL for a resource on a web server. An accepted URL must follow the specified syntax defined in RFC 1738. The general format is: http://<host>:<port>/<path>?<searchpart>. The host can be either a name string or IP address. The port is the port number to connect to, which usually defaults to 80 and is often omitted, along with the preceding colon. The path tells the web server which file you want, and, if omitted, means home page for the system. The searchpart can be used to send additional information to a web server. A string which indicates the method to be performed on the resource. See the table below for the available (case-sensitive) methods. A handle to the request object. A handle to the security context. createSecureRequest Parameters
http_method request_handle securityContext
6-10

Return Code 0 1 2 Status Success. Invalid URL (Syntactically). Invalid method (For HTTP 1.0, only GET/POST/HEAD) Return Code Status
Note: If URL does include a searchpart, it must be in its encoded format (space is converted into +, and other non-alphanumeric characters are converted into %HH format. See addRequestParameter() for more details). However, host and path are allowed to have these unsafe characters. UniVerse BASIC will encode them before communicating with the web server.
6-11 UniVerse BASIC
Setting Additional Headers for a Request

The setRequestHeader function enables you to set additional headers for a request.
Syntax
setRequestHeader(request_handle, header_name, header_value)
Parameters
Parameter request_handle header_name header_value Description The handle to the request returned by createRequest(). The name of the header. The value of the header. setRequestHeader Parameters

Return Code 0 1 2 3 Status Success. Invalid request handle. Invalid header (Incompatible with method). Invalid header value. Return Code Status
Note: Since a user-defined header or header value can be transferred, it is difficult to check the validity of parameters passed to the function. UniVerse BASIC currently will not perform syntax checking on the parameters, although it will reject setting a response header to a request. Refer to RFC 2616 for valid request headers. The header set by this function will overwrite settings by setHTTPDefault().
6-12
This function supports Base64 encoding for Basic authentication. If header_name contains either Authorization or Proxy-Authorization,the header_value should then contain ASCII text user credential information in the format of userid:password as specified by RFC 2617. This function will then encode the text based on Base64 encoding. Only Basic authentication is supported. Digest authentication may be supported in the future. Basic authentication is not safe and is not recommended for use with transferring secured data.
6-13
UniVerse BASIC
Adding a Parameter to the Request

The addRequestParameter function adds a parameter to the request.
Syntax
addRequestParameter(request_handle, parameter_name, parameter_value, content_handling)
Parameters
Parameter request_handle parameter_name parameter_value content_handling Description The handle to the request. The name of the parameter. The value of the parameter. The dynamic MIME type for the parameter value. addRequestParameter Parameters

Return Code 0 1 2 3 Status Success. Invalid request handle. Invalid parameter. Bad content type. Return Code Status
Note: For a GET request, content_handling is ignored.
6-14
For a POST request with default content type, the default for content_handling is ContentType:text/plain if content_handling is not specified. For a POST request with Multipart/* content-type, content_handling is a dynamic array containing Content-* strings separated by field marks (@FM). They will be included in the multipart message before the data contained in parameter_value is sent. An example of content_handling:
Content-Type: application/XML @FM Content-Dispostion: attachment; file=C:\drive\test.dat @FM Content-Length: 1923
Specifically, for a POST request with content type multipart/form-data, a Content-Disposition:form-data header will be created (or, in the case of ContentDisposition already in content_handling, form-data will be added to it). For both a GET and a POST request with either no content type specified or specified as application/x-www-form-urlencoded, as described in createRequest(), URL encoding is performed on data in parameter_value automatically. Basically, any character other than alphanumeric is considered unsafe and will be replaced by %HH, where HH is the ASCII value of the character in question. For example, # is replaced by %23, and / is replaced by %2F, and so forth. One exception is that by convention, spaces ( ) are converted into +. For a POST method with other MIME-type specified, no encoding is done on data contained in parameter_value.
6-15
UniVerse BASIC
Submitting a Request
The submitRequest function will submit a request and get a response. The request is formed on the basis of default HTTP settings and previous setRequestHeader() and addRequestParameter() values. Specifically, for a GET method with parameters added, a parameter string (properly encoded) is created and attached to the URL string after the ? character. For a POST request with non-empty post_data, the data is attached to the request message as is. No encoding is performed, and any parameters added through addRequestParameter() will be totally ignored. Otherwise the following processing will be performed. For a POST request with default content type, the parameter string is assembled, a Content-Length header created, and then the string is attached as the last part of the request message. For a POST request with multipart/* content type, a unique boundary string is created and then multiple parts are generated in the sequence they were added through calling addRequestParameter(). Each will have a unique boundary, followed by optional Content-* headers, and data part. The total length is calculated and a Content-Length header is added to the message header. The request is then sent to the Web server identified by the URL supplied with the request and created through createRequest() (maybe via a proxy server). UniVerse Basic then waits for the web server to respond. Once the response message is received, the status contained in the response is analyzed. If the response status indicates that redirection is needed (status 301, 302, 305 or 307), it will be performed automatically, up to ten consecutive redirections (the limit is set to prevent looping, suggested by RFC 2616). If the response status is 401 or 407 (access denied), the response headers are examined to see if the server requires (or accepts) Basic authentication. If no Basic authentication request is found, the function returns with an error. Otherwise, default Authentication (set by setHTTPDefault) is used to re-send the request. If no default authentication is set, and no other cached user authentication is found, the function will return with an error.
6-16
If the user provides authentication information through Authorization or ProxyAuthorization header, the encoded information is cached. If later, a Basic authentication request is raised, no default authentication is found, and only one user/password encoding is cached, it will be used to re-send the request. The response from the HTTP server is disposed into response_header and response_data. It is the users responsibility to parse the headers and data. UniVerse Basic only performs transfer encoding (chunked encoding), and nothing else is done on the data. In other words, content-encoding (gzip, compress, deflate, and so forth) are supposed to be handled by the user, as with all MIME types. Also, if a response contains header Content-type: multipart/*, all the data (multiple bodies enclosed in boundary delimiters, see RFC 2046) is stored in response_data. It is the users responsibility to parse it according to boundary parameter.
Syntax
submitRequest(request_handle, time_out, post_data,response_headers,response_data, http_status)
Parameters
Parameter request_handle time_out post_data response_headers response_data http_status Description The handle to the request. The time-out value (in milliseconds) before the wait response is abandoned. The data sent with the POST request. A dynamic array to store header/value pairs. The resultant data (may be in binary format). A dynamic array containing the status code and explanatory text. submitRequest Parameters
6-17
UniVerse BASIC

Return Code 0 1 2 3 4 Status Success. Invalid request handle. Timed out. Network Error. Other Errors. Return Code Status
6-18
Chapter
Using WebSphere MQ with UniVerse

In This Chapter . . . . . . . . . . . . . . . . Preface . . . . . . . . . . . . . . . . . . . Overview of Messaging . . . . . . . . . . . . . Overview of IBM WebSphere MQ . . . . . . . . . . WebSphere MQ API for UniData and UniVerse . . . . . . MQSeries Application Messaging Interface . . . . . . Session . . . . . . . . . . . . . . . . . Services . . . . . . . . . . . . . . . . . Policies . . . . . . . . . . . . . . . . . Message Objects . . . . . . . . . . . . . . Messaging Styles . . . . . . . . . . . . . . Setup and Configuration for the WebSphere MQ API . . . . Requirements . . . . . . . . . . . . . . . Platform Availability . . . . . . . . . . . . . Setting up the Environment for UniData and WebSphere MQ Configurations . . . . . . . . . . . . . . . WebSphere MQ API Programmatic Interfaces . . . . . . Initialize an AMI Session . . . . . . . . . . . . . Receiving a Message . . . . . . . . . . . . . . Receiving a Request. . . . . . . . . . . . . . . Sending a Message . . . . . . . . . . . . . . . Sending a Request . . . . . . . . . . . . . . . Sending a Response . . . . . . . . . . . . . . . Terminating a Session . . . . . . . . . . . . . . Programming Examples . . . . . . . . . . . . . Additional Reading . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-2 3-3 3-4 3-5 3-7 3-7 3-8 3-8 3-9 3-9 3-10 3-12 3-12 3-12 3-12 3-14 3-18 3-19 3-21 3-25 3-29 3-31 3-33 3-35 3-37 3-47
In This Chapter
This chapter describes how to set up and configure the WebSphere MQ API for UniData and UniVerse. This chapter consists of the following sections: Preface Overview of Messaging Overview of IBM WebSphere MQ WebSphere MQ API for UniData and UniVerse Setup and Configuration for the WebSphere MQ API WebSphere MQ API Programmatic Interfaces Programming Examples Additional Reading
Preface
The WebSphere MQ API for UniData and UniVerse makes use of the MQSeries Application Messaging Interface (AMI). Note: WebSphere MQ was formerly named MQSeries and as such, much of the documentation references the former name. The AMI is available for download as a WebSphere MQ SupportPac from http://www-3.ibm.com/software/ts/mqseries/txppacs/ma0f.html. You need to download and install this SupportPac before you can use the WebSphere MQ API for UniData and UniVerse. Detailed information on the AMI can be found in the MQSeries Application Messaging Interface manual, which you can download from the same location. This manual assumes you have a general understanding of WebSphere MQ. Numerous documents for WebSphere MQ are available for download from the IBM Publications Center at: http://www.ibm.com/shop/publications/order
3-3
Overview of Messaging
Distributed applications are a common occurrence in companies today. They may come about from business acquisitions that bring together disparate systems which must then interact with each other, or from the purchase of new software systems that must interact with existing facilities. Other distributed systems are intentionally designed as such in order to improve scalability and overall reliability. Regardless of the circumstances of how these heterogeneous systems come about, they require a means for internal communication. A common solution to this challenge is messaging. Messaging middleware products provide the concept of message queues, which applications can use to communicate with each other through the exchange of messages. When one application has information to deliver, it places a message in a queue. Another application can then retrieve the message and act upon it. This is a flexible paradigm, allowing many different types of communication. Examples include the Datagram ("send-and-forget") messaging style, where an application simply delivers a message and then disconnects, and the Request/Response messaging style, which follows a client-server style of communication. A core feature of messaging middleware products is guaranteed, once-only message delivery. This frees applications from having to take on this burden themselves with low-level communication details. An application making use of the services of a messaging middleware product is guaranteed that its message will be delivered to the destination queue, and that the message will be delivered one time only. Another feature that message-based applications take advantage of is the benefits of being loosely-coupled. One application can go offline without affecting other applications in the system. When the application comes back online, it can then retrieve any messages that have been waiting for it from the message queue. Allowing components to be loosely-coupled can improve overall system reliability.
Overview of IBM WebSphere MQ

IBM WebSphere MQ (renamed from IBM MQSeries) is IBMs messaging middleware product. Through its services, applications can communicate with each other as messaging clients. WebSphere MQ makes use of message queues and queue managers in providing its services to message-based applications. A queue manager is a service that allows access to and administration of message queues. It handles the details of message delivery, such as guaranteeing once-only delivery, and forwarding messages across a network to other queue managers when required. Message queues act as the destinations for message delivery, holding the incoming messages until retrieved by another application. With WebSphere MQ, when an application needs to deliver a message, it connects to a WebSphere MQ queue manager, opens a message queue, and places the message on the queue. If required, the queue manager then forwards the message to a queue running under a different queue manager on another machine. A receiving application can then connect to that second queue manager, open the destination queue, and retrieve the message. The following excerpt from The MQSeries Application Programming Guide provides a description of WebSphere MQ queue managers and message queues:
What is a message queue?

A message queue, known simply as a queue, is a named destination to which messages can be sent. Messages accumulate on queues until they are retrieved by programs that service those queues. Queues reside in, and are managed by, a queue manager (see What is a queue manager? on page 5). The physical nature of a queue depends on the operating system on which the queue manager is running. A queue can either be a volatile buffer area in the memory of a computer, or a data set on a permanent storage device (such as a disk). The physical management of queues is the responsibility of the queue manager and is not made apparent to the participating application programs.
3-5
What is a queue manager?

A queue manager is a system program that provides queuing services to applications. It provides an application programming interface so that programs can put messages on, and get messages from, queues. A queue manager provides additional functions so that administrators can create new queues, alter the properties of existing queues, and control the operation of the queue manager. Many different applications can make use of the queue managers services at the same time and these applications can be entirely unrelated. For a program to use the services of a queue manager, it must establish a connection to that queue manager. For applications to be able to send messages to applications that are connected to other queue managers, the queue managers must be able to communicate among themselves. MQSeries implements a store-and-forward protocol to ensure the safe delivery of messages between such applications.
WebSphere MQ API for UniData and UniVerse

MQSeries Application Messaging Interface
The WebSphere MQ API for UniData and UniVerse makes use of the MQSeries Application Messaging Interface (AMI), available as a WebSphere MQ SupportPac (SupportPac ma0f) at http://www-3.ibm.com/software/ts/mqseries/txppacs/ma0f.html. The MQSeries AMI utilizes a repository of definitions that describe how and where messages are to be delivered. Service definitions determine where messages are to be delivered, and policy definitions govern how those messages are delivered. Typically, a WebSphere MQ administrator creates and administers the definitions. AMI-based programs can then reference the definitions by name. This simplifies software development and maintenance by moving messaging complexity away from the program and into the repository. The repository itself exists as an XML file on the machine running the application (although LDAP-based repositories are supported as well). The WebSphere MQ API for UniData and UniVerse utilizes service and policy definitions by accepting them as parameters to the various API calls. For example, when placing a message on a queue with amSendMsg, the properties defined by the service name and policy name passed in to the function determine where and how the message is sent. For Windows platforms, WebSphere MQ AMI provides the AMI Administration Tool to manage the repository. It allows administration of the AMI repository through a GUI interface, rather than through direct editing of the XML file. For more information about the WebSphere MQ AMI repository, and about the AMI Administration Tool, see the MQSeries Application Messaging Interface manual.
3-7
Session
In the WebSphere MQ API for UniData and UniVerse, the sending and receiving of messages takes place within a session. You start sessions via the API call amInitialize, and end them with amTerminate. Upon successful completion, amInitialize returns a valid session handle in the hsession output variable. You then use this session handle in all subsequent WebSphere API for UniData and UniVerse calls, until you close the session with amTerminate. Only one session may be active at a time from within a given instance of a running BASIC program.
Services
The WebSphere MQ API for UniData and UniVerse makes use of AMI services in its API calls. An AMI service represents a destination from where a message is to be sent to or retrieved. In other words, a service represents a particular message queue running under a particular queue manager. Interacting with queues can be complex, owing to the many variables associated with them. Services hide this complexity by encapsulating queue parameters within the service definitions themselves. Thus, rather than explicitly setting all of the message queue parameters directly in the program, you simply reference a particular service definition by name in the WebSphere MQ API for UniData and UniVerse function call. A WebSphere MQ administrator creates service definitions, and they are stored in the AMI repository. Default services are also available, and can be referenced by using an empty string ("") in place of an actual service name in the WebSphere MQ API for UniData and UniVerse API calls. See the MQSeries Application Messaging Interface manual, Chapter 19: Defining Services, Policies, and Policy Handlers, under the section Service Definitions, for default values of service properties. For more information about AMI services, and about the AMI Repository, see the MQSeries Application Messaging Interface manual.
Policies
The WebSphere MQ API for UniData and UniVerse makes use of AMI policies in its API calls. A policy represents how a message is to be sent or retrieved. For example, a policy can dictate whether truncated messages are allowed, or how many times a failed message delivery should be automatically retried. By referencing policies directly by name in the various WebSphere MQ API for UniData and UniVerse function calls, you avoid having to explicitly code message delivery details in your programs. Instead, this complexity is embedded in the policies themselves. A WebSphere MQ administrator creates policy definitions, and they are stored in the AMI repository. Default policies are also available, and you can reference them by using an empty string ("") in place of an actual policy name in the WebSphere MQ API for UniData and UniVerse API calls. See the WebSphere MQ Application Messaging Interface manual, Chapter 19: Defining Services, Policies, and Policy Handlers under the section Policy Definitions, for default policy values. For more information about AMI policies, and about the AMI repository, see the MQSeries Application Messaging Interface manual.
Message Objects
When a message is sent or received via the WebSphere MQ API for UniData and UniVerse calls, an AMI message object is created implicitly, behind the scenes. The message object encapsulates details of the message, such as its MQSeries message headers, including the Message ID and Correlation ID, along with the message data itself. You can name, or tag, these message objects by providing names for them in the API calls. For example, in the amSendRequest function, you can use the sndMsgName parameter to specify a name for the underlying message object that gets created during the call. By tagging a message object in this manner, you can later reference that same message object in subsequent API calls. This is particularly important when correlating requests and responses in the Request/Response messaging style. Note: It is not required to name the underlying message objects. You can use an empty string (""), especially in cases where the message object will not need to be referenced later, as is often the case for the Datagram messaging style.
3-9
Messaging Styles
The WebSphere MQ API for UniData and UniVerse supports two messaging styles, Datagram and Request/Response.
Datagram Messaging Style

The Datagram messaging style, also known as "Send-and-Forget," is the simplest type of messaging. It involves an application placing a message on a queue without requiring a response back. A receiving application picks up the message and performs work based on the message contents, but does not respond back to the sending application. Datagram messaging involves the use of two functions: amSendMsg amReceiveMsg
Request/Response Messaging Style

Request/Response messaging follows the client/server paradigm. One application, acting as the client, sends a request message to a queue. A server application picks up and processes the message, and then sends a response message to another queue, which the client monitors for a reply. The client then picks up the response message and acts on it appropriately. Request/Response messaging relies on four functions, separated according to client or server functionality.
Client Request/Response Functions

amSendRequest amReceiveMsg
Server Request/Response Functions

amReceiveRequest amSendResponse
3-10
Due to the nature of messaging, where communication is accomplished through an intermediaryfor example, a message queuethe notion of correlating requests and responses is important for the Request/Response messaging style. Without a means for this correlation, a requesting application would not be able to differentiate the response message from any other message appearing on the queue. WebSphere MQ accomplishes this correlation through the use of Correlation ID's, which are stored in the message header. In Request/Response messaging, the responding application copies the request message's Message ID into the Correlation ID field of the response message. The requesting application can then select the correct response message from the queue through the use of this Correlation ID. The WebSphere MQ API for UniData and UniVerse handles this correlation process transparently through the use of AMI message objects. Thus, you need not be concerned with the details of copying Message ID's to Correlation ID fields, or filtering messages based on their Correlation ID. In the client application, this is accomplished by using the message object created in amSendRequest as the message selection criteria in amReceiveMsg. So, in the call to amSendRequest, you tag the underlying request message object by giving it a name via the sndMsgName parameter. This name is then used as the selMsgName parameter in the subsequent call to amReceiveMsg. Behind the scenes, the Message ID of the request message sent out via amSendRequest, is used by amReceiveMsg to select the correct response message based on its Correlation ID field. In the server application, a similar process takes place between the calls amReceiveRequest and amSendResponse. When receiving a request message throgh amReceiveRequest, you tag the underlying request message object by giving it a name via the rcvMsgName parameter. This named message object is then used in the subsequent call to amSendResponse, through that function's rcvMsgName parameter. Behind the scenes, the Message ID from the request message is copied over to the Correlation ID field of the response message, which is then sent out through amSendResponse.
3-11
Setup and Configuration for the WebSphere MQ API

Requirements
UniData 6.0 or later UniVerse 10.1 or later WebSphere MQ version 5.2 (Formerly MQSeries version 5.2) WebSphere MQ Application Messaging Interface SupportPac SupportPac ma0f - available for download from http://www3.ibm.com/software/ts/mqseries/txppacs/ma0f.html
Platform Availability
The WebSphere MQ API for UniData and UniVerse is available on the following platforms. AIX - V4.3.3 (non-threaded and pthreads) SUN Solaris - V2.6, V7, and V8 (pthreads) HP-UX - V11.0 PA2 (pthreads) Windows NT/2000
Setting up the Environment for UniData and WebSphere MQ

You must complete the following steps in order to set up your environment to utilize WebSphere MQ for UniData. First you must install either MQSeries, or MQSeries Client on the UniData machine. For information about installing MQSeries, see the MQSeries Quick Beginnings manual that ships with your copy of MQSeries. For information about installing the MQSeries Client, see the MQSeries manual MQSeries Clients. These manuals are also available for download from http://www.ibm.com/shop/publications/order.
3-12
Once MQSeries or the MQSeries Client is installed on the UniData machine, you should install the MQSeries AMI SupportPac. The AMI is available for download from: http://www-3.ibm.com/software/ts/mqseries/txppacs/ma0f.html. For information about installing the MQSeries AMI SupportPac, see the MQSeries Application Messaging Interface manual, available for download from the same location, and from: http://www.ibm.com/shop/publications/order. More information on using MQSeries Client from within UniData or UniVerse can be found in WebSphere MQ and UniData or UniVerse on Separate Machines. For Windows platforms, this is all that is required for enabling WebSphere MQ support for UniData. For UNIX platforms, you must run the script file makeu2mqs to complete the process, as described in Enabling WebSphere MQ Support in UniData on UNIX.
Enabling WebSphere MQ Support in UniData on UNIX

You can use the script file makeu2mqs, located in the $UDTHOME/work directory, to enable WebSphere MQ support in UniData. Before running makeu2mqs, you will need to verify the following.
1. 2.
The $UDTHOME environment variable is set. You know the location of the WebSphere MQ AMI library file. The names and default locations of the AMI library files for the supported platforms are listed here: AIX AMI library file: libamt.a Default location: /usr/mqm/lib HP-UX AMI library file: libamt.sl Default location: /opt/mqm/lib Solaris AMI library file: libamt.so Default location: /opt/mqm/lib
3-13
Once you are ready to begin, change to the $UDTHOME/work directory and run the makeu2mqs script with the enabled option. It is important to be in this directory when running the script. You need to have sufficient privileges to overwrite the file $UDTBIN/u2amiproxy in order to successfully enable WebSphere MQ support. Invoke the following commands:
cd $UDTHOME/work ./makeu2mqs enabled
At this point, you will be given a chance to confirm the values for the UniData bin and lib directories, and then will be asked to supply the directory holding the AMI library file. makeu2mqs then completes the process of enabling WebSphere MQ support in UniData.
Disabling WebSphere MQ Support in UniData on UNIX

You can also use the script file makeu2mqs, located in the $UDTHOME/work directory, to later disable WebSphere MQ support in UniData. To disable WebSphere MQ support in UniData, change directories to the $UDTHOME/work directory and run makeu2mqs disabled. It is important that you be in this directory when running makeu2mqs. You need to have sufficient privileges to overwrite the file $UDTBIN/u2amiproxy in order to successfully disable WebSphere MQ support. Invoke the following commands:
cd $UDTHOME/work ./makeu2mqs disabled
You will be given a chance to confirm the values for the UniData bin and lib directories, after which makeu2mqs completes the process of disabling WebSphere MQ support in UniData.
Configurations
Although in most cases a WebSphere MQ queue manager runs on the same machine as the UniData or UniVerse database, this is not strictly necessary. Instead, UniData or UniVerse can communicate directly with a queue manager running on a different machine by acting as a WebSphere MQ Client. In this configuration, WebSphere MQ API for UniData and UniVerse function calls make use of WebSphere MQ client libraries that marshall the calls across the network to the remote queue manager.
3-14
Both scenarios have their particular benefits, and the choice of configuration depends on the particular application. For more information about running an application as a WebSphere MQ Client, see the MQSeries Clients manual, which ships with WebSphere MQ, and is also available for download from http://www.ibm.com/shop/publications/order.
WebSphere MQ and UniData or UniVerse on the Same Machine

To connect to a WebSphere MQ queue manager running on the same machine as UniData or UniVerse, no special steps are required. This is often referred to in various WebSphere MQ documentation as connecting via the MQSeries "server libraries." By default, AMI policy settings are such that the MQSeries server libraries are used if they are installed on the given machine (the machine running UniData or UniVerse). The server libraries are installed when the full version of WebSphere MQ is installed. The server libraries allow applications to connect only to queue managers running on the local machine. When messages must be delivered across a network, the queue managers handle this automatically (after being configured appropriately by the WebSphere MQ Administrator). Running the application on the same machine as the queue manager is the typical WebSphere MQ configuration.
WebSphere MQ and UniData or UniVerse on Separate Machines

It is also possible to run WebSphere MQ on a separate machine from the UniData or UniVerse database. In this scenario, you must install the WebSphere MQ Client on the machine running UniData or UniVerse. In addition to the WebSphere MQ Client, you must also install the MQSeries AMI SupportPac on the UniData or UniVerse machine. With the WebSphere MQ Client installed, the UniData or UniVerse database can connect to a remote queue manager via the WebSphere MQ "client libraries." To connect to a queue manager via the WebSphere MQ client libraries, the AMI policy governing the connection must be configured appropriately. Complete the following steps to connect to a remote queue manager:
1. 2. 3. 4.
Install the WebSphere MQ Client on the database server. Install the WebSphere MQ AMI SupportPac on the database server. Configure your AMI policy to connect as a WebSphere MQ Client. Set up a listener for the queue manager on the remote machine.
3-15
Install the MQSeries Client on the UniData/UniVerse machine

For MQSeries Client installation instructions, see the MQSeries Client manual, available with the WebSphere MQ installation, and also for download from http://www.ibm.com/shop/publications/order.
Install the MQSeries AMI SupportPac on the UniData/UniVerse machine

For MQSeries AMI installation instructions, see the MQSeries Application Messaging Interface manual, available from the MQSeries AMI SupportPac page (http://www-3.ibm.com/software/ts/mqseries/txppacs/ma0f.html), and also from http://www.ibm.com/shop/publications/order.
Configure your AMI policy to connect as an MQSeries Client

The following AMI Policy attributes are used when connecting through the WebSphere MQ client libraries: Connection Type If Connection Type is set to Auto (the default), the application automatically detects if it should connect directly (via the server libraries), or as a client. If Connection Type is Client, the application connects as a client. If Connection Type is Server, the application connects directly to the local queue manager. Client Channel Name For a WebSphere MQ client connection, the name of the server-connection channel. See the MQSeries Client manual for more information about MQSeries Channels. You can use this attribute, in combination with the Client TCP Server Address attribute, instead of the MQSERVER environment variable on the MQSeries client. For more information about the MQSERVER environment variable, see the MQSeries Clients manual. Client TCP Server Address For an MQSeries client connection, the TCP/IP host name or IP address, and optional port, of the WebSphere MQ server, in the form hostname(portnumber). You can use this attribute, in combination with the Client Channel Name attribute, instead of the MQSERVER environment variable on the WebSphere MQ client. For more information about the MQSERVER environment variable, see the MQSeries Clients manual.
Setup a Listener for the Queue Manager on the Remote Machine

The queue manager running on the remote machine must have a listener configured to accept the requests from the WebSphere MQ client application. See the MQSeries Clients manual, available with the WebSphere MQ installation, and also for download from http://www.ibm.com/shop/publications/order, for information on setting up an MQSeries listener.
3-17
WebSphere MQ API Programmatic Interfaces

This section provides information on the WebSphere MQ functions and parameters for UniData and UniVerse. Note: A set of named constants are available in the include file INCLUDE/U2AMI.H.
3-18
Initialize an AMI Session

The amInitialize() function creates and opens an AMI session. The output parameter hSession is a session handle which is valid until the session is terminated. The function returns a status code indicating success, warning or failure. You can also use The BASIC STATUS() function to obtain this value.
Syntax
ret = amInitialize(hSession, appName, policyName, reasonCode) The following table describes each parameter of the syntax.
Parameter hSession appName policyName reasonCode Description Upon successful return, holds a handle to a session. You can then use this handle in other UniData and UniVerse WebSphere MQ API calls. [OUT] An optional name you can use to identify the session. [IN] The name of a policy. If you specify as "" (null), amInitialize uses the system default policy name. [IN] Holds an AMI Reason Code when the function returns a status indicating an AMI warning or an AMI error occurred. You can use the AMI Reason Code to obtain more information about the cause of the warning or error. See Appendix A, MQSeries API for UniData and UniVerse Reason Codes for a list of AMI Reason Codes and their descriptions. [OUT] amInitialize Parameters
3-19

Return Code 0 - AMCC_SUCCESS 1 - AMCC_WARNING Status Function completed successfully. A warning was returned from AMI. The reasonCode output parameter contains an AMI reason code with further details about the warning. An error was returned from AMI. The reasonCode output parameter contains an AMI reason code with further details about the error. An active session already exists (under a different hSession variable than the one being passed in see Usage Notes for more details). A non-AMI error occurred. Return Code Status
2 - AMCC_FAILED
115 - U2AMI_ERR_SESSION_IN_USE
Other
Usage Notes
Only one session may be active at one time. If you call amInitialize while another session is active, an error code of U2AMI_ERR_SESSION_IN_USE is returned. The one exception to this case is if the subsequent call to amInitialize uses the same hSession variable from the first call. In this case, the session is automatically terminated using the same AMI policy with which it was initialized, and a new session is started in its place.
3-20
Receiving a Message
The amReceiveMsg() function receives a message sent by the amSendMsg() function.
Syntax
ret = amReceiveMsg(hSession, receiverName, policyName, selMsgName, maxMsgLen, dataLen, data, rcvMsgName, reasonCode)
Parameters
Parameter hSession receiverName policyName selMsgName Description The session handle returned by amInitialize. [IN] The name of a receiver service. If you specify (null), amReceiveMsg uses the system default receiver name. [IN] The name of a policy. If you specify (null), amReceiveMsg uses the system default policy name. [IN] Optional parameter specifying the name of a message object containing information (such as a Correl ID) to use to retrieve the required message from the queue. See the Usage Notes for additional information about the use of this parameter.[IN] The maximum message length the application will accept. Specify as -1 to accept messages of any length, or use the optional parameter U2AMI_RESIZEBUFFER. See the Usage Notes for additional information about the use of this parameter. [IN] The length of the received message data, in bytes. Specify as (null) if you do not require this parameter. [OUT] The received message data. [OUT] amReceiveMsg parameters
maxMsgLen
dataLen data
3-21
Parameter rcvMsgName
Description The name of a message object for the retrieved message. If you specify (null) for this parameter, amReceiveMsg uses the system default name (constant AMSD_RCV_MSG). See the Usage Notes for additional information about the use of this parameter. [IN] Holds an AMI Reason Code when the function returns a status indicating an AMI warning or an AMI error occurred. You can use the AMI Reason Code to obtain more information about the cause of the warning or error. See Appendix A, MQSeries API for UniData and UniVerse Reason Codes, for a list of AMI Reason Codes and their descriptions. [OUT] U2AMI_LEAVEMSG If you specify U2AMI_LEAVEMSG for this parameter, and Accept Truncated Messages is not set in the policy receive attributes, UniVerse returns the message length in the dataLen parameter, but the message itself remains on the queue. If you specify U2AMI_DISCARDMSG for this parameter and Accept Truncated Messages is set in the policy receive attributes, UniVerse discards the message at the MQSeries level with an AMRC_MSG_TRUNCATED warning. This behavior is preferable to discarding the message at the UniVerse level. If you specify U2AMI_RESIZEBUFFER for this parameter, UniVerse handles the details of the buffer size used to retrieve the message. If you do not specify this parameter, you must specify the buffer size. See Usage Notes for more information about this option.
reasonCode
optional parameter
U2AMI_DISCARDMSG
U2AMI_RESIZEBUFFER
amReceiveMsg parameters (Continued)
3-22

Return Code 0 - AMCC_SUCCESS 1 - AMCC_WARNING Status Function completed successfully. A warning was returned from AMI. The reasonCode output parameter contains an AMI reason code with further details about the warning. An error was returned from AMI. The reasonCode output parameter contains an AMI reason code with further details about the error. A non-AMI error occurred. Return Code Status
2 - AMCC_FAILED
Other
Usage Notes
selMsgName You can use this parameter in Request/Reply messaging to tell amReceiveMsg to retrieve from the queue only those messages that correlate with a message previously placed on the queue with amSendRequest. When used in this manner, use the sndMsgName parameter of the amSendRequest call as the value for selMsgName in amReceiveMsg. Message correlation occurs here due to the following:
1.
The underlying message object that was created when the request message was sent, and referenced by the name sndMsgName, holds information about the sent message, such as its Correlation Id and Message Id. When you use this message object (sndMsgName) as the selMsgName parameter to amReceiveMsg, the information held in this message object will be used to ensure that only correlating response messages are retrieved from the queue.
2.
maxMsgLen You can use this parameter to define the maximum length message that amReceiveMsg retrieves from the queue. If the value of maxMsgLen is less than the length of the message to be retrieved, behavior depends on whether you set the Accept Truncated Message parameter in the policy receive attributes to true. If Accept Truncated Message is set to true, the data is truncated and there is an AMRC_MSG_TRUNCATED warning in the reasonCode parameter. If you set Accept Truncated Message to false (the default), amReceiveMsg fails with return status AMCC_FAILED (2), and reasonCode AMRC_RECEIVE_BUFF_LEN_ERR.
3-23
Note: If amReceiveMsg returns AMRC_RECEIVE_BUFF_LEN_ERR as the reasonCode, the message length value is contained in dataLen parameter, even though the call failed with return value MQCC_FAILED. If you do not specify the U2AMI_RESIZE BUFFER optional parameter and the buffer size you specify with the maxMsgLen parameter is too small, the function fails with the AMRC_RECEIVE_BUFF_LEN_ERR. If this happens, UniVerse returns the necessary buffer size in the dataLen parameter so you can reissue the request with the correct size. If you specify the U2AMI_RESIZEBUFFER parameter, UniVerse uses a default buffer size of 8K. If this buffer size is too small, UniVerse automatically reissues the request with the correct buffer size. While convenient, this behavior can result in performance degradation for the following reasons: If the default buffer size is larger than necessary for the received message, UniVerse incurs an unnecessary overhead. If the default buffer size is too small for the received message, UniVerse must issue to requests to the queue before successfully retrieving the message. For performance reasons, IBM recommends you set the maxMsgLen parameter to the expected size of the message whenever possible. rcvMsgName This parameter allows the application to attach a name to the underlying message object used to retrieve the message. Though supported, this parameter is mainly intended for use in conjunction with future additions to the WebSphere MQ for UniData and UniVerse API.
3-24
Receiving a Request
The amReceiveRequest() function receives a request message.
Syntax
ret = amReceiveRequest(hSession, receiverName, policyName, maxMsgLen, dataLen, data, rcvMsgName, senderName, reasonCode [U2AMI_LEAVEMSG | U2AMI_DISCARDMSG | U2AMI_RESIZEBUFFER])
Parameters
Parameter hSession receiverName policyName maxMsgLen Description The session handle returned by amInitialize. [IN] The name of a receiver service. If you specify (null), amReceiveRequest uses the system default receiver name. [IN] The name of a policy. If you specify (null), amReceiveRequest uses the system default policy name. [IN] The maximum message length the application will accept. Specify as -1 to accept messages of any length, or use the optional parameter U2AMI_RESIZEBUFFER. See Usage Notes for additional information about the use of this parameter. [IN] The length of the received message data, in bytes. Specify (null) if you do not require this parameter. [OUT] The received message data. [OUT] The name of the message object for the received message. If you specify (null), amReceiveRequest uses the system default receiver service. The value for rcvMsgName will be used in the subsequent call to amSendResponse. [IN] amReceiveRequest parameters
dataLen data rcvMsgName
3-25
Parameter senderName
Description The name of a special type of sender service known as a response sender, to which the response message will be sent. If you do not specify a name, amReceiveRequest uses the system default response sender service. [IN] Note: The sender name you specify must ot exist in your AMI repository.
reasonCode
Holds an AMI Reason Code when the function returns a status indicating an AMI warning or an AMI error occurred. You can use the AMI Reason Code to obtain more information about the cause of the warning or error. See Appendix A, MQSeries API for UniData and UniVerse Reason Codes, for a list of AMI Reason Codes and their descriptions. [OUT] U2AMI_LEAVEMSG If you specify U2AMI_LEAVEMSG for this parameter, and Accept Truncated Messages is not set in the policy receive attributes, UniVerse returns the message length in the dataLen parameter, but the message itself remains on the queue. If you specify U2_DISCARDMSG for this parameter and Accept Truncated Messages is set in the policy receive attributes, UniVerse discards the message at the MQSeries level with an AMRC_MSG_TRUNCATED warning. This behavior is preferable to discarding the message at the UniVerse level. If you specify U2AMI_RESIZEBUFFER for this parameter, UniVerse handles the details of the buffer size used to retrieve the message. If you do not specify this parameter, you must specify the buffer size. See Usage Notes for more information about this option.
optional parameter
U2AMI_DISCARDMSG
U2AMI_RESIZEBUFFER
amReceiveRequest parameters (Continued)
3-26

2 - AMCC_FAILED
other
Usage Notes
maxMsgLen You can use this parameter to define the maximum length message that amReceiveRequest retrieves from the queue. If the value of maxMsgLen is less than the length of the message to retrieve, behavior depends on whether you set Accept Truncated Message in the policy receive attributes to true. If Accept Truncated Message is set to true, the data is truncated and there is an AMRC_MSG_TRUNCATED warning in the reasonCode parameter. If Accept Truncated Message is false (the default), amReceiveRequest fails with return status AMCC_FAILED (2), and reasonCode AMRC_RECEIVE_BUFF_LEN_ERR. Note: If AMRC_RECEIVE_BUFF_LEN_ERR is returned as the reasonCode, the message length value is contained in dataLen parameter, even though the call failed with return value MQCC_FAILED. If you do not specify the U2AMI_RESIZEBUFFER optional parameter and the buffer size you specify with the maxMsgLen parameter is too small, the function fails with the AMRC_RECEIVE_ BUFF_LEN_ERR. If this happens, UniVerse returns the necessary buffer size in the dataLen parameter so you can reissue the request with the correct size. If you specify the U2AMI_RESIZEBUFFER parameter, UniVerse uses a default buffer size of 8K. If this buffer size is too small, UniVerse automatically reissues the request with the correct buffer size. While convenient, this behavior can result in performance degradation for the following reasons:
3-27
If the default buffer size is larger than necessary for the received message, UniVerse incurs an unnecessary overhead. If the default buffer size is too small for the received message, UniVerse must issue two requests to the queue before successfully retrieving the message. For performance reasons, IBM recommends you set the maxMsgLen parameter to the expected size of the message whenever possible.
3-28
Sending a Message
The amSendMsg() function sends a datagram (send and forget) message.
Syntax
ret = amSendMsg(hSession, senderName, policyName, data, sndMsgName, reasonCode)
Parameters
Parameter hSession senderName policyName data sndMsgName Description The session handle returned by amInitialize. [IN] The name of a sender service. If you specify (null), amSendMsg uses the system default receiver name. [IN] The name of a policy. If you specify (null), amSendMsg uses the system default policy name. [IN] The message data to be sent. [IN] The name of a message object for the message being sent. If you specify (null), amSendMsg uses the system default policy name. [IN] Holds an AMI Reason Code when the function returns a status indicating an AMI warning or an AMI error occurred. You can use the AMI Reason Code to obtain more information on the cause of the warning or error. See Appendix A, MQSeries API for UniData and UniVerse Reason Codes, for a list of AMI Reason Codes and their descriptions. [OUT] amSendMsg Parameters
reasonCode
3-29

2 - AMCC_FAILED
Other
You can also use the BASIC STATUS() to obtain the return status from the function.
3-30
Sending a Request
The amSendRequest() function sends a request message.
Syntax
ret = amSendRequest(hSession, senderName, policyName, data, sndMsgName, reasonCode)
Parameters
Parameter hSession senderName policyName responseName dataLen data sndMsgName Description The session handle returned by amInitialize. [IN] The name of a sender service. If you specify (null), amSendRequest uses the system default sender name. [IN] The name of a policy. If you specify (null), amSendRequest uses the system default policy name. [IN] The name of the receiver service to which the response to this send request should be sent. Specify (null) if no response is required. [IN] The length of the message data, in bytes. [IN] The message data to be sent. [IN] The name of a message object for the message being sent. If you specify (null), amSendRequest uses the system default message name (constant AMSD_SND_MSG). [IN] Holds an AMI Reason Code when the function returns a status indicating an AMI warning or an AMI error occurred. You can use the AMI Reason Code to obtain more information about the cause of the warning or error. See Appendix A, MQSeries API for UniData and UniVerse Reason Codes, for a list of AMI Reason Codes and their descriptions. [OUT] amSendRequest Parameters
reasonCode
3-31

2 - AMCC_FAILED
Other
You can also use the BASIC STATUS() function to obtain the return status from the function.
3-32
Sending a Response
The amSendResponse() function sends a request message.
Syntax
ret = amSendResponse(hSession, senderName, policyName, rcvMsgName, data, sndMsgName, reasonCode)
Parameters
Parameter hSession senderName policyName rcvMsgName Description The session handle returned by amInitialize. [IN] The name of the sender service. You must set this parameter to the senderName specified for the amReceiveRequest function. [IN] The name of a policy. If you specify (null), amSendResponse uses the system default policy name. [IN] The name of the received message to which this message is a response. You must set this parameter to the rcvMsgName specified for the amReceiveRequest function. [IN] The length of the message data, in bytes. [IN] The message data to be sent. [IN] The name of a message object for the message being sent. If you specify (null), amSendResponse uses the system default message name (constant AMSD_SND_MSG). [IN] Holds an AMI Reason Code when the function returns a status indicating an AMI warning or an AMI error occurred. You can use the AMI Reason Code can be used to obtain more information about the cause of the warning error. See Appendix A, MQSeries API for UniData and UniVerse Reason Codes, for a list of AMI Reason Codes and their descriptions.[OUT] amSendResponse Parameters 3-33
dataLen data sndMsgName
reasonCode

Return Code 0 - AMCC_SUCCESS 1 - AMCC_WARNING Status Function completed successfully. A warning was returned from AMI. The reasonCode output parameter contains an AMI reason code with further details about the warning. An error was returned from AMI. the reasonCode output parameter contains an AMI reason code with further details about the error. A non-AMI error occurred. Return Code Status
2 - AMCC_FAILED
Other
3-34
Terminating a Session
The amTerminate() function closes a session.
Syntax
ret = amTerminate(hSession, policyName, reasonCode)
Parameters
Parameter hSession policyName reasonCode Description The session handle returned by amInitialize. [IN/OUT] The name of a policy. If you specify (null), amTerminate uses the system default policy name. [IN] Holds an AMI Reason Code when the function returns a status indicating an AMI warning or an AMI error occurred. You can use the AMI Reason Code to obtain more information about the cause of the warning or error. See Appendix A, MQSeries API for UniData and UniVerse Reason Codes, for a list of AMI Reason Codes and their descriptions. [OUT] amTerminate Parameters
3-35

2 - AMCC_FAILED
Other
3-36
Programming Examples
Sending a Message
The following example demonstrates sending a message to a message queue. The message is sent using the policy and service rules set forth in "AMT.SAMPLE.POLICY" and "AMT.SAMPLE.SERVICE".
$INCLUDE INCLUDE U2AMI.H ret = amInitialize(hSess, "SAMPLE.APP", "AMT.SAMPLE.POLICY", reasonCode) msg = "Sample Message sent at " : TIMEDATE() ret = amSendMsg(hSess, "AMT.SAMPLE.SERVICE", "AMT.SAMPLE.POLICY", msg, "", reasonCode) ret = amTerminate(hSess, "AMT.SAMPLE.POLICY", reasonCode)
Retrieving a Message
The following example demonstrates retrieving a message from a message queue. The message, of maximum length 1024, is retrieved into the variable msg using the policy and service rules set forth in "AMT.SAMPLE.POLICY" and "AMT.SAMPLE.SERVICE". The message selection criteria is "", meaning the next available message will be retrieved from the queue.
$INCLUDE INCLUDE U2AMI.H retCode = amInitialize(hSess, "SAMPLE.APP", "AMT.SAMPLE.POLICY", reasonCode) retCode = amReceiveMsg(hSess, "AMT.SAMPLE.SERVICE", "AMT.SAMPLE.POLICY", "", 1024, dataLen, msg, "", reasonCode) retCode = amTerminate(hSess, "AMT.SAMPLE.POLICY", reasonCode)
Request/Response Messaging
The following client and server samples demonstrate use of the Request/Response messaging style. The client sends a message to the server, and the server then echoes that message back to the client.
3-37
Note that the repository definitions named in the program can be created via the amtsamp.tst script that ships with the MQSeries AMI SupportPac. See the chapter Installation and Sample Programs in the MQSeries Application Messaging Interface manual for more details.
3-38
Sample Request/Response Client

$INCLUDE INCLUDE U2AMI.H
APP_NAME SENDER_SERVICE RECEIVER_SERVICE SEND_MESSAGE_NAME RECEIVE_MESSAGE_NAME POLICY
= = = = = =
"SAMPLE.CLIENT" "AMT.SAMPLE.REQUEST.SERVICE" "AMT.SAMPLE.RESPONSE.RECEIVER" "AMT.SAMPLE.SEND.MESSAGE" "AMT.SAMPLE.RECEIVE.MESSAGE" "AMT.SAMPLE.POLICY"
hSession retCode reasonCode
= 0 = 0 = 0
reqMessage = "" respMessage = "" respMsgLen = 0 MAX_MSG_LEN = 1024
********************************* * Initialize the Session * ********************************* retCode = amInitialize(hSession, APP_NAME, POLICY, reasonCode) IF retCode # AMCC_OK THEN function = "amInitialize" GOTO ErrorExit END
********************************* * Send the Request Message * * * amSendRequest INPUTS * * hSession - Session handle. * SENDER_SERVICE - Service definition used to send * the request message. * POLICY - Policy definition used to send * the request message. * RECEIVER_SERVICE - Service definition describing where * the response message should be sent * reqMessage - Request message. * SEND_MESSAGE_NAME - Name we're giving to the the
3-39
* underlying * message object used to send the * request message. * * amSendRequest OUTPUTS * * retCode - Holds return code indicating status of * function: * AMCC_OK (0) - Success * AMCC_WARNING (1) - WebSphere MQ AMI * Warning * AMCC_FAILED (2) - WebSphere MQ AMI * Error * Other - Other error * reasonCode - Holds additional information if * WebSphere MQ AMI error or warning * occurs. * ********************************* PRINT "Please enter a message to send to the server. " PRINT "The server will echo the message back: " INPUT reqMessage PRINT "Sending Request Message: " PRINT " << " : reqMessage PRINT ""
retCode = amSendRequest(hSession, SENDER_SERVICE, POLICY, RECEIVER_SERVICE, reqMessage, SEND_MESSAGE_NAME, reasonCode) IF retCode # AMCC_OK THEN function = "amSendRequest" GOTO ErrorExit END
********************************* * Receive the Response Message * * * amReceiveMsg INPUTS * * hSession - Session handle. * RECEIVER_SERVICE - Service definition describing where * the response message is to be * retrieved from. * POLICY - Policy definition used to retrieve * the response message. * SEND_MESSAGE_NAME - Name we gave to the the underlying * message object used to send the * request * message. This message object is now
3-40
* used as the message selection criteria * to ensure that we retrieve only the * message * that is sent in response to our * request. * MAX_MSG_LEN - Max allowed length for retrieved * message. * RECEIVE_MESSAGE_NAME - Name we're giving to the the * underlying * message object used to receive the * response message. * * amReceiveMsg OUTPUTS * * retCode - Holds return code indicating status of * function: * AMCC_OK (0) - Success * AMCC_WARNING (1) - WebSphere MQ AMI * Warning * AMCC_FAILED (2) - WebSphere MQ AMI * Error * Other - Other error * respMsgLen - Length of received message. * respMessage - Response message. * reasonCode - Holds additional information if * WebSphere MQ AMI error or warning * occurs. * ********************************* retCode = amReceiveMsg(hSession, RECEIVER_SERVICE, POLICY, SEND_MESSAGE_NAME, MAX_MSG_LEN, respMsgLen, respMessage, RECEIVE_MESSAGE_NAME, reasonCode) IF retCode # AMCC_OK THEN function = "amReceiveMsg" GOTO ErrorExit END PRINT "Received Response Message: " PRINT " >> " : respMessage PRINT ""
********************************* * Terminate the Session * ********************************* retCode = amTerminate(hSession, POLICY, reasonCode) IF retCode # AMCC_OK THEN function = "amTerminate" GOTO ErrorExit END
3-41
STOP
ErrorExit: PRINT "Error/Warning encountered in function " : function PRINT " retCode = " : retCode IF retCode = AMCC_WARNING OR retCode = AMCC_FAILED THEN PRINT " reasonCode = " : reasonCode END
END
3-42
Sample Request/Response Server

$INCLUDE INCLUDE U2AMI.H
APP_NAME SENDER_SERVICE RECEIVER_SERVICE SEND_MESSAGE_NAME RECEIVE_MESSAGE_NAME POLICY
= = = = = =
"SAMPLE.SERVER" "AMT.SAMPLE.RESPONDER" "AMT.SAMPLE.REQUEST.SERVICE" "AMT.SAMPLE.SEND.MESSAGE" "AMT.SAMPLE.RECEIVE.MESSAGE" "AMT.SAMPLE.POLICY"
hSession retCode reasonCode
= 0 = 0 = 0
MAX_REQUESTS = 5 msgCount = 0 reqMessage respMessage reqMsgLen MAX_MSG_LEN = "" = "" = 0 = 1024
********************************* * Initialize the Session * ********************************* retCode = amInitialize(hSession, APP_NAME, POLICY, reasonCode) IF retCode # AMCC_OK THEN function = "amInitialize" GOTO ErrorExit END
************************************* * Service up to MAX_REQUESTS * ************************************* FOR msgCount = 1 TO MAX_REQUESTS
********************************* * Receive the Request Message * * * amReceiveRequest INPUTS * * hSession - Session handle.
3-43
* RECEIVER_SERVICE - Service definition describing where * the request message is to be * retrieved from. * POLICY - Policy definition used to retrieve * the request message. * MAX_MSG_LEN - Max allowed length for retrieved * message. * RECEIVE_MESSAGE_NAME - Name we're giving to the the * underlying * message object used to receive the * request message. * SENDER_SERVICE - Name we're giving to the special * internally-defined "response sender" * service. Note that because of the * special status of * response-senders, the * name we give the service must not * be defined in the AMI repository. * * amReceiveRequest OUTPUTS * * retCode - Holds return code indicating status of * function: * AMCC_OK (0) - Success * AMCC_WARNING (1) - WebSphere MQ AMI * Warning * AMCC_FAILED (2) - WebSphere MQ AMI * Error * Other - Other error * reqMsgLen - Length of received message. * reqMessage - Request message. * reasonCode - Holds additional information if * WebSphere MQ AMI error or warning occurs. * ********************************* retCode = amReceiveRequest(hSession, RECEIVER_SERVICE, POLICY, MAX_MSG_LEN, reqMsgLen, reqMessage, RECEIVE_MESSAGE_NAME, SENDER_SERVICE, reasonCode) IF retCode # AMCC_OK THEN function = "amReceiveRequest" GOTO ErrorExit END PRINT "Received Request Message: " PRINT " >> " : reqMessage PRINT ""
********************************* * Send the Response Message
3-44
* * * amSendResponse INPUTS * * hSession - Session handle. * SENDER_SERVICE - The response-sender we named * previously * in the call to amReceiveRequest. * POLICY - Policy definition used to send * the response message. * RECEIVE_MESSAGE_NAME - Name we gave to the the underlying * message object used to receive the * request message. This message object * is * now used to correlate the response * message with the initial request * message. * respMessage - Response message. * SEND_MESSAGE_NAME - Name we're giving to the the * underlying * message object used to send the * response message. * * amSendResponse OUTPUTS * * retCode - Holds return code indicating status of * function: * AMCC_OK (0) - Success * AMCC_WARNING (1) - WebSphere MQ AMI * Warning * AMCC_FAILED (2) - WebSphere MQ AMI * Error * Other - Other error * reasonCode - Holds additional information if * WebSphere MQ AMI error or warning * occurs. * ********************************* respMessage = reqMessage retCode = amSendResponse(hSession, SENDER_SERVICE, POLICY, RECEIVE_MESSAGE_NAME, respMessage, SEND_MESSAGE_NAME, reasonCode) IF retCode # AMCC_OK THEN function = "amSendResponse" GOTO ErrorExit END PRINT "Sent Response Message: " PRINT " << " : respMessage PRINT ""
3-45
NEXT
********************************* * Terminate the Session * ********************************* retCode = amTerminate(hSession, POLICY, reasonCode) IF retCode # AMCC_OK THEN function = "amTerminate" GOTO ErrorExit END
STOP ErrorExit: PRINT "Error/Warning encountered in function " : function PRINT " retCode = " : retCode IF retCode = AMCC_WARNING OR retCode = AMCC_FAILED THEN PRINT " reasonCode = " : reasonCode END END
3-46
Additional Reading
Interested readers are encouraged to refer to the following publications, which are available for download from http://www.ibm.com/shop/publications/order. MQSeries Primer MQSeries Application Messaging Interface MQSeries Application Programming Guide MQSeries Clients
3-47
Chapter
Creating XML Documents
4
. . . . . . . . . . . . . . . . . . . . . . 4-2 4-2 4-3 4-3 4-4 4-4 4-4 4-6 4-7 4-7 4-11 4-12 4-19 4-20 4-21 4-22 4-36 4-36 4-38 4-39 4-39 4-62
XML for IBM UniVerse . . . . . . . . . . . . Document Type Definitions . . . . . . . . . . The Document Object Model (DOM) . . . . . . . Well-Formed and Valid XML Documents . . . . . Creating an XML Document from RetrieVe . . . . . . Create the &XML& File . . . . . . . . . . . Mapping Modes . . . . . . . . . . . . . The Mapping File . . . . . . . . . . . . . . Distinguishing Elements . . . . . . . . . . . Root Element Attributes . . . . . . . . . . . Association Elements . . . . . . . . . . . . Mapping File Example . . . . . . . . . . . How Data is Mapped . . . . . . . . . . . . Mapping Example . . . . . . . . . . . . . Creating an XML Document. . . . . . . . . . Examples . . . . . . . . . . . . . . . . Creating an XML Document with UniVerse SQL . . . . Create the &XML& File . . . . . . . . . . . Processing Rules for UniVerse SQL SELECT Statements XML Limitations in UniVerse SQL . . . . . . . Examples . . . . . . . . . . . . . . . . UniVerse BASIC Example. . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . .
C:\Program Files\Adobe\FrameMaker7.0\UniVerse 10.2\basicext\Ch4TOC.fm September 22, 2006 3:24 pm UniVerse Basic
XML for IBM UniVerse

The Extensible Markup Language (XML) is a markup language used to define, validate, and share document formats. It enables you to tailor document formats to specifications unique to your application by defining your own elements, tags, and attributes. Note: XML describes how a document is structured, not how a document is displayed. XML was developed by the World Wide Web Consortium (W3C), who describe XML as: The Extensible Markup Language (XML) is the universal format for structured documents and data on the Web. An XML document consists of a set of tags that describe the structure of data. Unlike HTML, you can write your own tags. You can use XML to describe any type of data so that it is cross-platform and machine independent. For detailed information about XML, see the W3C website at http://www.w3.org/TR/REC-xml.
Document Type Definitions

You must define the rules of the structure of your XML document. These rules may be part of the XML document, and are called the Document Type Definition, or DTD. The DTD provides a list of elements, tags, attributes, and entities contained in the document, and describes their relationship to each other. A DTD can be external or internal. External DTD An external DTD is a separate document from the XML document, residing outside of your XML document. External DTDs can be applied to many different XML documents. If you need to change the DTD, you can make the change once, and all referencing XML documents are updated automatically. Internal DTD An internal DTD resides in the XML document as part of the header of the document, and applies only to that XML document. You can combine external DTDs with internal DTDs in an XML document.
4-2
The Document Object Model (DOM)

The Document Object Model (DOM) is a platform- and language-independent interface that enables programs and scripts to dynamically access and update the content, structure, and style of documents. A DOM is a formal way to describe an XML document to another application or programming language. You can describe the XML document as a tree, with nodes representing elements, attributes, entities, an text.
Well-Formed and Valid XML Documents

An XML document is either well-formed or valid: Well-formed XML documents must follow XML rules. All XML documents must be well-formed. Valid XML documents are both well-formed, and follow the rules of a specific DTD. Not all XML documents must be valid. For optimum exchange of data, you should try to ensure that your XML documents are valid.
Creating an XML Document from RetrieVe

You can create an XML document from UniVerse files through RetrieVe. To create an XML document through RetrieVe, complete the following steps:
1.
Analyze the DTD associated with the application to which you are sending the XML file. Determine which of your dictionary attributes correspond to the DTD elements. Create an XML mapping file, if necessary. List the appropriate fields using the LIST command.
2. 3.
Create the &XML& File

UniVerse stores XML mapping files in the &XML& directory file. To create this file, enter the following command: CREATE.FILE &XML& 19
Mapping Modes
UniVerse supports three modes for mapping data to XML files. These modes are: Attribute-centric Element-centric Mixed
Attribute-centric Mode
In the attribute-centric mode, which is the default mode, each record displayed in the query statement becomes an XML element. The following rules apply to the record fields: Each singlevalued field becomes an attribute within the element. Each multivalued or multi-subvalued field becomes a sub-element of the record element. The name of the sub-element is association_name-MV.
4-4
Within a sub-element, each multivalued field becomes an attribute of the sub-element. Associated multi-subvalued fields become another nested sub-element of the sub-element. The name of this nested sub-element is association_name-MS. If there are no associated multi-subvalued fields, the sub-element name is field_name-MV/MS. This is the default mapping scheme. You can change the default by defining maps in the &XML& file.
Element-centric Mode
In the element-centric mode, as in the attribute-centric mode, each record becomes an XML element. The following rules apply: Each singlevalued field becomes a simple sub-element of the element, containing no nested sub-elements. The value of the field becomes the value of the sub-element. Each association whose multivalued and multi-subvalued fields are included in the query statement form a complex sub-element. In the subelement, each multivalued field belonging to the association becomes a subelement that may contain multi-subvalued sub-elements. By default, UniVerse converts text marks to an empty string. Specify that you want to use element-centric mapping by using the ELEMENTS keyword in the RetrieVe statement.
Mixed Mode
In the mixed-mode, you create your own map file, where you specify which fields are treated as attribute-centric and which fields are treated as element-centric. Field-level mapping overrides the mode you specify in the RetrieVe.
The Mapping File

If you want to use mixed-mode, you must create a mapping record in the &XML& file. This mapping record contains those fields that you want to treat as elementcentric. If a field is not defined in the mapping record, UniVerse treats it as attributecentric. Warning: The attribute type definition for a multivalued or multi-subvalued field in a UniVerse dictionary record is M. If you know that a field is multi-subvalued, you must define it as such in a mapping file, or the XML document you create may not be accurate. A mapping file has the following format: <?XML version=1.0?> <U2xml-mapping xmlns:U2xml=http://www.informix.com/U2-xml>  <U2xml :mapping file=file_name field=dictionary_display_name map-to=name_in_xml_doc namespace=namespace_name type=MV | MS hastm=yes | 1 treated-as=attribute | element root=root_element_name record=record_element_name association-mv=mv_level_assoc_name association-ms=ms_level_assoc_name format = format -pattern.. conversion = conversion code encode=encoding characters /> ...</U2xml-mapping> Note: UniVerse supports multiple cases of the U2XML_extraction tag. Valid cases are: U2XML_extraction U2xml_extraction u2xml_extraction
4-6
The XML mapping file is, in itself, and XML file. There are three types of significant elements, the root element, the field element, and the association element. The root Element The root element describes the global options that control different output formats, such as the schema type, targetNamespace, hideroot, hidemv, and hidems. You can also use the root element to change the default root element name, or the record element name. You should have only one root element in the mapping file. The field Element UniVerse uses the field element to change the characteristics of a particular fields XML output attributes, such as the display name, the format, or the conversion. The association Element UniVerse uses the association element to change the display name of an association. By default, this name is the association phrase name, together with -MV or -MS.
Distinguishing Elements
You can distinguish the root element from the field and association elements because the root element does not define a field or association element. Both the field element and the association element must have the file and field attribute to define the file name and the field name in the file that has been processed. Generally, the field name is a data-descriptor or I-descriptor, making it a field element. If the field name is an association phrase, it is an association element.
Root Element Attributes

The default root element name in an XML document is ROOT. You can change the name of the root element, as shown in the following example:
root=root-element-name
Record Name Attribute

The default record name is FILENAME_record. The record attribute in the root element changes the record name. The following example illustrates the record attribute:
record=record-element-name
The Hideroot Attribute

The Hideroot attribute allows you to specify to only create a segment of an XML document, for example, using the SAMPLE keyword and other conditional clauses. If Hideroot is set to 1, UniVerse only creates the record portion of the XML document, it does not create a DTD or XMLSchema. The default value is 0.
Hideroot=1/0
The Hidemv and Hidems Attributes

Normally, when UniVerse processes multivalued or multi-subvalued fields, UniVerse adds another level of elements to produce multiple levels of nesting. You have the option of disabling this additional level by adding the Hidemv and Hidems attributes to the mapping file. When these options are on, the generated XML document and the associated DTD or XMLSchema will have fewer levels of nesting.
Hidemv=0/1/yes/no Hidems=0/1/yes/no
Note: If the document is created in attribute mode, it is not possible to eliminate the extra level of element tags. You can also use these attributes with XMLEXECUTE().
Namespace Attributes
UniVerse provides the following attributes for defining namespaces: namespace=name-space-name xmlns:name-space-name=URL targetnamespace=URL UniVerse displays the targetnamespace attribute in the XMLSchema as targetNamespace, and uses the URL you define in the XML document to define schemaLocation. If you define the targetnamespace and other explicit namespace definitions, UniVerse checks if the explictly defined namespace has the same URL as the targetnamespace. If it does, UniVerse uses the namespace name to qualify the schema element, and the XML document element name.
4-8
If there is no other namespace explictly defined, UniVerse creates a defaultnamespace in the schema file as shown in the following example:
xmlns=targetnamespace URL
In this case, UniVerse does not qualify the schema element or the XML document element. UniVerse uses the namespace attributes and xmlns:name-space-name together to define the namespace. All namespaces defined in the root element are for global element namespace qualifiers only. Note: Namespace is used primarily for XMLSchema. If you do not specify XMLSchema in the command line, UniVerse will not use a global namespace to qualify any element the instance document.
Schema Attribute
The default schema format is ref type schema. You can use the Schema attribute to define a different schema format.
schema=inline|ref|type
Elementformdefault and Attributeformdefault Attributes

UniVerse uses the elementformdefault and attributeformdefault attributes in the XMLSchema. If you use them together with the namespace attribute in the root element, you can indicate all of the local elements and local attributes need to be qualified with the namespace. UniVerse processes all attributes in the field element and association element in the same way as UniVerse 10.0.
File Attribute
UniVerse uses the file attribute to process both RetrieVe and SQL commands. If you do not define the file attribute exactly as it is used on the command line, this field element will not be properly processed.
File=filename
Field Attribute
The field attribute defines the field name. The field can be either a data-descriptor or an I-descriptor.
Field=field-name
Map-to Attribute
The Map-to attribute allows you to define a new attribute tag or element tag name for the field. By default, UniVerse used the dictionary field name for the element or attribute name tag.
Type Attribute
The Type attribute defines how to treat the field in the XML document, either as a multivalued field or a multi-subvalued field.
type=MV|MS
Treated-as Attribute
The Treated-as attribute determines if the field should be treated as an element or attribute in the generated XML document.
Encode Attribute
The Encode attribute encodes unprintable characters with a macro.
encode=0x7B 0x7D
Conv Attribute
The Conv attribute changes the conversion defined in the dictionary record to the conversion you define.
conv=new conv code | conversion = new conversion code
4-10
Fmt Attribute
The Fmt attribute changes the format defined in the dictionary record to the format you define.
fmt=new format code | format = new format code
Association Elements
An association element contains the following four attribute: file = file name field = association phrase name association-mv = new multivalue element tag association-ms = new multi-subvalue element tag
Mapping File Example

The following example illustrates a mapping file:
<U2 root="MAIN" schema="type" targetnamespace="www.ibm.com" /> <U2 file="STUDENT.F" field = "CGA" association-mv="Term" association-ms="Courses_Taken" /> <U2 file="STUDENT.F" field = "COURSE_NBR" type="MS" treated-as="element" /> <U2 file="STUDENT.F" field = "SEMESTER" map-to="SEMESTER" type="MV" treated-as="element" /> <U2 file="STUDENT.F" field = "COURSE_GRD" map-to="COURSE_GRD" type="ms" treated-as="element" /> <U2 file="STUDENT.F" field = "COURSE_NAME" type="ms" treated-as="element" />
4-12
The next example illustrates an XMLSchema using the mapping file in the previous example:
<?xml version="1.0"?> <xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema" targetNamespace="www.ibm.com" > <xsd:annotation> <xsd:documentation xml:lang="en"> Acct:D:\uvxml Cmd:LIST STUDENT.F LNAME SEMESTER COURSE_NBR TOXML XMLMAPPING student.map WITHSCHEMA TO xxxx </xsd:documentation> </xsd:annotation> <xsd:element name="MAIN"> <xsd:complexType> <xsd:sequence maxOccurs="unbounded"> <xsd:element name="STUDENT.F_record" type="ibm:STUDENT.F_recordType" maxOccurs="unbounded"/> </xsd:sequence> </xsd:complexType> </xsd:element> <xsd:complexType name="STUDENT.F_recordType"> <xsd:sequence maxOccurs="unbounded"> <xsd:element name="SEMESTER" type="xsd:string" minOccurs="0" maxOccurs="unbounded"/> <xsd:element name="Courses_Taken" type="ibm:Courses_TakenType" minOccurs="0" maxOccurs="unbounded"/> </xsd:sequence> <xsd:attribute name="_ID"/> <xsd:attribute name="LNAME"/> </xsd:complexType> <xsd:complexType name="Courses_TakenType"> <xsd:sequence maxOccurs="unbounded"> <xsd:element name="COURSE_NBR" type="xsd:string" minOccurs="0" maxOccurs="unbounded"/> </xsd:sequence> </xsd:complexType> </xsd:schema>
4-13
The next example illustrates an XML document created using the mapping file in the previous example.
<?xml version="1.0"?> <ibm:MAIN xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation= "www.ibm.com xxxx.xsd" xmlns:ibm="www.ibm.com" > <STUDENT.F_record _ID = "978766676" LNAME = "Muller"> <Term> <SEMESTER>FA93</SEMESTER> <Courses_Taken> <COURSE_NBR>FA120</COURSE_NBR> <COURSE_NBR>FA230</COURSE_NBR> <COURSE_NBR>HY101</COURSE_NBR> </Courses_Taken> <SEMESTER>SP94</SEMESTER> <Courses_Taken> <COURSE_NBR>FA121</COURSE_NBR> <COURSE_NBR>FA231</COURSE_NBR> <COURSE_NBR>HY102</COURSE_NBR> </Courses_Taken> </Term> </STUDENT.F_record> .. </ibm:MAIN>
The next example illustrates the same mapping file, with the following root element added:
<U2 root="MAIN" targetnamespace="www.ibm.com" hidemv ="1" hidems="1" />
4-14
The next example illustrates an XMLSchema file generated from the mapping file with the root element described in the previous example:
<?xml version="1.0"?> <xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema" targetNamespace="www.ibm.com" xmlns="www.ibm.com"> <xsd:annotation> <xsd:documentation xml:lang="en"> account: D:\uvxml command: LIST STUDENT.F LNAME SEMESTER COURSE_NBR TOXML WITHSCHEMA XMLMAPPIN G student.f.map </xsd:documentation> </xsd:annotation> <xsd:element name="MAIN"> <xsd:complexType> <xsd:sequence maxOccurs="unbounded"> <xsd:element ref="STUDENT.F_record" maxOccurs="unbounded"/> </xsd:sequence> </xsd:complexType> </xsd:element> <xsd:element name="STUDENT.F_record"> <xsd:complexType> <xsd:sequence maxOccurs="unbounded"> <xsd:sequence maxOccurs='unbounded'> <xsd:element ref="SEMESTER" minOccurs="0" maxOccurs="unbounded"/> <xsd:sequence maxOccurs='unbounded'> <xsd:element ref="COURSE_NBR" minOccurs="0" maxOccurs="unbounded"/> </xsd:sequence> </xsd:sequence> </xsd:sequence> <xsd:attribute name="_ID"/> <xsd:attribute name="LNAME"/> </xsd:complexType> </xsd:element> <xsd:element name="SEMESTER" type="xsd:string"/> <xsd:element name="COURSE_NBR" type="xsd:string"/> </xsd:schema>
4-15
The next example illustrates an XML file generated from the mapping file with the root element described in the previous example:
<?xml version="1.0"?> <xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema" targetNamespace="www.ibm.com" xmlns="www.ibm.com" > <xsd:annotation> <xsd:documentation xml:lang="en"> Acct:D:\uvxml Cmd:LIST STUDENT.F LNAME SEMESTER COURSE_NBR TOXML XMLMAPPING student.map WITHSCHEMA TO xxxx </xsd:documentation> </xsd:annotation> <xsd:element name="MAIN"> <xsd:complexType> <xsd:sequence maxOccurs="unbounded"> <xsd:element ref="STUDENT.F_record" maxOccurs="unbounded"/> </xsd:sequence> </xsd:complexType> </xsd:element> <xsd:element name="STUDENT.F_record"> <xsd:complexType> <xsd:sequence maxOccurs="unbounded"> <xsd:element ref="SEMESTER" minOccurs="0" maxOccurs="unbounded"/> <xsd:element ref="COURSE_NBR" minOccurs="0" maxOccurs="unbounded"/> </xsd:sequence> <xsd:attribute name="_ID"/> <xsd:attribute name="LNAME"/> </xsd:complexType> </xsd:element> <xsd:element name="SEMESTER" type="xsd:string"/> <xsd:element name="COURSE_NBR" type="xsd:string"/> </xsd:schema> <?xml version="1.0"?> <MAIN xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <STUDENT.F_record _ID = "424325656" LNAME = "Martin"> <SEMESTER>SP94</SEMESTER> <COURSE_NBR>PY100</COURSE_NBR> <COURSE_NBR>PE100</COURSE_NBR> </STUDENT.F_record> <STUDENT.F_record _ID = "521814564" LNAME = "Smith"> <SEMESTER>FA93</SEMESTER> <COURSE_NBR>CS130</COURSE_NBR> <COURSE_NBR>CS100</COURSE_NBR> <COURSE_NBR>PY100</COURSE_NBR> <SEMESTER>SP94</SEMESTER> <COURSE_NBR>CS131</COURSE_NBR> <COURSE_NBR>CS101</COURSE_NBR>
4-16
<COURSE_NBR>PE220</COURSE_NBR> </STUDENT.F_record> </MAIN>
Conversion Code Considerations

UniVerse XML follows the following rules when extracting data from database files: If the dictionary record of a field you are extracting contains a conversion code, UniVerse XML uses that conversion code when extracting data from database files. If you specify a conversion code in the mapping file, the conversion code in the mapping file overrides the conversion code specified in the dictionary record. If you specify a conversion code using the CONV keyword during the execution of a RetrieVe statement, that conversion code overrides both the conversion code specified in the mapping file, and the conversion code specified in the dictionary record.
Formatting Considerations
UniVerse XML does not generally apply the dictionary format pattern to the extracted data. To specify a format, define it in the mapping file. If you specify a format using the FMT keyword in a RetrieVe statement, that format will override the format defined in the mapping file.
Mapping File Encoding

For special character encountered in data, UniVerse XML uses the default XML entities to encode the data. For example, < becomes <, > becomes >, & becomes &, and becomes ". However, UniVerse XML does not convert to ', unless you specify it in attribute encode. (<, >, &, ', and " are all built-in entities for the XML parser).
4-17
Use the encode field in the mapping file to add flexibility to the output. You can define special characters to encode in hexadecimal form. UniVerse encodes these special characters to &#x##;. For example, if you want the character { to be encoded for field FIELD1, specify the following encode value in the mapping file for FIELD1: encode=0x7B In this case, UniVerse XML will convert { found in the data of FIELD1 to &#x7B. You can also use this type of encoding for any nonprintable character. If you need to define more than one character for a field, add a space between the hexadecimal definitions. For example, if you want to encode both { and }, the encode value in the mapping file should look like the following example: encode=0x7B 0x7D
The following example illustrates a mapping file for the STUDENT file.
<?XML version=1.0?> <U2xml-mapping xmlns:U2xml=http://www.ibm.com/U2-xml> <! -- this is a comment --> <U2xml:mapping record=STUDENT_rec root = SCHOOL xmlns:IBM=http://www.IBM.com namespace=IBM /> <U2XML:mapping file=STUDENT field = SEMESTER type=MV treated-as=element /> <U2XML:mapping file=STUDENT field = COURSE_NBR type=MS treated-as=element /> <U2XML:mapping file=STUDENT field = COURSE_GRD type=MS treated-as=element /> <U2XML:mapping file=STUDENT field = COURSE_NAME type=MS treated-as=element /> </U2xml-mapping>
4-18
Notice that the SEMESTER, COURSE_NBR, COURSE_GRD, and COURSE_NAME fields are to be treated as elements. When you create the XML document, these fields will produce element-centric XML data. Any other fields listed in the query statement will produce attribute-centric XML data, since attributecentric is the default mode. Additionally, COURSE_NBR, COURSE_GRD, and COURSE_NAME are defined as multi-subvalued fields. If they were not, UniVerse would create the XML data as if they were multivalued attributes.
How Data is Mapped

Regardless of the mapping mode you choose, the outer-most element in the XML document is created as <ROOT>, by default. The name of each record element defaults to <file_name>. You can change these mapping defaults in the mapping file, as shown in the following example:
<U2xml:mapping root=root_name record=record_name/>
4-19
Mapping Example
The following examples illustrate creation of XML documents. These examples use the STUDENT file, which contains the following fields:
>LIST DICT STUDENT DICT STUDENT 12:50:05pm 10 Oct 2001 Page 1
Type & Field......... Field. Field........ Conversion.. Column......... Output Depth & Name.......... Number Definition... Code........ Heading........ Format Assoc.. @ID ID D D 0 0 STUDENT STUDENT 10L 12R### -##-## ## 15T 10L 4L 4L 8L 4L 5L 3L 10L S S
LNAME FNAME MAJOR MINOR ADVISOR SEMESTER CGA COURSE_NBR CGA COURSE_GRD CGA TEACHER CGA
D D D D D D D D I
1 2 3 4 5 6 7 8 TRANS('COURSE S',COURSE_NBR ,'TEACHER','X ') TRANS('COURSE
Last Name First Name Major Minor Advisor Term Crs # GD Teacher
S S S S S M M M M
COURSE_NAME I CGA Press any key to continue... DICT STUDENT 12:50:07pm
Course Name
25L
10 Oct 2001
Page
Type & Field......... Field. Field........ Conversion.. Column......... Output Depth & Name.......... Number Definition... Code........ Heading........ Format Assoc.. S',COURSE_NBR ,'NAME','X') SUBR('GPA1',C MD3 OURSE_HOURS,C OURSE_GRD) TRANS('COURSE S',COURSE_NBR ,CREDITS,'X') SEMESTER COURSE_NBR COURSE_NAME
GPA1
GPA
5R
COURSE_HOURS CGA
Hours
5R
CGA
PH
4-20
COURSE_GRD COURSE_HOURS TEACHER @ORIGINAL @SYNONYM S S @ID ID M M
Press any key to continue... DICT STUDENT 12:50:08pm 10 Oct 2001 Page 3
Type & Field......... Field. Field........ Conversion.. Column......... Output Depth & Name.......... Number Definition... Code........ Heading........ Format Assoc.. 17 records listed. >
Creating an XML Document

To create an XML document using RetrieVe, use the LIST command. LIST [DICT | USING [DICT] dictname] filename ... [TOXML [ELEMENTS] [WITHDTD] [XMLMAPPING mapping_file]]... The following table describes each parameter of the syntax.
Parameter DICT USING [ DICT ] dictname filename Description Lists records in the file dictionary of filename. If you do not specify DICT, records in the data file are listed. If DICT is not specified, uses dictname as the dictionary of filename. If DICT is specified, the dictionary of dictname is used as the dictionary of filename. The file whose records you want to list. You can specify filename anywhere in the sentence. LIST uses the first word in the sentence that has a file descriptor in the VOC file as the filename. Outputs LIST results in XML format. LIST Parameters
TOXML
4-21
Parameter ELEMENTS WITHDTD XMLMAPPING mapping_file
Description Outputs results in element-centric format. I Output produces a DTD corresponding to the query. Specifies a mapping file containing transformation rules for display. This file must exist in the &XML& file. LIST Parameters (Continued)
For detailed information about the LIST command, see the RetrieVe Users Guide.
Examples
Note: The examples in this section use the STUDENT.F and COURSES files. To create these files, execute the MAKE.DEMO.FILES from the TCL prompt.
Creating an Attribute-centric XML Document

This example lists fields from the STUDENT file, using the TOXML keyword, to create an XML document. By default, UniVerse uses the attribute-centric mapping mode.
4-22
Note: UniVerse does not store the XML document unless you execute the COMO ON statement prior to executing the RetrieVe statement. If you execute COMO ON, the XML document is stored in the &COMO& file. You can also direct the output to the &HOLD& file using SETPTR, or the printer using LPTR.
>LIST STUDENT.F SEMESTER COURSE_NBR COURSE_GRD COURSE_NAME TOXML Validate XML name changed display name from '@ID' to '_ID'
<?xml version="1.0"?> <ROOT> <STUDENT.F_record _ID = "424325656"> <CGA-MV SEMESTER = "SP94" COURSE_NBR = "PY100" COURSE_GRD = "C" COURSE_NAME = "Introduction to Psychology" COURSE_NBR = "PE100" COURSE_GRD = "C" COURSE_NAME = "Golf - I"/> </STUDENT.F_record> <STUDENT.F_record _ID = "521814564"> <CGA-MV SEMESTER = "FA93" COURSE_NBR = "CS130" COURSE_GRD = "A" COURSE_NAME = "Intro to Operating Systems" COURSE_NBR = "CS100" COURSE_GRD = "B" COURSE_NAME = "Intro to Computer Science" COURSE_NBR = "PY100" COURSE_GRD = "B" COURSE_NAME = "Introduction to Psychology"/> <CGA-MV SEMESTER = "SP94" COURSE_NBR = "CS131" COURSE_GRD = "B" COURSE_NAME = "Intro to Operating Systems" COURSE_NBR = "CS101" COURSE_GRD = "B" COURSE_NAME = "Intro to Computer Science" COURSE_NBR = "PE220" COURSE_GRD = "A" COURSE_NAME = "Racquetball"/> </STUDENT.F_record> <STUDENT.F_record _ID = "978766676"> <CGA-MV SEMESTER = "FA93" COURSE_NBR = "FA120" COURSE_GRD = "A" COURSE_NAME = "Finger Painting" COURSE_NBR = "FA230" COURSE_GRD = "C" COURSE_NAME = "Photograp hy Principals" COURSE_NBR = "HY101" COURSE_GRD = "C" COURSE_NAME = "Western Civi lization"/> <CGA-MV SEMESTER = "SP94" COURSE_NBR = "FA121" COURSE_GRD = "A" COURSE_NAME = "Watercorlors" COURSE_NBR = "FA231" COURSE_GRD = "B" COURSE_NAME = "Photography Practicum" COURSE_NBR = "HY102" COURSE_GRD = "I" COURSE_NAME = "Western Civiliza tion - 1500 to 1945"/> </STUDENT.F_record> <STUDENT.F_record _ID = "221345665"> <CGA-MV SEMESTER = "FA93" COURSE_NBR = "EG110" COURSE_GRD = "C"
4-23
COURSE_NAME = "Engineering Principles" COURSE_NBR = "MA220" COURSE_GRD = "B" COURSE_NAME = "Ca lculus- I" COURSE_NBR = "PY100" COURSE_GRD = "B" COURSE_NAME = "Introduction to Psychology"/> <CGA-MV SEMESTER = "SP94" COURSE_NBR = "EG140" COURSE_GRD = "B" COURSE_NAME = "Fluid Mechanics" COURSE_NBR = "EG240" COURSE_GRD = "B" COURSE_NAME = "Circut Th eory" COURSE_NBR = "MA221" COURSE_GRD = "B" COURSE_NAME = "Calculus - II"/> </STUDENT.F_record> <STUDENT.F_record _ID = "291222021"> <CGA-MV SEMESTER = "SP94" COURSE_NBR = "FA100" COURSE_GRD = "B" COURSE_NAME = "Visual Thinking"/> </STUDENT.F_record> <STUDENT.F_record _ID = "414446545"> <CGA-MV SEMESTER = "FA93" COURSE_NBR = "CS104" COURSE_GRD = "D" COURSE_NAME = "Database Design" COURSE_NBR = "MA101" COURSE_GRD = "C" COURSE_NAME = "Math Prin cipals" COURSE_NBR = "FA100" COURSE_GRD = "C" COURSE_NAME = "Visual Thinking"/> <CGA-MV SEMESTER = "SP94" COURSE_NBR = "CS105" COURSE_GRD = "B" COURSE_NAME = "Database Design" COURSE_NBR = "MA102" COURSE_GRD = "C" COURSE_NAME = "Algebra" COURSE_NBR = "PY100" COURSE_GRD = "C" COURSE_NAME = "Introduction to Psychology" /> </STUDENT.F_record> </ROOT> >
4-24
Creating an Element-centric XML Document

To create an element-centric XML document, use the ELEMENTS keyword.
>LIST STUDENT.F SEMESTER COURSE_NBR COURSE_GRD COURSE_NAME TOXML ELEMENTS Validate XML name changed display name from '@ID' to '_ID'
<?xml version="1.0"?> <ROOT> <STUDENT.F_record _ID = "424325656"> <CGA-MV SEMESTER = "SP94" COURSE_NBR = "PY100" COURSE_GRD = "C" COURSE_NAME = "Introduction to Psychology" COURSE_NBR = "PE100" COURSE_GRD = "C" COURSE_NAME = "Golf - I"/> </STUDENT.F_record> <STUDENT.F_record _ID = "521814564"> <CGA-MV SEMESTER = "FA93" COURSE_NBR = "CS130" COURSE_GRD = "A" COURSE_NAME = "Intro to Operating Systems" COURSE_NBR = "CS100" COURSE_GRD = "B" COURSE_NAME = "Intro to Computer Science" COURSE_NBR = "PY100" COURSE_GRD = "B" COURSE_NAME = "Introduction to Psychology"/> <CGA-MV SEMESTER = "SP94" COURSE_NBR = "CS131" COURSE_GRD = "B" COURSE_NAME = "Intro to Operating Systems" COURSE_NBR = "CS101" COURSE_GRD = "B" COURSE_NAME = "Intro to Computer Science" COURSE_NBR = "PE220" COURSE_GRD = "A" COURSE_NAME = "Racquetball"/> </STUDENT.F_record> <STUDENT.F_record _ID = "978766676"> <CGA-MV SEMESTER = "FA93" COURSE_NBR = "FA120" COURSE_GRD = "A" COURSE_NAME = "Finger Painting" COURSE_NBR = "FA230" COURSE_GRD = "C" COURSE_NAME = "Photograp hy Principals" COURSE_NBR = "HY101" COURSE_GRD = "C" COURSE_NAME = "Western Civi lization"/> <CGA-MV SEMESTER = "SP94" COURSE_NBR = "FA121" COURSE_GRD = "A" COURSE_NAME = "Watercorlors" COURSE_NBR = "FA231" COURSE_GRD = "B" COURSE_NAME = "Photography Practicum" COURSE_NBR = "HY102" COURSE_GRD = "I" COURSE_NAME = "Western Civiliza tion - 1500 to 1945"/> </STUDENT.F_record> <STUDENT.F_record _ID = "221345665"> <CGA-MV SEMESTER = "FA93" COURSE_NBR = "EG110" COURSE_GRD = "C" COURSE_NAME =
4-25
"Engineering Principles" COURSE_NBR = "MA220" COURSE_GRD = "B" COURSE_NAME = "Ca lculus- I" COURSE_NBR = "PY100" COURSE_GRD = "B" COURSE_NAME = "Introduction to Psychology"/> <CGA-MV SEMESTER = "SP94" COURSE_NBR = "EG140" COURSE_GRD = "B" COURSE_NAME = "Fluid Mechanics" COURSE_NBR = "EG240" COURSE_GRD = "B" COURSE_NAME = "Circut Th eory" COURSE_NBR = "MA221" COURSE_GRD = "B" COURSE_NAME = "Calculus - II"/> </STUDENT.F_record> <STUDENT.F_record _ID = "291222021"> <CGA-MV SEMESTER = "SP94" COURSE_NBR = "FA100" COURSE_GRD = "B" COURSE_NAME = "Visual Thinking"/> </STUDENT.F_record> <STUDENT.F_record _ID = "414446545"> <CGA-MV SEMESTER = "FA93" COURSE_NBR = "CS104" COURSE_GRD = "D" COURSE_NAME = "Database Design" COURSE_NBR = "MA101" COURSE_GRD = "C" COURSE_NAME = "Math Prin cipals" COURSE_NBR = "FA100" COURSE_GRD = "C" COURSE_NAME = "Visual Thinking"/> <CGA-MV SEMESTER = "SP94" COURSE_NBR = "CS105" COURSE_GRD = "B" COURSE_NAME = "Database Design" COURSE_NBR = "MA102" COURSE_GRD = "C" COURSE_NAME = "Algebra" COURSE_NBR = "PY100" COURSE_GRD = "C" COURSE_NAME = "Introduction to Psychology" /> </STUDENT.F_record> </ROOT> >
4-26
Creating a Mixed-mode XML Document

Using the mapping file described in The Mapping File, the following example creates a mixed-mode XML document. To use a mapping file, specify the XMLMAPPING keyword in the RetrieVe statement.
>LIST STUDENT.F LNAME FNAME SEMESTER COURSE_NBR COURSE_GRD COURSE_NAME TOXML XMLMAPPING STUDENT_MAP Validate XML name changed display name from '@ID' to '_ID'
<?xml version="1.0"?> <SCHOOL xmlns:IBM="HTTP://WWW.IBM.COM" > <IBM:STUDENT_REC _ID = "424325656" LNAME = "Martin" FNAME = "Sally"> <CGA-MV> <SEMESTER>SP94</SEMESTER> <CGA-MS> <COURSE_NBR>PY100</COURSE_NBR> <COURSE_GRD>C</COURSE_GRD> <COURSE_NAME>Introduction to Psychology</COURSE_NAME> </CGA-MS> <CGA-MS> <COURSE_NBR>PE100</COURSE_NBR> <COURSE_GRD>C</COURSE_GRD> <COURSE_NAME>Golf - I</COURSE_NAME> </CGA-MS> </CGA-MV> </IBM:STUDENT_REC> <IBM:STUDENT_REC _ID = "521814564" LNAME = "Smith" FNAME = "Harry"> <CGA-MV> <SEMESTER>FA93</SEMESTER> <CGA-MS> <COURSE_NBR>CS130</COURSE_NBR> <COURSE_GRD>A</COURSE_GRD> <COURSE_NAME>Intro to Operating Systems</COURSE_NAME> </CGA-MS> <CGA-MS> <COURSE_NBR>CS100</COURSE_NBR> <COURSE_GRD>B</COURSE_GRD> <COURSE_NAME>Intro to Computer Science</COURSE_NAME> </CGA-MS> <CGA-MS> <COURSE_NBR>PY100</COURSE_NBR> <COURSE_GRD>B</COURSE_GRD> <COURSE_NAME>Introduction to Psychology</COURSE_NAME> </CGA-MS> </CGA-MV> <CGA-MV>
4-27
<SEMESTER>SP94</SEMESTER> <CGA-MS> <COURSE_NBR>CS131</COURSE_NBR> <COURSE_GRD>B</COURSE_GRD> <COURSE_NAME>Intro to Operating Systems</COURSE_NAME> </CGA-MS> <CGA-MS> <COURSE_NBR>CS101</COURSE_NBR> <COURSE_GRD>B</COURSE_GRD> <COURSE_NAME>Intro to Computer Science</COURSE_NAME> </CGA-MS> <CGA-MS> <COURSE_NBR>PE220</COURSE_NBR> <COURSE_GRD>A</COURSE_GRD> <COURSE_NAME>Racquetball</COURSE_NAME> </CGA-MS> </CGA-MV> </IBM:STUDENT_REC> <IBM:STUDENT_REC _ID = "978766676" LNAME = "Muller" FNAME = "Gerhardt"> <CGA-MV> <SEMESTER>FA93</SEMESTER> <CGA-MS> <COURSE_NBR>FA120</COURSE_NBR> <COURSE_GRD>A</COURSE_GRD> <COURSE_NAME>Finger Painting</COURSE_NAME> </CGA-MS> <CGA-MS> <COURSE_NBR>FA230</COURSE_NBR> <COURSE_GRD>C</COURSE_GRD> <COURSE_NAME>Photography Principals</COURSE_NAME> </CGA-MS> <CGA-MS> <COURSE_NBR>HY101</COURSE_NBR> <COURSE_GRD>C</COURSE_GRD> <COURSE_NAME>Western Civilization</COURSE_NAME> </CGA-MS> </CGA-MV> <CGA-MV> <SEMESTER>SP94</SEMESTER> <CGA-MS> <COURSE_NBR>FA121</COURSE_NBR> <COURSE_GRD>A</COURSE_GRD> <COURSE_NAME>Watercorlors</COURSE_NAME> </CGA-MS> <CGA-MS> <COURSE_NBR>FA231</COURSE_NBR> <COURSE_GRD>B</COURSE_GRD> <COURSE_NAME>Photography Practicum</COURSE_NAME> </CGA-MS> <CGA-MS> <COURSE_NBR>HY102</COURSE_NBR> <COURSE_GRD>I</COURSE_GRD> <COURSE_NAME>Western Civilization - 1500 to
4-28
1945</COURSE_NAME> </CGA-MS> </CGA-MV> </IBM:STUDENT_REC> <IBM:STUDENT_REC _ID = "221345665" LNAME = "Miller" FNAME = "Susan"> <CGA-MV> <SEMESTER>FA93</SEMESTER> <CGA-MS> <COURSE_NBR>EG110</COURSE_NBR> <COURSE_GRD>C</COURSE_GRD> <COURSE_NAME>Engineering Principles</COURSE_NAME> </CGA-MS> <CGA-MS> <COURSE_NBR>MA220</COURSE_NBR> <COURSE_GRD>B</COURSE_GRD> <COURSE_NAME>Calculus- I</COURSE_NAME> </CGA-MS> <CGA-MS> <COURSE_NBR>PY100</COURSE_NBR> <COURSE_GRD>B</COURSE_GRD> <COURSE_NAME>Introduction to Psychology</COURSE_NAME> </CGA-MS> </CGA-MV> <CGA-MV> <SEMESTER>SP94</SEMESTER> <CGA-MS> <COURSE_NBR>EG140</COURSE_NBR> <COURSE_GRD>B</COURSE_GRD> <COURSE_NAME>Fluid Mechanics</COURSE_NAME> </CGA-MS> <CGA-MS> <COURSE_NBR>EG240</COURSE_NBR> <COURSE_GRD>B</COURSE_GRD> <COURSE_NAME>Circut Theory</COURSE_NAME> </CGA-MS> <CGA-MS> <COURSE_NBR>MA221</COURSE_NBR> <COURSE_GRD>B</COURSE_GRD> <COURSE_NAME>Calculus - II</COURSE_NAME> </CGA-MS> </CGA-MV> </IBM:STUDENT_REC> <IBM:STUDENT_REC _ID = "291222021" LNAME = "Smith" FNAME = "jojo"> <CGA-MV> <SEMESTER>SP94</SEMESTER> <CGA-MS> <COURSE_NBR>FA100</COURSE_NBR> <COURSE_GRD>B</COURSE_GRD> <COURSE_NAME>Visual Thinking</COURSE_NAME> </CGA-MS> </CGA-MV> </IBM:STUDENT_REC> <IBM:STUDENT_REC _ID = "414446545" LNAME = "Offenbach" FNAME =
4-29
"Karl"> <CGA-MV> <SEMESTER>FA93</SEMESTER> <CGA-MS> <COURSE_NBR>CS104</COURSE_NBR> <COURSE_GRD>D</COURSE_GRD> <COURSE_NAME>Database Design</COURSE_NAME> </CGA-MS> <CGA-MS> <COURSE_NBR>MA101</COURSE_NBR> <COURSE_GRD>C</COURSE_GRD> <COURSE_NAME>Math Principals</COURSE_NAME> </CGA-MS> <CGA-MS> <COURSE_NBR>FA100</COURSE_NBR> <COURSE_GRD>C</COURSE_GRD> <COURSE_NAME>Visual Thinking</COURSE_NAME> </CGA-MS> </CGA-MV> <CGA-MV> <SEMESTER>SP94</SEMESTER> <CGA-MS> <COURSE_NBR>CS105</COURSE_NBR> <COURSE_GRD>B</COURSE_GRD> <COURSE_NAME>Database Design</COURSE_NAME> </CGA-MS> <CGA-MS> <COURSE_NBR>MA102</COURSE_NBR> <COURSE_GRD>C</COURSE_GRD> <COURSE_NAME>Algebra</COURSE_NAME> </CGA-MS> <CGA-MS> <COURSE_NBR>PY100</COURSE_NBR> <COURSE_GRD>C</COURSE_GRD> <COURSE_NAME>Introduction to Psychology</COURSE_NAME> </CGA-MS> </CGA-MV> </IBM:STUDENT_REC> </SCHOOL> >
Notice in the XML document that LNAME and FNAME are attribute-centric, and the rest of the elements are element-centric.
4-30
Creating an XML Document with a DTD

If you only include the TOXML keyword in the RetrieVe statement, the resulting XML document does not include the DTD. To create an XML document that includes a DTD, use the WITHDTD keyword.
LIST STUDENT.F SEMESTER COURSE_NBR COURSE_GRD COURSE_NAME TOXML WITHDTD Validate XML name changed display name from '@ID' to '_ID'
<?xml version="1.0"?> <!DOCTYPE ROOT[ <!ELEMENT ROOT (STUDENT.F_record*)> <!ELEMENT STUDENT.F_record ( CGA-MV* )> <!ATTLIST STUDENT.F_record _ID CDATA #REQUIRED > <!ELEMENT CGA-MV EMPTY> <!ATTLIST CGA-MV SEMESTER CDATA #IMPLIED COURSE_NBR CDATA #IMPLIED COURSE_GRD CDATA #IMPLIED COURSE_NAME CDATA #IMPLIED > ]> <ROOT> <STUDENT.F_record _ID = "424325656"> <CGA-MV SEMESTER = "SP94" COURSE_NBR = "PY100" COURSE_GRD = COURSE_NAME = "Introduction to Psychology" COURSE_NBR = "PE100" COURSE_GRD = COURSE_NAME = "Golf - I"/> </STUDENT.F_record> <STUDENT.F_record _ID = "521814564"> <CGA-MV SEMESTER = "FA93" COURSE_NBR = "CS130" COURSE_GRD = COURSE_NAME = "Intro to Operating Systems" COURSE_NBR = "CS100" COURSE_GRD = COURSE_NAME = "Intro to Computer Science" COURSE_NBR = "PY100" COURSE_GRD = COURSE_NAME = "Introduction to Psychology"/> <CGA-MV SEMESTER = "SP94" COURSE_NBR = "CS131" COURSE_GRD = COURSE_NAME = "Intro to Operating Systems" COURSE_NBR = "CS101" COURSE_GRD = COURSE_NAME = "Intro to Computer Science" COURSE_NBR = "PE220" COURSE_GRD = COURSE_NAME = "Racquetball"/> </STUDENT.F_record> <STUDENT.F_record _ID = "978766676"> <CGA-MV SEMESTER = "FA93" COURSE_NBR = "FA120" COURSE_GRD =
"C" "C"
"A" "B" "B"
"B" "B" "A"
"A"
4-31
COURSE_NAME = "Finger Painting" COURSE_NBR = "FA230" COURSE_GRD = "C" COURSE_NAME = "Photograp hy Principals" COURSE_NBR = "HY101" COURSE_GRD = "C" COURSE_NAME = "Western Civi lization"/> <CGA-MV SEMESTER = "SP94" COURSE_NBR = "FA121" COURSE_GRD = "A" COURSE_NAME = "Watercorlors" COURSE_NBR = "FA231" COURSE_GRD = "B" COURSE_NAME = "Photography Practicum" COURSE_NBR = "HY102" COURSE_GRD = "I" COURSE_NAME = "Western Civiliza tion - 1500 to 1945"/> </STUDENT.F_record> <STUDENT.F_record _ID = "221345665"> <CGA-MV SEMESTER = "FA93" COURSE_NBR = "EG110" COURSE_GRD = "C" COURSE_NAME = "Engineering Principles" COURSE_NBR = "MA220" COURSE_GRD = "B" COURSE_NAME = "Ca lculus- I" COURSE_NBR = "PY100" COURSE_GRD = "B" COURSE_NAME = "Introduction to Psychology"/> <CGA-MV SEMESTER = "SP94" COURSE_NBR = "EG140" COURSE_GRD = "B" COURSE_NAME = "Fluid Mechanics" COURSE_NBR = "EG240" COURSE_GRD = "B" COURSE_NAME = "Circut Th eory" COURSE_NBR = "MA221" COURSE_GRD = "B" COURSE_NAME = "Calculus - II"/> </STUDENT.F_record> <STUDENT.F_record _ID = "291222021"> <CGA-MV SEMESTER = "SP94" COURSE_NBR = "FA100" COURSE_GRD = "B" COURSE_NAME = "Visual Thinking"/> </STUDENT.F_record> <STUDENT.F_record _ID = "414446545"> <CGA-MV SEMESTER = "FA93" COURSE_NBR = "CS104" COURSE_GRD = "D" COURSE_NAME = "Database Design" COURSE_NBR = "MA101" COURSE_GRD = "C" COURSE_NAME = "Math Prin cipals" COURSE_NBR = "FA100" COURSE_GRD = "C" COURSE_NAME = "Visual Thinking"/> <CGA-MV SEMESTER = "SP94" COURSE_NBR = "CS105" COURSE_GRD = "B" COURSE_NAME = "Database Design" COURSE_NBR = "MA102" COURSE_GRD = "C" COURSE_NAME = "Algebra" COURSE_NBR = "PY100" COURSE_GRD = "C" COURSE_NAME = "Introduction to Psychology" /> </STUDENT.F_record> </ROOT> >
4-32
Using WITHSCHEMA
Use the WITHSCHEMA keyword with the RetrieVe LIST command and the UniVerse SQL SELECT command. The syntax for the LIST command is: LIST [DICT | USING [DICT] dictname] filename ... [TOXML [ELEMENTS][WITHSCHEMA][WITHDTD] TO filename [XMLMAPPING mapping_file]]... The syntax for the UniVerse SQL SELECT command is: To create an XML document from UniVerse SQL, use the UniVerse SQL
SELECT command. SELECT clause FROM clause [WHERE clause] [WHEN clause [WHEN clause]...] [GROUP BY clause] [HAVING clause] [ORDER BY clause] [report_qualifiers] [processing_qualifiers] [TOXML [ELEMENTS] [WITHDTD][WITHSCHEMA] [XMLMAPPING mapping_file]] [XMLDATA extraction_mapping_file];
WITHSCHEMA creates an XML schema filename.xsd. By default, UniVerse writes this file to the &XML& directory. If you do not specify a targetNamespace in the mapping file, the filename.xmls root element contains the following:
noNamespaceSchemaLocation=filename.xsd
to define the schema location. If you specify the targetNamespace in the mapping file, the following is generated:
schemaLocation=namespaceURL filename.xsd
In both of these cases, you can validate the files using the XML schema validator, or the UniVerse BASIC API XDOMValidate() function.
4-33
The following example illustrates the output from a LIST statement using WITHSCHEMA:
>LIST STUDENT FNAME SEMESTER TEACHER COURSE_NBR TOXML WITHSCHEMA
<?xml version="1.0"?> <xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema"> <xsd:annotation> <xsd:documentation xml:lang="en"> account: C:\IBM\UV command: LIST STUDENT FNAME SEMESTER TEACHER COURSE_NBR TOXML WITHSCHEMA </xsd:documentation> </xsd:annotation> <xsd:element name="ROOT"> <xsd:complexType> <xsd:sequence maxOccurs="unbounded"> <xsd:element ref="STUDENT_record" maxOccurs="unbounded"/> </xsd:sequence> </xsd:complexType> </xsd:element> <xsd:element name="STUDENT_record"> <xsd:complexType> <xsd:sequence maxOccurs="unbounded"> <xsd:element ref="CGA-MV" minOccurs="0" maxOccurs="unbounded"/> </xsd:sequence> <xsd:attribute name="_ID"/> <xsd:attribute name="FNAME"/> </xsd:complexType> </xsd:element> <xsd:element name="CGA-MV"> <xsd:complexType> <xsd:attribute name="SEMESTER"/> <xsd:attribute name="TEACHER"/> <xsd:attribute name="COURSE_NBR"/> </xsd:complexType> </xsd:element> </xsd:schema> <?xml version="1.0"?> <ROOT xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <STUDENT_record _ID = "424325656" FNAME = "Sally"> <CGA-MV SEMESTER = "SP94" TEACHER = "Masters" COURSE_NBR = "PY100" TEACHER = " Fisher" COURSE_NBR = "PE100"/> </STUDENT_record> <STUDENT_record _ID = "521814564" FNAME = "Harry"> <CGA-MV SEMESTER = "FA93" TEACHER = "James" COURSE_NBR = "CS130" TEACHER = "Gi bson" COURSE_NBR = "CS100" TEACHER = "Masters" COURSE_NBR = "PY100"/>
4-34
<CGA-MV SEMESTER = "SP94" TEACHER = "Aaron" COURSE_NBR = "CS131" TEACHER = "Gi bson" COURSE_NBR = "CS101" TEACHER = "Fisher" COURSE_NBR = "PE220"/> </STUDENT_record> . . . </ROOT> >
4-35
Creating an XML Document with UniVerse SQL

In addition to RetrieVe, you can also create XML documents using UniVerse SQL. To create an XML document through UniVerse SQL, complete the following steps:
1.
Analyze the DTD associated with the application to which you are sending the XML file. Determine which of your dictionary attributes correspond to the DTD elements. Create an XML mapping file, if necessary. List the appropriate fields using the UniVerse SQL SELECT command.
2. 3.

UniVerse stores XML mapping files and XSL files in the &XML& directory file. To create this file, enter the following command: CREATE.FILE &XML& 19 To create an XML document from UniVerse SQL, use the UniVerse SQL SELECT command. SELECT clause FROM clause [WHERE clause] [WHEN clause [WHEN clause]...] [GROUP BY clause] [HAVING clause] [ORDER BY clause] [report_qualifiers] [processing_qualifiers] [TOXML [ELEMENTS] [WITHDTD] [XMLMAPPING mapping_file]] [XMLDATA extraction_mapping_file];
4-36

Parameter SELECT clause FROM clause WHERE clause WHEN clause GROUP BY clause HAVING clause ORDER BY clause report_qualifiers processing_qualifiers TOXML ELEMENTS WITHDTD XMLMAPPING mapping_file XMLDATA extraction_mapping_file Description Specifies the columns to select from the database. Specifies the tables containing the selected columns. Specifies the criteria that rows must meet to be selected. Specifies the criteria that values in a multivalued column must meet for an association row to be output. Groups rows to summarize results. Specifies the criteria that grouped rows must meet to be selected. Sorts selected rows. Formats a report generated by the SELECT statement. Modifies or reports on the processing of the SELECT statement. Outputs SELECT results in XML format. Outputs results in element-centric format. Output produces a DTD corresponding to the query. Specifies a mapping file containing transformation rules for display. This file must exist in the &XML& file. Specifies the file containing the extraction rules for the XML document. This file is used for receiving an XML file. SELECT Parameters
You must specify clauses in the SELECT statement in the order shown in the syntax. You can use the SELECT statement with type 1, type 19, and type 25 files only if the current isolation level is 0 or 1. For a full discussion of the UniVerse SQL SELECT statement clauses, see the UniVerse SQL Reference.
4-37
Processing Rules for UniVerse SQL SELECT Statements

UniVerse processes SELECT statements much the same as it processes LIST statements, with a few exceptions. The processing rules for a UniVerse SQL SELECT statement against a single table are the same as the RetrieVe LIST rules. For a discussion of how UniVerse SQL processes these statements, see Creating an XML Document from RetrieVe.
Processing Multiple Tables

When processing a UniVerse SQL SELECT statement involving multiple files, UniVerse attempts to keep the nesting inherited in the query in the resulting XML document. Because of this, the order in which you specify the fields in the UniVerse SQL SELECT statement is important for determining how the elements are nested.
Processing in Attribute-centric Mode

As with RetrieVe, the attribute-centric mode is the default mapping mode. For more information about the attribute-centric mode, see Attribute-centric Mode. In this mode, UniVerse uses the name of the file containing the first field you specify in the SELECT statement as the outer-most element in the XML output. Any singlevalued fields you specify in the SELECT statement that belong to this file become attributes of this element. UniVerse processes the SELECT statement in the order you specify. If it finds a field that belongs to another file, UniVerse creates a sub-element. The name of this sub-element is the new file name. All singlevalued fields found in the SELECT statement that belong to this file are created as attributes for the sub-element. If UniVerse finds a multivalued or multi-subvalued field in the SELECT statement, it creates a sub-element. The name of this element is the name of the association of which this field is a member. When you execute UNNEST against an SQL table, it flattens the multivalues into single values. UniVerse processes the ELEMENTS, WITHDTD, and XMLMAPPING keywords in the same manner as it processes them for the RetrieVe LIST command.
4-38
Processing in Element-centric Mode

When using the element-centric mode, UniVerse automatically prefixes each file name to the association name. For example, the CGA association in the STUDENT file is named STUDENT_CGA in the resulting XML file.
XML Limitations in UniVerse SQL

The TOXML keyword is not allowed in the following cases: In a sub-query In a SELECT statement that is part of an INSERT statement. In a SELECT statement that is part of a UNION definition. In a SELECT statement that is part of a VIEW definition.
Examples
This section illustrates XML output from the UniVerse SQL SELECT statement. The examples use sample CUSTOMER, TAPES, and STUDENT files. The following example lists the dictionary records from the CUSTOMER file that are used in the examples:
DICT CUSTOMER 04:31:35pm 11 Oct 2001 Page 1
Type & Field......... Field. Field........ Conversion.. Column......... Output Depth & Name.......... Number Definition... Code........ Heading........ Format Assoc.. NAME TAPES_RENTED TAPE_INFO D D PH 1 7 TAPES_RENTED DATE_OUT DATE_DUE DAYS_BETWEEN TAPE_COST TAPE_NAME UP_NAMES TAPE_CAT 11 Oct 2001 Page 1 Customer Name Tapes 15T 10L S M TAPE_ INFO
DICT TAPES
04:33:47pm
Type & Field......... Field. Field........ Conversion.. Column......... Output Depth & Name.......... Number Definition... Code........ Heading........ Format Assoc.. @ID NAME CAT_NAME D D I 0 1 TRANS('CATEGO RIES',CATEGOR TAPES Tape Name Tape Type 10L 20T 20L S S S CATS
4-39
IES,'NAME','X ') 1 records listed. >
4-40
Creating an XML Document From Multiple Files in Attributecentric Mode

In the following example, UniVerse creates an XML document from the CUSTOMER.F and TAPES.F file in the attribute-centric mode.
>SELECT CUSTOMER.F.NAME, TAPES.F.NAME, CAT_NAME FROM CUSTOMER.F,TAPES.F WHERETAPES_RENTED = TAPES.F.@ID ORDER BY CUSTOMER.F.NAME TOXML;
<?xml version="1.0"?> <ROOT> <CUSTOMER.F_record NAME = "Barrie, Dick"> <TAPES.F NAME = "Citizen Kane"> <TAPES.F_CATS_MV CAT_NAME = "Old Classic"/> <TAPES.F_CATS_MV CAT_NAME = "Drama"/> <TAPES.F_CATS_MV CAT_NAME = "Horror"/> </TAPES.F> </CUSTOMER.F_record> <CUSTOMER.F_record NAME = "Best, George"> <TAPES.F NAME = "Love Story"> <TAPES.F_CATS_MV CAT_NAME = "Romance"/> <TAPES.F_CATS_MV CAT_NAME = "Tear Jerker"/> </TAPES.F> </CUSTOMER.F_record> <CUSTOMER.F_record NAME = "Bowie, David"> <TAPES.F NAME = "The Stalker"> <TAPES.F_CATS_MV CAT_NAME = "Avant Garde"/> <TAPES.F_CATS_MV CAT_NAME = "Science Fiction"/> </TAPES.F> </CUSTOMER.F_record> <CUSTOMER.F_record NAME = "Chase, Carl"> <TAPES.F NAME = "'Round Midnight"> <TAPES.F_CATS_MV CAT_NAME = "Musical"/> <TAPES.F_CATS_MV CAT_NAME = "Drama"/> </TAPES.F> </CUSTOMER.F_record> <CUSTOMER.F_record NAME = "Chase, Carl"> <TAPES.F NAME = "American Graffiti "> <TAPES.F_CATS_MV CAT_NAME = "Comedy"/> <TAPES.F_CATS_MV CAT_NAME = "Childrens Movie"/> </TAPES.F> </CUSTOMER.F_record> <CUSTOMER.F_record NAME = "Chase, Carl"> <TAPES.F NAME = "Flash Gordon"> <TAPES.F_CATS_MV CAT_NAME = "Science Fiction"/> <TAPES.F_CATS_MV CAT_NAME = "Childrens Movie"/> </TAPES.F> </CUSTOMER.F_record> <CUSTOMER.F_record NAME = "Faber, Harry"> <TAPES.F NAME = "To Kill A Mockingbird"> <TAPES.F_CATS_MV CAT_NAME = "Horror"/>
4-41
<TAPES.F_CATS_MV CAT_NAME = "Political"/> <TAPES.F_CATS_MV CAT_NAME = "Drama"/> </TAPES.F> </CUSTOMER.F_record> <CUSTOMER.F_record NAME = "Fischer, Carrie"> <TAPES.F NAME = "Girl Friday"> <TAPES.F_CATS_MV CAT_NAME = "Comedy"/> <TAPES.F_CATS_MV CAT_NAME = "Old Classic"/> </TAPES.F> </CUSTOMER.F_record> <CUSTOMER.F_record NAME = "James, Bob"> <TAPES.F NAME = "Blue Velvet"> <TAPES.F_CATS_MV CAT_NAME = "Horror"/> <TAPES.F_CATS_MV CAT_NAME = "Drama"/> <TAPES.F_CATS_MV CAT_NAME = "Avant Garde"/> </TAPES.F> </CUSTOMER.F_record> <CUSTOMER.F_record NAME = "Jamieson, Dale"> <TAPES.F NAME = "2001"> <TAPES.F_CATS_MV CAT_NAME = "Science Fiction"/> <TAPES.F_CATS_MV CAT_NAME = "Drama"/> </TAPES.F> </CUSTOMER.F_record> <CUSTOMER.F_record NAME = "Jones, Bob"> <TAPES.F NAME = "Z"> <TAPES.F_CATS_MV CAT_NAME = "Political"/> <TAPES.F_CATS_MV CAT_NAME = "Drama"/> </TAPES.F> </CUSTOMER.F_record> <CUSTOMER.F_record NAME = "Jones, Freddie"> <TAPES.F NAME = "Help"> <TAPES.F_CATS_MV CAT_NAME = "Childrens Movie"/> <TAPES.F_CATS_MV CAT_NAME = "Comedy"/> <TAPES.F_CATS_MV CAT_NAME = "Musical"/> </TAPES.F> </CUSTOMER.F_record> <CUSTOMER.F_record NAME = "Jones, Mable"> <TAPES.F NAME = "Psycho"> <TAPES.F_CATS_MV CAT_NAME = "Horror"/> <TAPES.F_CATS_MV CAT_NAME = "Drama"/> </TAPES.F> </CUSTOMER.F_record> <CUSTOMER.F_record NAME = "Jones, Mable"> <TAPES.F NAME = "Gone With The Wind"> <TAPES.F_CATS_MV CAT_NAME = "Romance"/> </TAPES.F> </CUSTOMER.F_record> <CUSTOMER.F_record NAME = "Jones, Samuel"> <TAPES.F NAME = "'Round Midnight"> <TAPES.F_CATS_MV CAT_NAME = "Musical"/> <TAPES.F_CATS_MV CAT_NAME = "Drama"/> </TAPES.F> </CUSTOMER.F_record> <CUSTOMER.F_record NAME = "Jones, Samuel">
4-42
<TAPES.F NAME = "Flash Gordon"> <TAPES.F_CATS_MV CAT_NAME = "Science Fiction"/> <TAPES.F_CATS_MV CAT_NAME = "Childrens Movie"/> </TAPES.F> </CUSTOMER.F_record> <CUSTOMER.F_record NAME = "Partner, Bonnie"> <TAPES.F NAME = "Tammy"> <TAPES.F_CATS_MV CAT_NAME = "Romance"/> </TAPES.F> </CUSTOMER.F_record> <CUSTOMER.F_record NAME = "Partner, Bonnie"> <TAPES.F NAME = "Love Story"> <TAPES.F_CATS_MV CAT_NAME = "Romance"/> <TAPES.F_CATS_MV CAT_NAME = "Tear Jerker"/> </TAPES.F> </CUSTOMER.F_record> <CUSTOMER.F_record NAME = "Smith, Harry"> <TAPES.F NAME = "Journey Abroad"> <TAPES.F_CATS_MV CAT_NAME = "B - Movie"/> </TAPES.F> </CUSTOMER.F_record> <CUSTOMER.F_record NAME = "Smith, Harry"> <TAPES.F NAME = "Catch 22"> <TAPES.F_CATS_MV CAT_NAME = "Comedy"/> <TAPES.F_CATS_MV CAT_NAME = "Avant Garde"/> </TAPES.F> </CUSTOMER.F_record> <CUSTOMER.F_record NAME = "Smith, Harry"> <TAPES.F NAME = "Blue Velvet"> <TAPES.F_CATS_MV CAT_NAME = "Horror"/> <TAPES.F_CATS_MV CAT_NAME = "Drama"/> <TAPES.F_CATS_MV CAT_NAME = "Avant Garde"/> </TAPES.F> </CUSTOMER.F_record> </ROOT> >
4-43
The next example illustrates the results of a UniVerse SQL statement against the same fields with a different SELECT order and a different sorting option:
01 SELECT TAPES.F.NAME, CUSTOMER.F.NAME, CAT_NAME FROM CUSTOMER.F, TAPES.F WHERE TAPES_RENTED = TAPES.F.@ID ORDER BY TAPES.F.NAME TOXML;
<?xml version="1.0"?> <ROOT> <TAPES.F_record NAME = "'Round Midnight"> <CUSTOMER.F NAME = "Jones, Samuel"/> <TAPES.F_CATS_MV CAT_NAME = "Musical"/> <TAPES.F_CATS_MV CAT_NAME = "Drama"/> </TAPES.F_record> <TAPES.F_record NAME = "'Round Midnight"> <CUSTOMER.F NAME = "Chase, Carl"/> <TAPES.F_CATS_MV CAT_NAME = "Musical"/> <TAPES.F_CATS_MV CAT_NAME = "Drama"/> </TAPES.F_record> <TAPES.F_record NAME = "2001"> <CUSTOMER.F NAME = "Jamieson, Dale"/> <TAPES.F_CATS_MV CAT_NAME = "Science Fiction"/> <TAPES.F_CATS_MV CAT_NAME = "Drama"/> </TAPES.F_record> <TAPES.F_record NAME = "American Graffiti "> <CUSTOMER.F NAME = "Chase, Carl"/> <TAPES.F_CATS_MV CAT_NAME = "Comedy"/> <TAPES.F_CATS_MV CAT_NAME = "Childrens Movie"/> </TAPES.F_record> <TAPES.F_record NAME = "Blue Velvet"> <CUSTOMER.F NAME = "Smith, Harry"/> <TAPES.F_CATS_MV CAT_NAME = "Horror"/> <TAPES.F_CATS_MV CAT_NAME = "Drama"/> <TAPES.F_CATS_MV CAT_NAME = "Avant Garde"/> </TAPES.F_record> <TAPES.F_record NAME = "Blue Velvet"> <CUSTOMER.F NAME = "James, Bob"/> <TAPES.F_CATS_MV CAT_NAME = "Horror"/> <TAPES.F_CATS_MV CAT_NAME = "Drama"/> <TAPES.F_CATS_MV CAT_NAME = "Avant Garde"/> </TAPES.F_record> <TAPES.F_record NAME = "Catch 22"> <CUSTOMER.F NAME = "Smith, Harry"/> <TAPES.F_CATS_MV CAT_NAME = "Comedy"/> <TAPES.F_CATS_MV CAT_NAME = "Avant Garde"/> </TAPES.F_record> <TAPES.F_record NAME = "Citizen Kane"> <CUSTOMER.F NAME = "Barrie, Dick"/> <TAPES.F_CATS_MV CAT_NAME = "Old Classic"/> <TAPES.F_CATS_MV CAT_NAME = "Drama"/> <TAPES.F_CATS_MV CAT_NAME = "Horror"/> </TAPES.F_record> <TAPES.F_record NAME = "Flash Gordon">
4-44
<CUSTOMER.F NAME = "Chase, Carl"/> <TAPES.F_CATS_MV CAT_NAME = "Science Fiction"/> <TAPES.F_CATS_MV CAT_NAME = "Childrens Movie"/> </TAPES.F_record> <TAPES.F_record NAME = "Flash Gordon"> <CUSTOMER.F NAME = "Jones, Samuel"/> <TAPES.F_CATS_MV CAT_NAME = "Science Fiction"/> <TAPES.F_CATS_MV CAT_NAME = "Childrens Movie"/> </TAPES.F_record> <TAPES.F_record NAME = "Girl Friday"> <CUSTOMER.F NAME = "Fischer, Carrie"/> <TAPES.F_CATS_MV CAT_NAME = "Comedy"/> <TAPES.F_CATS_MV CAT_NAME = "Old Classic"/> </TAPES.F_record> <TAPES.F_record NAME = "Gone With The Wind"> <CUSTOMER.F NAME = "Jones, Mable"/> <TAPES.F_CATS_MV CAT_NAME = "Romance"/> </TAPES.F_record> <TAPES.F_record NAME = "Help"> <CUSTOMER.F NAME = "Jones, Freddie"/> <TAPES.F_CATS_MV CAT_NAME = "Childrens Movie"/> <TAPES.F_CATS_MV CAT_NAME = "Comedy"/> <TAPES.F_CATS_MV CAT_NAME = "Musical"/> </TAPES.F_record> <TAPES.F_record NAME = "Journey Abroad"> <CUSTOMER.F NAME = "Smith, Harry"/> <TAPES.F_CATS_MV CAT_NAME = "B - Movie"/> </TAPES.F_record> <TAPES.F_record NAME = "Love Story"> <CUSTOMER.F NAME = "Partner, Bonnie"/> <TAPES.F_CATS_MV CAT_NAME = "Romance"/> <TAPES.F_CATS_MV CAT_NAME = "Tear Jerker"/> </TAPES.F_record> <TAPES.F_record NAME = "Love Story"> <CUSTOMER.F NAME = "Best, George"/> <TAPES.F_CATS_MV CAT_NAME = "Romance"/> <TAPES.F_CATS_MV CAT_NAME = "Tear Jerker"/> </TAPES.F_record> <TAPES.F_record NAME = "Psycho"> <CUSTOMER.F NAME = "Jones, Mable"/> <TAPES.F_CATS_MV CAT_NAME = "Horror"/> <TAPES.F_CATS_MV CAT_NAME = "Drama"/> </TAPES.F_record> <TAPES.F_record NAME = "Tammy"> <CUSTOMER.F NAME = "Partner, Bonnie"/> <TAPES.F_CATS_MV CAT_NAME = "Romance"/> </TAPES.F_record> <TAPES.F_record NAME = "The Stalker"> <CUSTOMER.F NAME = "Bowie, David"/> <TAPES.F_CATS_MV CAT_NAME = "Avant Garde"/> <TAPES.F_CATS_MV CAT_NAME = "Science Fiction"/> </TAPES.F_record> <TAPES.F_record NAME = "To Kill A Mockingbird"> <CUSTOMER.F NAME = "Faber, Harry"/>
4-45
<TAPES.F_CATS_MV CAT_NAME = "Horror"/> <TAPES.F_CATS_MV CAT_NAME = "Political"/> <TAPES.F_CATS_MV CAT_NAME = "Drama"/> </TAPES.F_record> <TAPES.F_record NAME = "Z"> <CUSTOMER.F NAME = "Jones, Bob"/> <TAPES.F_CATS_MV CAT_NAME = "Political"/> <TAPES.F_CATS_MV CAT_NAME = "Drama"/> </TAPES.F_record> </ROOT> >
4-46
Creating an XML Document From Multiple Files in Element-centric Mode

The following example illustrates creating an XML document from multiple files in element-centric mode, using the ELEMENTS keyword.
>SELECT CUSTOMER.NAME, TAPES.NAME, CAT_NAME FROM CUSTOMER, TAPES WHERE TAPES_RENTED = TAPES.@ID ORDER BY CUSTOMER.NAME TOXML ELEMENTS; Validate XML name changed display name from 'Customer Name' to 'Customer_Name' Validate XML name changed display name from 'Tape Name' to 'Tape_Name' Validate XML name changed display name from 'Tape Type' to 'Tape_Type'
<?xml version="1.0"?> <ROOT> <CUSTOMER_record> <Customer_Name>Chase, Carl</Customer_Name> <TAPES> <Tape_Name>American Graffiti</Tape_Name> <TAPES_CATS_MV> <Tape_Type>Comedy</Tape_Type> </TAPES_CATS_MV> <TAPES_CATS_MV> <Tape_Type>Childrens Movie</Tape_Type> </TAPES_CATS_MV> </TAPES> </CUSTOMER_record> <CUSTOMER_record> <Customer_Name>Chase, Carl</Customer_Name> <TAPES> <Tape_Name>Flash Gordon</Tape_Name> <TAPES_CATS_MV> <Tape_Type>Science Fiction</Tape_Type> </TAPES_CATS_MV> <TAPES_CATS_MV> <Tape_Type>Childrens Movie</Tape_Type> </TAPES_CATS_MV> </TAPES> </CUSTOMER_record> <CUSTOMER_record> <Customer_Name>Chase, Carl</Customer_Name> <TAPES> <Tape_Name>'Round Midnight</Tape_Name> <TAPES_CATS_MV> <Tape_Type>Musical</Tape_Type> </TAPES_CATS_MV> <TAPES_CATS_MV> <Tape_Type>Drama</Tape_Type> </TAPES_CATS_MV>
4-47
</TAPES> </CUSTOMER_record> <CUSTOMER_record> <Customer_Name>Jamieson, Dale</Customer_Name> <TAPES> <Tape_Name>2001</Tape_Name> <TAPES_CATS_MV> <Tape_Type>Science Fiction</Tape_Type> </TAPES_CATS_MV> <TAPES_CATS_MV> <Tape_Type>Drama</Tape_Type> </TAPES_CATS_MV> </TAPES> </CUSTOMER_record> <CUSTOMER_record> <Customer_Name>Jones, Bob</Customer_Name> <TAPES> <Tape_Name>Z</Tape_Name> <TAPES_CATS_MV> <Tape_Type>Political</Tape_Type> </TAPES_CATS_MV> <TAPES_CATS_MV> <Tape_Type>Drama</Tape_Type> </TAPES_CATS_MV> </TAPES> </CUSTOMER_record> </ROOT> >
4-48
Creating an XML Document From Multiple Files with a Multivalued Field

The next example illustrates creating an XML document from multiple files with a multivalued field. In the example, TAPES_RENTED is multivalued and belongs to the TAPE_INFO association in the CUSTOMER file. In the XML document, TAPES_RENTED appears in the CUSTOMER_TAPE_INFO_MV element.
>SELECT CUSTOMER.F.NAME, TAPES.F.NAME, CAT_NAME, TAPES_RENTED FROM CUSTOMER.F, TAPES.F WHERE TAPES_RENTED = TAPES.F.@ID ORDER BY CUSTOMER.F.NAME TOXML;
<?xml version="1.0"?> <ROOT> <CUSTOMER.F_record NAME = "Barrie, Dick"> <TAPES.F NAME = "Citizen Kane"> <TAPES.F_CATS_MV CAT_NAME = "Old Classic"/> <TAPES.F_CATS_MV CAT_NAME = "Drama"/> <TAPES.F_CATS_MV CAT_NAME = "Horror"/> </TAPES.F> <CUSTOMER.F_TAPE_INFO_MV TAPES_RENTED = "V996"/> </CUSTOMER.F_record> <CUSTOMER.F_record NAME = "Best, George"> <TAPES.F NAME = "Love Story"> <TAPES.F_CATS_MV CAT_NAME = "Romance"/> <TAPES.F_CATS_MV CAT_NAME = "Tear Jerker"/> </TAPES.F> <CUSTOMER.F_TAPE_INFO_MV TAPES_RENTED = "B2297"/> </CUSTOMER.F_record> <CUSTOMER.F_record NAME = "Bowie, David"> <TAPES.F NAME = "The Stalker"> <TAPES.F_CATS_MV CAT_NAME = "Avant Garde"/> <TAPES.F_CATS_MV CAT_NAME = "Science Fiction"/> </TAPES.F> <CUSTOMER.F_TAPE_INFO_MV TAPES_RENTED = "V9961"/> </CUSTOMER.F_record> <CUSTOMER.F_record NAME = "Chase, Carl"> <TAPES.F NAME = "'Round Midnight"> <TAPES.F_CATS_MV CAT_NAME = "Musical"/> <TAPES.F_CATS_MV CAT_NAME = "Drama"/> </TAPES.F> <CUSTOMER.F_TAPE_INFO_MV TAPES_RENTED = "V8481"/> <CUSTOMER.F_TAPE_INFO_MV TAPES_RENTED = "V1254"/> <CUSTOMER.F_TAPE_INFO_MV TAPES_RENTED = "V4951"/> </CUSTOMER.F_record> <CUSTOMER.F_record NAME = "Chase, Carl"> <TAPES.F NAME = "American Graffiti "> <TAPES.F_CATS_MV CAT_NAME = "Comedy"/> <TAPES.F_CATS_MV CAT_NAME = "Childrens Movie"/> </TAPES.F> <CUSTOMER.F_TAPE_INFO_MV TAPES_RENTED = "V8481"/>
4-49
<CUSTOMER.F_TAPE_INFO_MV TAPES_RENTED = "V1254"/> <CUSTOMER.F_TAPE_INFO_MV TAPES_RENTED = "V4951"/> </CUSTOMER.F_record> <CUSTOMER.F_record NAME = "Chase, Carl"> <TAPES.F NAME = "Flash Gordon"> <TAPES.F_CATS_MV CAT_NAME = "Science Fiction"/> <TAPES.F_CATS_MV CAT_NAME = "Childrens Movie"/> </TAPES.F> <CUSTOMER.F_TAPE_INFO_MV TAPES_RENTED = "V8481"/> <CUSTOMER.F_TAPE_INFO_MV TAPES_RENTED = "V1254"/> <CUSTOMER.F_TAPE_INFO_MV TAPES_RENTED = "V4951"/> </CUSTOMER.F_record> <CUSTOMER.F_record NAME = "Faber, Harry"> <TAPES.F NAME = "To Kill A Mockingbird"> <TAPES.F_CATS_MV CAT_NAME = "Horror"/> <TAPES.F_CATS_MV CAT_NAME = "Political"/> <TAPES.F_CATS_MV CAT_NAME = "Drama"/> </TAPES.F> <CUSTOMER.F_TAPE_INFO_MV TAPES_RENTED = "V5151"/> </CUSTOMER.F_record> <CUSTOMER.F_record NAME = "Fischer, Carrie"> <TAPES.F NAME = "Girl Friday"> <TAPES.F_CATS_MV CAT_NAME = "Comedy"/> <TAPES.F_CATS_MV CAT_NAME = "Old Classic"/> </TAPES.F> <CUSTOMER.F_TAPE_INFO_MV TAPES_RENTED = "V110"/> </CUSTOMER.F_record> <CUSTOMER.F_record NAME = "James, Bob"> <TAPES.F NAME = "Blue Velvet"> <TAPES.F_CATS_MV CAT_NAME = "Horror"/> <TAPES.F_CATS_MV CAT_NAME = "Drama"/> <TAPES.F_CATS_MV CAT_NAME = "Avant Garde"/> </TAPES.F> <CUSTOMER.F_TAPE_INFO_MV TAPES_RENTED = "V2001"/> </CUSTOMER.F_record> <CUSTOMER.F_record NAME = "Jamieson, Dale"> <TAPES.F NAME = "2001"> <TAPES.F_CATS_MV CAT_NAME = "Science Fiction"/> <TAPES.F_CATS_MV CAT_NAME = "Drama"/> </TAPES.F> <CUSTOMER.F_TAPE_INFO_MV TAPES_RENTED = "V6670"/> </CUSTOMER.F_record> <CUSTOMER.F_record NAME = "Jones, Bob"> <TAPES.F NAME = "Z"> <TAPES.F_CATS_MV CAT_NAME = "Political"/> <TAPES.F_CATS_MV CAT_NAME = "Drama"/> </TAPES.F> <CUSTOMER.F_TAPE_INFO_MV TAPES_RENTED = "V4341"/> </CUSTOMER.F_record> <CUSTOMER.F_record NAME = "Jones, Freddie"> <TAPES.F NAME = "Help"> <TAPES.F_CATS_MV CAT_NAME = "Childrens Movie"/> <TAPES.F_CATS_MV CAT_NAME = "Comedy"/> <TAPES.F_CATS_MV CAT_NAME = "Musical"/>
4-50
</TAPES.F> <CUSTOMER.F_TAPE_INFO_MV TAPES_RENTED = "V9431"/> </CUSTOMER.F_record> <CUSTOMER.F_record NAME = "Jones, Mable"> <TAPES.F NAME = "Psycho"> <TAPES.F_CATS_MV CAT_NAME = "Horror"/> <TAPES.F_CATS_MV CAT_NAME = "Drama"/> </TAPES.F> <CUSTOMER.F_TAPE_INFO_MV TAPES_RENTED = "V1249"/> <CUSTOMER.F_TAPE_INFO_MV TAPES_RENTED = "V4499"/> </CUSTOMER.F_record> <CUSTOMER.F_record NAME = "Jones, Mable"> <TAPES.F NAME = "Gone With The Wind"> <TAPES.F_CATS_MV CAT_NAME = "Romance"/> </TAPES.F> <CUSTOMER.F_TAPE_INFO_MV TAPES_RENTED = "V1249"/> <CUSTOMER.F_TAPE_INFO_MV TAPES_RENTED = "V4499"/> </CUSTOMER.F_record> <CUSTOMER.F_record NAME = "Jones, Samuel"> <TAPES.F NAME = "'Round Midnight"> <TAPES.F_CATS_MV CAT_NAME = "Musical"/> <TAPES.F_CATS_MV CAT_NAME = "Drama"/> </TAPES.F> <CUSTOMER.F_TAPE_INFO_MV TAPES_RENTED = "V1254"/> <CUSTOMER.F_TAPE_INFO_MV TAPES_RENTED = "V8481"/> </CUSTOMER.F_record> <CUSTOMER.F_record NAME = "Jones, Samuel"> <TAPES.F NAME = "Flash Gordon"> <TAPES.F_CATS_MV CAT_NAME = "Science Fiction"/> <TAPES.F_CATS_MV CAT_NAME = "Childrens Movie"/> </TAPES.F> <CUSTOMER.F_TAPE_INFO_MV TAPES_RENTED = "V1254"/> <CUSTOMER.F_TAPE_INFO_MV TAPES_RENTED = "V8481"/> </CUSTOMER.F_record> <CUSTOMER.F_record NAME = "Partner, Bonnie"> <TAPES.F NAME = "Tammy"> <TAPES.F_CATS_MV CAT_NAME = "Romance"/> </TAPES.F> <CUSTOMER.F_TAPE_INFO_MV TAPES_RENTED = "B914"/> <CUSTOMER.F_TAPE_INFO_MV TAPES_RENTED = "B2297"/> </CUSTOMER.F_record> <CUSTOMER.F_record NAME = "Partner, Bonnie"> <TAPES.F NAME = "Love Story"> <TAPES.F_CATS_MV CAT_NAME = "Romance"/> <TAPES.F_CATS_MV CAT_NAME = "Tear Jerker"/> </TAPES.F> <CUSTOMER.F_TAPE_INFO_MV TAPES_RENTED = "B914"/> <CUSTOMER.F_TAPE_INFO_MV TAPES_RENTED = "B2297"/> </CUSTOMER.F_record> <CUSTOMER.F_record NAME = "Smith, Harry"> <TAPES.F NAME = "Journey Abroad"> <TAPES.F_CATS_MV CAT_NAME = "B - Movie"/> </TAPES.F> <CUSTOMER.F_TAPE_INFO_MV TAPES_RENTED = "V2001"/>
4-51
<CUSTOMER.F_TAPE_INFO_MV TAPES_RENTED = "V5004"/> <CUSTOMER.F_TAPE_INFO_MV TAPES_RENTED = "V8181"/> </CUSTOMER.F_record> <CUSTOMER.F_record NAME = "Smith, Harry"> <TAPES.F NAME = "Catch 22"> <TAPES.F_CATS_MV CAT_NAME = "Comedy"/> <TAPES.F_CATS_MV CAT_NAME = "Avant Garde"/> </TAPES.F> <CUSTOMER.F_TAPE_INFO_MV TAPES_RENTED = "V2001"/> <CUSTOMER.F_TAPE_INFO_MV TAPES_RENTED = "V5004"/> <CUSTOMER.F_TAPE_INFO_MV TAPES_RENTED = "V8181"/> </CUSTOMER.F_record> <CUSTOMER.F_record NAME = "Smith, Harry"> <TAPES.F NAME = "Blue Velvet"> <TAPES.F_CATS_MV CAT_NAME = "Horror"/> <TAPES.F_CATS_MV CAT_NAME = "Drama"/> <TAPES.F_CATS_MV CAT_NAME = "Avant Garde"/> </TAPES.F> <CUSTOMER.F_TAPE_INFO_MV TAPES_RENTED = "V2001"/> <CUSTOMER.F_TAPE_INFO_MV TAPES_RENTED = "V5004"/> <CUSTOMER.F_TAPE_INFO_MV TAPES_RENTED = "V8181"/> </CUSTOMER.F_record> </ROOT> >
4-52
Creating an XML Document From Multiple Files with a DTD

The following example illustrates creating an XML document from multiple files with a DTD. To include the DTD, use the WITHDTD keyword.
>SELECT CUSTOMER.F.NAME, TAPES.F.NAME, CAT_NAME, TAPES_RENTED FROM CUSTOMER.F, TAPES.F WHERE TAPES_RENTED = TAPES.F.@ID ORDER BY CUSTOMER.F.NAME TOXML WITHDTD;
<?xml version="1.0"?> <!DOCTYPE ROOT[ <!ELEMENT ROOT (CUSTOMER.F_record*)> <!ELEMENT CUSTOMER.F_record ( TAPES.F* , CUSTOMER.F_TAPE_INFO_MV* )> <!ATTLIST CUSTOMER.F_record NAME CDATA #REQUIRED > <!ELEMENT TAPES.F ( TAPES.F_CATS_MV* )> <!ATTLIST TAPES.F NAME CDATA #IMPLIED > <!ELEMENT TAPES.F_CATS_MV EMPTY> <!ATTLIST TAPES.F_CATS_MV CAT_NAME CDATA #IMPLIED > <!ELEMENT CUSTOMER.F_TAPE_INFO_MV EMPTY> <!ATTLIST CUSTOMER.F_TAPE_INFO_MV TAPES_RENTED CDATA #IMPLIED > ]> <ROOT> <CUSTOMER.F_record NAME = "Barrie, Dick"> <TAPES.F NAME = "Citizen Kane"> <TAPES.F_CATS_MV CAT_NAME = "Old Classic"/> <TAPES.F_CATS_MV CAT_NAME = "Drama"/> <TAPES.F_CATS_MV CAT_NAME = "Horror"/> </TAPES.F> <CUSTOMER.F_TAPE_INFO_MV TAPES_RENTED = "V996"/> </CUSTOMER.F_record> <CUSTOMER.F_record NAME = "Best, George"> <TAPES.F NAME = "Love Story"> <TAPES.F_CATS_MV CAT_NAME = "Romance"/> <TAPES.F_CATS_MV CAT_NAME = "Tear Jerker"/> </TAPES.F> <CUSTOMER.F_TAPE_INFO_MV TAPES_RENTED = "B2297"/> </CUSTOMER.F_record> <CUSTOMER.F_record NAME = "Bowie, David"> <TAPES.F NAME = "The Stalker"> <TAPES.F_CATS_MV CAT_NAME = "Avant Garde"/> <TAPES.F_CATS_MV CAT_NAME = "Science Fiction"/> </TAPES.F> <CUSTOMER.F_TAPE_INFO_MV TAPES_RENTED = "V9961"/>
4-53
</CUSTOMER.F_record> <CUSTOMER.F_record NAME = "Chase, Carl"> <TAPES.F NAME = "'Round Midnight"> <TAPES.F_CATS_MV CAT_NAME = "Musical"/> <TAPES.F_CATS_MV CAT_NAME = "Drama"/> </TAPES.F> <CUSTOMER.F_TAPE_INFO_MV TAPES_RENTED = "V8481"/> <CUSTOMER.F_TAPE_INFO_MV TAPES_RENTED = "V1254"/> <CUSTOMER.F_TAPE_INFO_MV TAPES_RENTED = "V4951"/> </CUSTOMER.F_record> <CUSTOMER.F_record NAME = "Chase, Carl"> <TAPES.F NAME = "American Graffiti "> <TAPES.F_CATS_MV CAT_NAME = "Comedy"/> <TAPES.F_CATS_MV CAT_NAME = "Childrens Movie"/> </TAPES.F> <CUSTOMER.F_TAPE_INFO_MV TAPES_RENTED = "V8481"/> <CUSTOMER.F_TAPE_INFO_MV TAPES_RENTED = "V1254"/> <CUSTOMER.F_TAPE_INFO_MV TAPES_RENTED = "V4951"/> </CUSTOMER.F_record> <CUSTOMER.F_record NAME = "Chase, Carl"> <TAPES.F NAME = "Flash Gordon"> <TAPES.F_CATS_MV CAT_NAME = "Science Fiction"/> <TAPES.F_CATS_MV CAT_NAME = "Childrens Movie"/> </TAPES.F> <CUSTOMER.F_TAPE_INFO_MV TAPES_RENTED = "V8481"/> <CUSTOMER.F_TAPE_INFO_MV TAPES_RENTED = "V1254"/> <CUSTOMER.F_TAPE_INFO_MV TAPES_RENTED = "V4951"/> </CUSTOMER.F_record> <CUSTOMER.F_record NAME = "Faber, Harry"> <TAPES.F NAME = "To Kill A Mockingbird"> <TAPES.F_CATS_MV CAT_NAME = "Horror"/> <TAPES.F_CATS_MV CAT_NAME = "Political"/> <TAPES.F_CATS_MV CAT_NAME = "Drama"/> </TAPES.F> <CUSTOMER.F_TAPE_INFO_MV TAPES_RENTED = "V5151"/> </CUSTOMER.F_record> <CUSTOMER.F_record NAME = "Fischer, Carrie"> <TAPES.F NAME = "Girl Friday"> <TAPES.F_CATS_MV CAT_NAME = "Comedy"/> <TAPES.F_CATS_MV CAT_NAME = "Old Classic"/> </TAPES.F> <CUSTOMER.F_TAPE_INFO_MV TAPES_RENTED = "V110"/> </CUSTOMER.F_record> <CUSTOMER.F_record NAME = "James, Bob"> <TAPES.F NAME = "Blue Velvet"> <TAPES.F_CATS_MV CAT_NAME = "Horror"/> <TAPES.F_CATS_MV CAT_NAME = "Drama"/> <TAPES.F_CATS_MV CAT_NAME = "Avant Garde"/> </TAPES.F> <CUSTOMER.F_TAPE_INFO_MV TAPES_RENTED = "V2001"/> </CUSTOMER.F_record> <CUSTOMER.F_record NAME = "Jamieson, Dale"> <TAPES.F NAME = "2001"> <TAPES.F_CATS_MV CAT_NAME = "Science Fiction"/>
4-54
<TAPES.F_CATS_MV CAT_NAME = "Drama"/> </TAPES.F> <CUSTOMER.F_TAPE_INFO_MV TAPES_RENTED = "V6670"/> </CUSTOMER.F_record> <CUSTOMER.F_record NAME = "Jones, Bob"> <TAPES.F NAME = "Z"> <TAPES.F_CATS_MV CAT_NAME = "Political"/> <TAPES.F_CATS_MV CAT_NAME = "Drama"/> </TAPES.F> <CUSTOMER.F_TAPE_INFO_MV TAPES_RENTED = "V4341"/> </CUSTOMER.F_record> <CUSTOMER.F_record NAME = "Jones, Freddie"> <TAPES.F NAME = "Help"> <TAPES.F_CATS_MV CAT_NAME = "Childrens Movie"/> <TAPES.F_CATS_MV CAT_NAME = "Comedy"/> <TAPES.F_CATS_MV CAT_NAME = "Musical"/> </TAPES.F> <CUSTOMER.F_TAPE_INFO_MV TAPES_RENTED = "V9431"/> </CUSTOMER.F_record> <CUSTOMER.F_record NAME = "Jones, Mable"> <TAPES.F NAME = "Psycho"> <TAPES.F_CATS_MV CAT_NAME = "Horror"/> <TAPES.F_CATS_MV CAT_NAME = "Drama"/> </TAPES.F> <CUSTOMER.F_TAPE_INFO_MV TAPES_RENTED = "V1249"/> <CUSTOMER.F_TAPE_INFO_MV TAPES_RENTED = "V4499"/> </CUSTOMER.F_record> <CUSTOMER.F_record NAME = "Jones, Mable"> <TAPES.F NAME = "Gone With The Wind"> <TAPES.F_CATS_MV CAT_NAME = "Romance"/> </TAPES.F> <CUSTOMER.F_TAPE_INFO_MV TAPES_RENTED = "V1249"/> <CUSTOMER.F_TAPE_INFO_MV TAPES_RENTED = "V4499"/> </CUSTOMER.F_record> <CUSTOMER.F_record NAME = "Jones, Samuel"> <TAPES.F NAME = "'Round Midnight"> <TAPES.F_CATS_MV CAT_NAME = "Musical"/> <TAPES.F_CATS_MV CAT_NAME = "Drama"/> </TAPES.F> <CUSTOMER.F_TAPE_INFO_MV TAPES_RENTED = "V1254"/> <CUSTOMER.F_TAPE_INFO_MV TAPES_RENTED = "V8481"/> </CUSTOMER.F_record> <CUSTOMER.F_record NAME = "Jones, Samuel"> <TAPES.F NAME = "Flash Gordon"> <TAPES.F_CATS_MV CAT_NAME = "Science Fiction"/> <TAPES.F_CATS_MV CAT_NAME = "Childrens Movie"/> </TAPES.F> <CUSTOMER.F_TAPE_INFO_MV TAPES_RENTED = "V1254"/> <CUSTOMER.F_TAPE_INFO_MV TAPES_RENTED = "V8481"/> </CUSTOMER.F_record> <CUSTOMER.F_record NAME = "Partner, Bonnie"> <TAPES.F NAME = "Tammy"> <TAPES.F_CATS_MV CAT_NAME = "Romance"/> </TAPES.F>
4-55
<CUSTOMER.F_TAPE_INFO_MV TAPES_RENTED = "B914"/> <CUSTOMER.F_TAPE_INFO_MV TAPES_RENTED = "B2297"/> </CUSTOMER.F_record> <CUSTOMER.F_record NAME = "Partner, Bonnie"> <TAPES.F NAME = "Love Story"> <TAPES.F_CATS_MV CAT_NAME = "Romance"/> <TAPES.F_CATS_MV CAT_NAME = "Tear Jerker"/> </TAPES.F> <CUSTOMER.F_TAPE_INFO_MV TAPES_RENTED = "B914"/> <CUSTOMER.F_TAPE_INFO_MV TAPES_RENTED = "B2297"/> </CUSTOMER.F_record> <CUSTOMER.F_record NAME = "Smith, Harry"> <TAPES.F NAME = "Journey Abroad"> <TAPES.F_CATS_MV CAT_NAME = "B - Movie"/> </TAPES.F> <CUSTOMER.F_TAPE_INFO_MV TAPES_RENTED = "V2001"/> <CUSTOMER.F_TAPE_INFO_MV TAPES_RENTED = "V5004"/> <CUSTOMER.F_TAPE_INFO_MV TAPES_RENTED = "V8181"/> </CUSTOMER.F_record> <CUSTOMER.F_record NAME = "Smith, Harry"> <TAPES.F NAME = "Catch 22"> <TAPES.F_CATS_MV CAT_NAME = "Comedy"/> <TAPES.F_CATS_MV CAT_NAME = "Avant Garde"/> </TAPES.F> <CUSTOMER.F_TAPE_INFO_MV TAPES_RENTED = "V2001"/> <CUSTOMER.F_TAPE_INFO_MV TAPES_RENTED = "V5004"/> <CUSTOMER.F_TAPE_INFO_MV TAPES_RENTED = "V8181"/> </CUSTOMER.F_record> <CUSTOMER.F_record NAME = "Smith, Harry"> <TAPES.F NAME = "Blue Velvet"> <TAPES.F_CATS_MV CAT_NAME = "Horror"/> <TAPES.F_CATS_MV CAT_NAME = "Drama"/> <TAPES.F_CATS_MV CAT_NAME = "Avant Garde"/> </TAPES.F> <CUSTOMER.F_TAPE_INFO_MV TAPES_RENTED = "V2001"/> <CUSTOMER.F_TAPE_INFO_MV TAPES_RENTED = "V5004"/> <CUSTOMER.F_TAPE_INFO_MV TAPES_RENTED = "V8181"/> </CUSTOMER.F_record> </ROOT> >
Creating an XML Document From Multiple Files Using a Mapping File

As with RetrieVe, you can create a mapping file to define transformation rules differing from the defaults. For information about creating the mapping file, see The Mapping File.
4-56
The following mapping file defines rules for the CUSTOMER and TAPES file.
<?XML version= 1.0 ?> <U2xml-mapping xmlns:U2xml=http://www.informix.com/U2-xml> <! -- CUSTOMER AND TAPE MAPPING FILE --> <U2xml:mapping file = TAPES.F field = CAT_NAME map-to= Cat_name TYPE= MV /> <U2xml:mapping file = CUSTOMER.F field = TAPES_RENTED map-to=Tapes_rented TYPE=MV /> <U2xml:mapping file = CUSTOMER.F field = DATE_OUT TYPE=MV /> <U2xml:mapping file = CUSTOMER.F field = DATE_DUE TYPE=MV /> </U2xml-mapping>
To use this mapping file in the SELECT statement, specify the XMLMAPPING keyword, as shown in the following example:
4-57
Note: You must surround the name of the mapping file in single quotation marks.
02 SELECT CUSTOMER.F.NAME, TAPES.F.NAME, CAT_NAME, DATE_OUT, DATE_DUE FROM CUSTOMER.F, TAPES.F WHERE TAPES_RENTED = TAPES.F.@ID ORDER BY CUSTOMER.F.NAME TOXML XMLMAPPING 'CUST.TAPE.MAP';
<?xml version="1.0"?> <ROOT> <CUSTOMER.F_record NAME = "Barrie, Dick"> <TAPES.F NAME = "Citizen Kane"> <TAPES.F_CATS_MV CAT_NAME = "Old Classic"/> <TAPES.F_CATS_MV CAT_NAME = "Drama"/> <TAPES.F_CATS_MV CAT_NAME = "Horror"/> </TAPES.F> <TAPES.F_CATS-MV DATE_OUT = "03/29/94" DATE_DUE </CUSTOMER.F_record> <CUSTOMER.F_record NAME = "Best, George"> <TAPES.F NAME = "Love Story"> <TAPES.F_CATS_MV CAT_NAME = "Romance"/> <TAPES.F_CATS_MV CAT_NAME = "Tear Jerker"/> </TAPES.F> <TAPES.F_CATS-MV DATE_OUT = "03/29/94" DATE_DUE </CUSTOMER.F_record> <CUSTOMER.F_record NAME = "Bowie, David"> <TAPES.F NAME = "The Stalker"> <TAPES.F_CATS_MV CAT_NAME = "Avant Garde"/> <TAPES.F_CATS_MV CAT_NAME = "Science Fiction"/> </TAPES.F> <TAPES.F_CATS-MV DATE_OUT = "04/15/94" DATE_DUE </CUSTOMER.F_record> <CUSTOMER.F_record NAME = "Chase, Carl"> <TAPES.F NAME = "'Round Midnight"> <TAPES.F_CATS_MV CAT_NAME = "Musical"/> <TAPES.F_CATS_MV CAT_NAME = "Drama"/> </TAPES.F> <TAPES.F_CATS-MV DATE_OUT = "04/20/94" DATE_DUE <TAPES.F_CATS-MV DATE_OUT = "04/20/94" DATE_DUE <TAPES.F_CATS-MV DATE_OUT = "04/21/94" DATE_DUE </CUSTOMER.F_record> <CUSTOMER.F_record NAME = "Chase, Carl"> <TAPES.F NAME = "American Graffiti "> <TAPES.F_CATS_MV CAT_NAME = "Comedy"/> <TAPES.F_CATS_MV CAT_NAME = "Childrens Movie"/> </TAPES.F> <TAPES.F_CATS-MV DATE_OUT = "04/20/94" DATE_DUE <TAPES.F_CATS-MV DATE_OUT = "04/20/94" DATE_DUE <TAPES.F_CATS-MV DATE_OUT = "04/21/94" DATE_DUE </CUSTOMER.F_record> <CUSTOMER.F_record NAME = "Chase, Carl"> <TAPES.F NAME = "Flash Gordon"> <TAPES.F_CATS_MV CAT_NAME = "Science Fiction"/> <TAPES.F_CATS_MV CAT_NAME = "Childrens Movie"/> </TAPES.F>
= "03/31/94"/>
= "03/31/94"/>
= "04/17/94"/>
= "04/22/94"/> = "04/22/94"/> = "04/23/94"/>
= "04/22/94"/> = "04/22/94"/> = "04/23/94"/>
4-58
<TAPES.F_CATS-MV DATE_OUT = "04/20/94" DATE_DUE <TAPES.F_CATS-MV DATE_OUT = "04/20/94" DATE_DUE <TAPES.F_CATS-MV DATE_OUT = "04/21/94" DATE_DUE </CUSTOMER.F_record> <CUSTOMER.F_record NAME = "Faber, Harry"> <TAPES.F NAME = "To Kill A Mockingbird"> <TAPES.F_CATS_MV CAT_NAME = "Horror"/> <TAPES.F_CATS_MV CAT_NAME = "Political"/> <TAPES.F_CATS_MV CAT_NAME = "Drama"/> </TAPES.F> <TAPES.F_CATS-MV DATE_OUT = "04/19/94" DATE_DUE </CUSTOMER.F_record> <CUSTOMER.F_record NAME = "Fischer, Carrie"> <TAPES.F NAME = "Girl Friday"> <TAPES.F_CATS_MV CAT_NAME = "Comedy"/> <TAPES.F_CATS_MV CAT_NAME = "Old Classic"/> </TAPES.F> <TAPES.F_CATS-MV DATE_OUT = "04/23/94" DATE_DUE </CUSTOMER.F_record> <CUSTOMER.F_record NAME = "James, Bob"> <TAPES.F NAME = "Blue Velvet"> <TAPES.F_CATS_MV CAT_NAME = "Horror"/> <TAPES.F_CATS_MV CAT_NAME = "Drama"/> <TAPES.F_CATS_MV CAT_NAME = "Avant Garde"/> </TAPES.F> <TAPES.F_CATS-MV DATE_OUT = "04/25/94" DATE_DUE </CUSTOMER.F_record> <CUSTOMER.F_record NAME = "Jamieson, Dale"> <TAPES.F NAME = "2001"> <TAPES.F_CATS_MV CAT_NAME = "Science Fiction"/> <TAPES.F_CATS_MV CAT_NAME = "Drama"/> </TAPES.F> <TAPES.F_CATS-MV DATE_OUT = "04/24/94" DATE_DUE </CUSTOMER.F_record> <CUSTOMER.F_record NAME = "Jones, Bob"> <TAPES.F NAME = "Z"> <TAPES.F_CATS_MV CAT_NAME = "Political"/> <TAPES.F_CATS_MV CAT_NAME = "Drama"/> </TAPES.F> <TAPES.F_CATS-MV DATE_OUT = "04/24/94" DATE_DUE </CUSTOMER.F_record> <CUSTOMER.F_record NAME = "Jones, Freddie"> <TAPES.F NAME = "Help"> <TAPES.F_CATS_MV CAT_NAME = "Childrens Movie"/> <TAPES.F_CATS_MV CAT_NAME = "Comedy"/> <TAPES.F_CATS_MV CAT_NAME = "Musical"/> </TAPES.F> <TAPES.F_CATS-MV DATE_OUT = "04/23/94" DATE_DUE </CUSTOMER.F_record> <CUSTOMER.F_record NAME = "Jones, Mable"> <TAPES.F NAME = "Psycho"> <TAPES.F_CATS_MV CAT_NAME = "Horror"/> <TAPES.F_CATS_MV CAT_NAME = "Drama"/> </TAPES.F>
= "04/22/94"/> = "04/22/94"/> = "04/23/94"/>
= "04/21/94"/>
= "04/25/94"/>
= "04/27/94"/>
= "04/26/94"/>
= "04/26/94"/>
= "04/25/94"/>
4-59
<TAPES.F_CATS-MV DATE_OUT = "04/23/94" DATE_DUE <TAPES.F_CATS-MV DATE_OUT = "04/25/94" DATE_DUE </CUSTOMER.F_record> <CUSTOMER.F_record NAME = "Jones, Mable"> <TAPES.F NAME = "Gone With The Wind"> <TAPES.F_CATS_MV CAT_NAME = "Romance"/> </TAPES.F> <TAPES.F_CATS-MV DATE_OUT = "04/23/94" DATE_DUE <TAPES.F_CATS-MV DATE_OUT = "04/25/94" DATE_DUE </CUSTOMER.F_record> <CUSTOMER.F_record NAME = "Jones, Samuel"> <TAPES.F NAME = "'Round Midnight"> <TAPES.F_CATS_MV CAT_NAME = "Musical"/> <TAPES.F_CATS_MV CAT_NAME = "Drama"/> </TAPES.F> <TAPES.F_CATS-MV DATE_OUT = "04/24/94" DATE_DUE <TAPES.F_CATS-MV DATE_OUT = "04/25/94" DATE_DUE </CUSTOMER.F_record> <CUSTOMER.F_record NAME = "Jones, Samuel"> <TAPES.F NAME = "Flash Gordon"> <TAPES.F_CATS_MV CAT_NAME = "Science Fiction"/> <TAPES.F_CATS_MV CAT_NAME = "Childrens Movie"/> </TAPES.F> <TAPES.F_CATS-MV DATE_OUT = "04/24/94" DATE_DUE <TAPES.F_CATS-MV DATE_OUT = "04/25/94" DATE_DUE </CUSTOMER.F_record> <CUSTOMER.F_record NAME = "Partner, Bonnie"> <TAPES.F NAME = "Tammy"> <TAPES.F_CATS_MV CAT_NAME = "Romance"/> </TAPES.F> <TAPES.F_CATS-MV DATE_OUT = "01/01/94" DATE_DUE <TAPES.F_CATS-MV DATE_OUT = "01/03/94" DATE_DUE </CUSTOMER.F_record> <CUSTOMER.F_record NAME = "Partner, Bonnie"> <TAPES.F NAME = "Love Story"> <TAPES.F_CATS_MV CAT_NAME = "Romance"/> <TAPES.F_CATS_MV CAT_NAME = "Tear Jerker"/> </TAPES.F> <TAPES.F_CATS-MV DATE_OUT = "01/01/94" DATE_DUE <TAPES.F_CATS-MV DATE_OUT = "01/03/94" DATE_DUE </CUSTOMER.F_record> <CUSTOMER.F_record NAME = "Smith, Harry"> <TAPES.F NAME = "Journey Abroad"> <TAPES.F_CATS_MV CAT_NAME = "B - Movie"/> </TAPES.F> <TAPES.F_CATS-MV DATE_OUT = "04/24/94" DATE_DUE <TAPES.F_CATS-MV DATE_OUT = "04/23/94" DATE_DUE <TAPES.F_CATS-MV DATE_OUT = "04/24/94" DATE_DUE </CUSTOMER.F_record> <CUSTOMER.F_record NAME = "Smith, Harry"> <TAPES.F NAME = "Catch 22"> <TAPES.F_CATS_MV CAT_NAME = "Comedy"/> <TAPES.F_CATS_MV CAT_NAME = "Avant Garde"/> </TAPES.F>
= "04/25/94"/> = "04/27/94"/>
= "04/25/94"/> = "04/27/94"/>
= "04/26/94"/> = "04/27/94"/>
= "04/26/94"/> = "04/27/94"/>
= "01/03/94"/> = "01/05/94"/>
= "01/03/94"/> = "01/05/94"/>
= "04/26/94"/> = "04/25/94"/> = "04/26/94"/>
4-60
<TAPES.F_CATS-MV DATE_OUT = "04/24/94" DATE_DUE <TAPES.F_CATS-MV DATE_OUT = "04/23/94" DATE_DUE <TAPES.F_CATS-MV DATE_OUT = "04/24/94" DATE_DUE </CUSTOMER.F_record> <CUSTOMER.F_record NAME = "Smith, Harry"> <TAPES.F NAME = "Blue Velvet"> <TAPES.F_CATS_MV CAT_NAME = "Horror"/> <TAPES.F_CATS_MV CAT_NAME = "Drama"/> <TAPES.F_CATS_MV CAT_NAME = "Avant Garde"/> </TAPES.F> <TAPES.F_CATS-MV DATE_OUT = "04/24/94" DATE_DUE <TAPES.F_CATS-MV DATE_OUT = "04/23/94" DATE_DUE <TAPES.F_CATS-MV DATE_OUT = "04/24/94" DATE_DUE </CUSTOMER.F_record> </ROOT> >
= "04/26/94"/> = "04/25/94"/> = "04/26/94"/>
= "04/26/94"/> = "04/25/94"/> = "04/26/94"/>
4-61
UniVerse BASIC Example

The following example illustrates an UniVerse BASIC program that generates an XML document:
CMD = "LIST STUDENT LNAME SEMESTER COURSE_NBR '424325656' TOXML XMLMAPPING student.map" STATUS = XMLEXECUTE(CMD,myvar) PRINT "XMLEXECUTE finished" PRINT myvar END
The next example illustrates the output from the program described in the previous example:
>RUN ENGTESTS XMLEXECUTE XMLEXECUTE finished <STUDENT_record> <_ID>424325656</_ID> <LNAME>Martin</LNAME> <SEMESTER>SP94</SEMESTER> <COURSE_NBR>PY100</COURSE_NBR> <COURSE_NBR>PE100</COURSE_NBR> </STUDENT_record>
The following example illustrates the root element of the student.map file:
<U2 root="STUDENT" schema = "type" hidemv="yes" hidems="yes" hideroot="1" />
4-62
Chapter
Receiving XML Documents
5
7-2 7-2 7-4 7-13 7-18 7-22
Receiving an XML Document through UniVerse BASIC . Defining Extraction Rules . . . . . . . . . Defining the XPath. . . . . . . . . . . . Extracting XML Data through UniVerse BASIC . . Displaying an XML Document through RetrieVe . . Displaying an XML Document through UniVerse SQL
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
XML for IBM UniVerse

The Extensible Markup Language (XML) is a markup language used to define, validate, and share document formats. It enables you to tailor document formats to specifications unique to your application by defining your own elements, tags, and attributes. Note: XML describes how a document is structured, not how a document is displayed. XML was developed by the World Wide Web Consortium (W3C), who describe XML as: The Extensible Markup Language (XML) is the universal format for structured documents and data on the Web. An XML document consists of a set of tags that describe the structure of data. Unlike HTML, you can write your own tags. You can use XML to describe any type of data so that it is cross-platform and machine independent. For detailed information about XML, see the W3C website at http://www.w3.org/TR/REC-xml.
Document Type Definitions

You must define the rules of the structure of your XML document. These rules may be part of the XML document, and are called the Document Type Definition, or DTD. The DTD provides a list of elements, tags, attributes, and entities contained in the document, and describes their relationship to each other. A DTD can be external or internal. External DTD An external DTD is a separate document from the XML document, residing outside of your XML document. External DTDs can be applied to many different XML documents. If you need to change the DTD, you can make the change once, and all referencing XML documents are updated automatically. Internal DTD An internal DTD resides in the XML document as part of the header of the document, and applies only to that XML document. You can combine external DTDs with internal DTDs in an XML document.
5-2
The Document Object Model (DOM)

The Document Object Model (DOM) is a platform- and language-independent interface that enables programs and scripts to dynamically access and update the content, structure, and style of documents. A DOM is a formal way to describe an XML document to another application or programming language. You can describe the XML document as a tree, with nodes representing elements, attributes, entities, an text.
Well-Formed and Valid XML Documents

An XML document is either well-formed or valid: Well-formed XML documents must follow XML rules. All XML documents must be well-formed. Valid XML documents are both well-formed, and follow the rules of a specific DTD. Not all XML documents must be valid. For optimum exchange of data, you should try to ensure that your XML documents are valid.
Creating an XML Document from RetrieVe

You can create an XML document from UniVerse files through RetrieVe. To create an XML document through RetrieVe, complete the following steps:
1.
Analyze the DTD associated with the application to which you are sending the XML file. Determine which of your dictionary attributes correspond to the DTD elements. Create an XML mapping file, if necessary. List the appropriate fields using the LIST command.
2. 3.

UniVerse stores XML mapping files in the &XML& directory file. To create this file, enter the following command: CREATE.FILE &XML& 19
Mapping Modes
UniVerse supports three modes for mapping data to XML files. These modes are: Attribute-centric Element-centric Mixed
Attribute-centric Mode
In the attribute-centric mode, which is the default mode, each record displayed in the query statement becomes an XML element. The following rules apply to the record fields: Each singlevalued field becomes an attribute within the element. Each multivalued or multi-subvalued field becomes a sub-element of the record element. The name of the sub-element is association_name-MV.
5-4
Within a sub-element, each multivalued field becomes an attribute of the sub-element. Associated multi-subvalued fields become another nested sub-element of the sub-element. The name of this nested sub-element is association_name-MS. If there are no associated multi-subvalued fields, the sub-element name is field_name-MV/MS. This is the default mapping scheme. You can change the default by defining maps in the &XML& file.
Element-centric Mode
In the element-centric mode, as in the attribute-centric mode, each record becomes an XML element. The following rules apply: Each singlevalued field becomes a simple sub-element of the element, containing no nested sub-elements. The value of the field becomes the value of the sub-element. Each association whose multivalued and multi-subvalued fields are included in the query statement form a complex sub-element. In the subelement, each multivalued field belonging to the association becomes a subelement that may contain multi-subvalued sub-elements. By default, UniVerse converts text marks to an empty string. Specify that you want to use element-centric mapping by using the ELEMENTS keyword in the RetrieVe statement.
Mixed Mode
In the mixed-mode, you create your own map file, where you specify which fields are treated as attribute-centric and which fields are treated as element-centric. Field-level mapping overrides the mode you specify in the RetrieVe.
The Mapping File

If you want to use mixed-mode, you must create a mapping record in the &XML& file. This mapping record contains those fields that you want to treat as elementcentric. If a field is not defined in the mapping record, UniVerse treats it as attributecentric. Warning: The attribute type definition for a multivalued or multi-subvalued field in a UniVerse dictionary record is M. If you know that a field is multi-subvalued, you must define it as such in a mapping file, or the XML document you create may not be accurate. A mapping file has the following format: <?XML version=1.0?> <U2xml-mapping xmlns:U2xml=http://www.informix.com/U2-xml>  <U2xml :mapping file=file_name field=dictionary_display_name map-to=name_in_xml_doc namespace=namespace_name type=MV | MS hastm=yes | 1 treated-as=attribute | element root=root_element_name record=record_element_name association-mv=mv_level_assoc_name association-ms=ms_level_assoc_name format = format -pattern.. conversion = conversion code encode=encoding characters /> ...</U2xml-mapping> Note: UniVerse supports multiple cases of the U2XML_extraction tag. Valid cases are: U2XML_extraction U2xml_extraction u2xml_extraction
5-6
The XML mapping file is, in itself, and XML file. There are three types of significant elements, the root element, the field element, and the association element. The root Element The root element describes the global options that control different output formats, such as the schema type, targetNamespace, hideroot, hidemv, and hidems. You can also use the root element to change the default root element name, or the record element name. You should have only one root element in the mapping file. The field Element UniVerse uses the field element to change the characteristics of a particular fields XML output attributes, such as the display name, the format, or the conversion. The association Element UniVerse uses the association element to change the display name of an association. By default, this name is the association phrase name, together with -MV or -MS.
Distinguishing Elements
You can distinguish the root element from the field and association elements because the root element does not define a field or association element. Both the field element and the association element must have the file and field attribute to define the file name and the field name in the file that has been processed. Generally, the field name is a data-descriptor or I-descriptor, making it a field element. If the field name is an association phrase, it is an association element.
Root Element Attributes

The default root element name in an XML document is ROOT. You can change the name of the root element, as shown in the following example:
root=root-element-name
Record Name Attribute

The default record name is FILENAME_record. The record attribute in the root element changes the record name. The following example illustrates the record attribute:
record=record-element-name
The Hideroot Attribute

The Hideroot attribute allows you to specify to only create a segment of an XML document, for example, using the SAMPLE keyword and other conditional clauses. If Hideroot is set to 1, UniVerse only creates the record portion of the XML document, it does not create a DTD or XMLSchema. The default value is 0.
Hideroot=1/0
The Hidemv and Hidems Attributes

Normally, when UniVerse processes multivalued or multi-subvalued fields, UniVerse adds another level of elements to produce multiple levels of nesting. You have the option of disabling this additional level by adding the Hidemv and Hidems attributes to the mapping file. When these options are on, the generated XML document and the associated DTD or XMLSchema will have fewer levels of nesting.
Hidemv=0/1/yes/no Hidems=0/1/yes/no
Note: If the document is created in attribute mode, it is not possible to eliminate the extra level of element tags. You can also use these attributes with XMLEXECUTE().
Namespace Attributes
UniVerse provides the following attributes for defining namespaces: namespace=name-space-name xmlns:name-space-name=URL targetnamespace=URL UniVerse displays the targetnamespace attribute in the XMLSchema as targetNamespace, and uses the URL you define in the XML document to define schemaLocation. If you define the targetnamespace and other explicit namespace definitions, UniVerse checks if the explictly defined namespace has the same URL as the targetnamespace. If it does, UniVerse uses the namespace name to qualify the schema element, and the XML document element name.
5-8
If there is no other namespace explictly defined, UniVerse creates a defaultnamespace in the schema file as shown in the following example:
xmlns=targetnamespace URL
In this case, UniVerse does not qualify the schema element or the XML document element. UniVerse uses the namespace attributes and xmlns:name-space-name together to define the namespace. All namespaces defined in the root element are for global element namespace qualifiers only. Note: Namespace is used primarily for XMLSchema. If you do not specify XMLSchema in the command line, UniVerse will not use a global namespace to qualify any element the instance document.
Schema Attribute
The default schema format is ref type schema. You can use the Schema attribute to define a different schema format.
schema=inline|ref|type
Elementformdefault and Attributeformdefault Attributes

UniVerse uses the elementformdefault and attributeformdefault attributes in the XMLSchema. If you use them together with the namespace attribute in the root element, you can indicate all of the local elements and local attributes need to be qualified with the namespace. UniVerse processes all attributes in the field element and association element in the same way as UniVerse 10.0.
File Attribute
UniVerse uses the file attribute to process both RetrieVe and SQL commands. If you do not define the file attribute exactly as it is used on the command line, this field element will not be properly processed.
File=filename
Field Attribute
The field attribute defines the field name. The field can be either a data-descriptor or an I-descriptor.
Field=field-name
Map-to Attribute
The Map-to attribute allows you to define a new attribute tag or element tag name for the field. By default, UniVerse used the dictionary field name for the element or attribute name tag.
Type Attribute
The Type attribute defines how to treat the field in the XML document, either as a multivalued field or a multi-subvalued field.
type=MV|MS
Treated-as Attribute
The Treated-as attribute determines if the field should be treated as an element or attribute in the generated XML document.
Encode Attribute
The Encode attribute encodes unprintable characters with a macro.
encode=0x7B 0x7D
Conv Attribute
The Conv attribute changes the conversion defined in the dictionary record to the conversion you define.
conv=new conv code | conversion = new conversion code
5-10
Fmt Attribute
The Fmt attribute changes the format defined in the dictionary record to the format you define.
fmt=new format code | format = new format code
Association Elements
An association element contains the following four attribute: file = file name field = association phrase name association-mv = new multivalue element tag association-ms = new multi-subvalue element tag
Mapping File Example

The following example illustrates a mapping file:
<U2 root="MAIN" schema="type" targetnamespace="www.ibm.com" /> <U2 file="STUDENT.F" field = "CGA" association-mv="Term" association-ms="Courses_Taken" /> <U2 file="STUDENT.F" field = "COURSE_NBR" type="MS" treated-as="element" /> <U2 file="STUDENT.F" field = "SEMESTER" map-to="SEMESTER" type="MV" treated-as="element" /> <U2 file="STUDENT.F" field = "COURSE_GRD" map-to="COURSE_GRD" type="ms" treated-as="element" /> <U2 file="STUDENT.F" field = "COURSE_NAME" type="ms" treated-as="element" />
5-12
The next example illustrates an XMLSchema using the mapping file in the previous example:
<?xml version="1.0"?> <xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema" targetNamespace="www.ibm.com" > <xsd:annotation> <xsd:documentation xml:lang="en"> Acct:D:\uvxml Cmd:LIST STUDENT.F LNAME SEMESTER COURSE_NBR TOXML XMLMAPPING student.map WITHSCHEMA TO xxxx </xsd:documentation> </xsd:annotation> <xsd:element name="MAIN"> <xsd:complexType> <xsd:sequence maxOccurs="unbounded"> <xsd:element name="STUDENT.F_record" type="ibm:STUDENT.F_recordType" maxOccurs="unbounded"/> </xsd:sequence> </xsd:complexType> </xsd:element> <xsd:complexType name="STUDENT.F_recordType"> <xsd:sequence maxOccurs="unbounded"> <xsd:element name="SEMESTER" type="xsd:string" minOccurs="0" maxOccurs="unbounded"/> <xsd:element name="Courses_Taken" type="ibm:Courses_TakenType" minOccurs="0" maxOccurs="unbounded"/> </xsd:sequence> <xsd:attribute name="_ID"/> <xsd:attribute name="LNAME"/> </xsd:complexType> <xsd:complexType name="Courses_TakenType"> <xsd:sequence maxOccurs="unbounded"> <xsd:element name="COURSE_NBR" type="xsd:string" minOccurs="0" maxOccurs="unbounded"/> </xsd:sequence> </xsd:complexType> </xsd:schema>
5-13
The next example illustrates an XML document created using the mapping file in the previous example.
<?xml version="1.0"?> <ibm:MAIN xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation= "www.ibm.com xxxx.xsd" xmlns:ibm="www.ibm.com" > <STUDENT.F_record _ID = "978766676" LNAME = "Muller"> <Term> <SEMESTER>FA93</SEMESTER> <Courses_Taken> <COURSE_NBR>FA120</COURSE_NBR> <COURSE_NBR>FA230</COURSE_NBR> <COURSE_NBR>HY101</COURSE_NBR> </Courses_Taken> <SEMESTER>SP94</SEMESTER> <Courses_Taken> <COURSE_NBR>FA121</COURSE_NBR> <COURSE_NBR>FA231</COURSE_NBR> <COURSE_NBR>HY102</COURSE_NBR> </Courses_Taken> </Term> </STUDENT.F_record> .. </ibm:MAIN>
The next example illustrates the same mapping file, with the following root element added:
<U2 root="MAIN" targetnamespace="www.ibm.com" hidemv ="1" hidems="1" />
5-14
The next example illustrates an XMLSchema file generated from the mapping file with the root element described in the previous example:
<?xml version="1.0"?> <xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema" targetNamespace="www.ibm.com" xmlns="www.ibm.com"> <xsd:annotation> <xsd:documentation xml:lang="en"> account: D:\uvxml command: LIST STUDENT.F LNAME SEMESTER COURSE_NBR TOXML WITHSCHEMA XMLMAPPIN G student.f.map </xsd:documentation> </xsd:annotation> <xsd:element name="MAIN"> <xsd:complexType> <xsd:sequence maxOccurs="unbounded"> <xsd:element ref="STUDENT.F_record" maxOccurs="unbounded"/> </xsd:sequence> </xsd:complexType> </xsd:element> <xsd:element name="STUDENT.F_record"> <xsd:complexType> <xsd:sequence maxOccurs="unbounded"> <xsd:sequence maxOccurs='unbounded'> <xsd:element ref="SEMESTER" minOccurs="0" maxOccurs="unbounded"/> <xsd:sequence maxOccurs='unbounded'> <xsd:element ref="COURSE_NBR" minOccurs="0" maxOccurs="unbounded"/> </xsd:sequence> </xsd:sequence> </xsd:sequence> <xsd:attribute name="_ID"/> <xsd:attribute name="LNAME"/> </xsd:complexType> </xsd:element> <xsd:element name="SEMESTER" type="xsd:string"/> <xsd:element name="COURSE_NBR" type="xsd:string"/> </xsd:schema>
5-15
The next example illustrates an XML file generated from the mapping file with the root element described in the previous example:
<?xml version="1.0"?> <xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema" targetNamespace="www.ibm.com" xmlns="www.ibm.com" > <xsd:annotation> <xsd:documentation xml:lang="en"> Acct:D:\uvxml Cmd:LIST STUDENT.F LNAME SEMESTER COURSE_NBR TOXML XMLMAPPING student.map WITHSCHEMA TO xxxx </xsd:documentation> </xsd:annotation> <xsd:element name="MAIN"> <xsd:complexType> <xsd:sequence maxOccurs="unbounded"> <xsd:element ref="STUDENT.F_record" maxOccurs="unbounded"/> </xsd:sequence> </xsd:complexType> </xsd:element> <xsd:element name="STUDENT.F_record"> <xsd:complexType> <xsd:sequence maxOccurs="unbounded"> <xsd:element ref="SEMESTER" minOccurs="0" maxOccurs="unbounded"/> <xsd:element ref="COURSE_NBR" minOccurs="0" maxOccurs="unbounded"/> </xsd:sequence> <xsd:attribute name="_ID"/> <xsd:attribute name="LNAME"/> </xsd:complexType> </xsd:element> <xsd:element name="SEMESTER" type="xsd:string"/> <xsd:element name="COURSE_NBR" type="xsd:string"/> </xsd:schema> <?xml version="1.0"?> <MAIN xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <STUDENT.F_record _ID = "424325656" LNAME = "Martin"> <SEMESTER>SP94</SEMESTER> <COURSE_NBR>PY100</COURSE_NBR> <COURSE_NBR>PE100</COURSE_NBR> </STUDENT.F_record> <STUDENT.F_record _ID = "521814564" LNAME = "Smith"> <SEMESTER>FA93</SEMESTER> <COURSE_NBR>CS130</COURSE_NBR> <COURSE_NBR>CS100</COURSE_NBR> <COURSE_NBR>PY100</COURSE_NBR> <SEMESTER>SP94</SEMESTER> <COURSE_NBR>CS131</COURSE_NBR> <COURSE_NBR>CS101</COURSE_NBR>
5-16
<COURSE_NBR>PE220</COURSE_NBR> </STUDENT.F_record> </MAIN>
Conversion Code Considerations

UniVerse XML follows the following rules when extracting data from database files: If the dictionary record of a field you are extracting contains a conversion code, UniVerse XML uses that conversion code when extracting data from database files. If you specify a conversion code in the mapping file, the conversion code in the mapping file overrides the conversion code specified in the dictionary record. If you specify a conversion code using the CONV keyword during the execution of a RetrieVe statement, that conversion code overrides both the conversion code specified in the mapping file, and the conversion code specified in the dictionary record.
Formatting Considerations
UniVerse XML does not generally apply the dictionary format pattern to the extracted data. To specify a format, define it in the mapping file. If you specify a format using the FMT keyword in a RetrieVe statement, that format will override the format defined in the mapping file.
Mapping File Encoding

For special character encountered in data, UniVerse XML uses the default XML entities to encode the data. For example, < becomes <, > becomes >, & becomes &, and becomes ". However, UniVerse XML does not convert to ', unless you specify it in attribute encode. (<, >, &, ', and " are all built-in entities for the XML parser).
5-17
Use the encode field in the mapping file to add flexibility to the output. You can define special characters to encode in hexadecimal form. UniVerse encodes these special characters to &#x##;. For example, if you want the character { to be encoded for field FIELD1, specify the following encode value in the mapping file for FIELD1: encode=0x7B In this case, UniVerse XML will convert { found in the data of FIELD1 to &#x7B. You can also use this type of encoding for any nonprintable character. If you need to define more than one character for a field, add a space between the hexadecimal definitions. For example, if you want to encode both { and }, the encode value in the mapping file should look like the following example: encode=0x7B 0x7D
The following example illustrates a mapping file for the STUDENT file.
<?XML version=1.0?> <U2xml-mapping xmlns:U2xml=http://www.ibm.com/U2-xml> <! -- this is a comment --> <U2xml:mapping record=STUDENT_rec root = SCHOOL xmlns:IBM=http://www.IBM.com namespace=IBM /> <U2XML:mapping file=STUDENT field = SEMESTER type=MV treated-as=element /> <U2XML:mapping file=STUDENT field = COURSE_NBR type=MS treated-as=element /> <U2XML:mapping file=STUDENT field = COURSE_GRD type=MS treated-as=element /> <U2XML:mapping file=STUDENT field = COURSE_NAME type=MS treated-as=element /> </U2xml-mapping>
5-18
Notice that the SEMESTER, COURSE_NBR, COURSE_GRD, and COURSE_NAME fields are to be treated as elements. When you create the XML document, these fields will produce element-centric XML data. Any other fields listed in the query statement will produce attribute-centric XML data, since attributecentric is the default mode. Additionally, COURSE_NBR, COURSE_GRD, and COURSE_NAME are defined as multi-subvalued fields. If they were not, UniVerse would create the XML data as if they were multivalued attributes.
How Data is Mapped

Regardless of the mapping mode you choose, the outer-most element in the XML document is created as <ROOT>, by default. The name of each record element defaults to <file_name>. You can change these mapping defaults in the mapping file, as shown in the following example:
<U2xml:mapping root=root_name record=record_name/>
5-19
Mapping Example
The following examples illustrate creation of XML documents. These examples use the STUDENT file, which contains the following fields:
>LIST DICT STUDENT DICT STUDENT 12:50:05pm 10 Oct 2001 Page 1
Type & Field......... Field. Field........ Conversion.. Column......... Output Depth & Name.......... Number Definition... Code........ Heading........ Format Assoc.. @ID ID D D 0 0 STUDENT STUDENT 10L 12R### -##-## ## 15T 10L 4L 4L 8L 4L 5L 3L 10L S S
LNAME FNAME MAJOR MINOR ADVISOR SEMESTER CGA COURSE_NBR CGA COURSE_GRD CGA TEACHER CGA
D D D D D D D D I
1 2 3 4 5 6 7 8 TRANS('COURSE S',COURSE_NBR ,'TEACHER','X ') TRANS('COURSE
Last Name First Name Major Minor Advisor Term Crs # GD Teacher
S S S S S M M M M
COURSE_NAME I CGA Press any key to continue... DICT STUDENT 12:50:07pm
Course Name
25L
10 Oct 2001
Page
Type & Field......... Field. Field........ Conversion.. Column......... Output Depth & Name.......... Number Definition... Code........ Heading........ Format Assoc.. S',COURSE_NBR ,'NAME','X') SUBR('GPA1',C MD3 OURSE_HOURS,C OURSE_GRD) TRANS('COURSE S',COURSE_NBR ,CREDITS,'X') SEMESTER COURSE_NBR COURSE_NAME
GPA1
GPA
5R
COURSE_HOURS CGA
Hours
5R
CGA
PH
5-20
COURSE_GRD COURSE_HOURS TEACHER @ORIGINAL @SYNONYM S S @ID ID M M
Press any key to continue... DICT STUDENT 12:50:08pm 10 Oct 2001 Page 3
Type & Field......... Field. Field........ Conversion.. Column......... Output Depth & Name.......... Number Definition... Code........ Heading........ Format Assoc.. 17 records listed. >
Creating an XML Document

To create an XML document using RetrieVe, use the LIST command. LIST [DICT | USING [DICT] dictname] filename ... [TOXML [ELEMENTS] [WITHDTD] [XMLMAPPING mapping_file]]... The following table describes each parameter of the syntax.
Parameter DICT USING [ DICT ] dictname filename Description Lists records in the file dictionary of filename. If you do not specify DICT, records in the data file are listed. If DICT is not specified, uses dictname as the dictionary of filename. If DICT is specified, the dictionary of dictname is used as the dictionary of filename. The file whose records you want to list. You can specify filename anywhere in the sentence. LIST uses the first word in the sentence that has a file descriptor in the VOC file as the filename. Outputs LIST results in XML format. LIST Parameters
TOXML
5-21
Parameter ELEMENTS WITHDTD XMLMAPPING mapping_file
Description Outputs results in element-centric format. I Output produces a DTD corresponding to the query. Specifies a mapping file containing transformation rules for display. This file must exist in the &XML& file. LIST Parameters (Continued)
For detailed information about the LIST command, see the RetrieVe Users Guide.
Examples
Note: The examples in this section use the STUDENT.F and COURSES files. To create these files, execute the MAKE.DEMO.FILES from the TCL prompt.
Creating an Attribute-centric XML Document

This example lists fields from the STUDENT file, using the TOXML keyword, to create an XML document. By default, UniVerse uses the attribute-centric mapping mode.
5-22
Note: UniVerse does not store the XML document unless you execute the COMO ON statement prior to executing the RetrieVe statement. If you execute COMO ON, the XML document is stored in the &COMO& file. You can also direct the output to the &HOLD& file using SETPTR, or the printer using LPTR.
>LIST STUDENT.F SEMESTER COURSE_NBR COURSE_GRD COURSE_NAME TOXML Validate XML name changed display name from '@ID' to '_ID'
<?xml version="1.0"?> <ROOT> <STUDENT.F_record _ID = "424325656"> <CGA-MV SEMESTER = "SP94" COURSE_NBR = "PY100" COURSE_GRD = "C" COURSE_NAME = "Introduction to Psychology" COURSE_NBR = "PE100" COURSE_GRD = "C" COURSE_NAME = "Golf - I"/> </STUDENT.F_record> <STUDENT.F_record _ID = "521814564"> <CGA-MV SEMESTER = "FA93" COURSE_NBR = "CS130" COURSE_GRD = "A" COURSE_NAME = "Intro to Operating Systems" COURSE_NBR = "CS100" COURSE_GRD = "B" COURSE_NAME = "Intro to Computer Science" COURSE_NBR = "PY100" COURSE_GRD = "B" COURSE_NAME = "Introduction to Psychology"/> <CGA-MV SEMESTER = "SP94" COURSE_NBR = "CS131" COURSE_GRD = "B" COURSE_NAME = "Intro to Operating Systems" COURSE_NBR = "CS101" COURSE_GRD = "B" COURSE_NAME = "Intro to Computer Science" COURSE_NBR = "PE220" COURSE_GRD = "A" COURSE_NAME = "Racquetball"/> </STUDENT.F_record> <STUDENT.F_record _ID = "978766676"> <CGA-MV SEMESTER = "FA93" COURSE_NBR = "FA120" COURSE_GRD = "A" COURSE_NAME = "Finger Painting" COURSE_NBR = "FA230" COURSE_GRD = "C" COURSE_NAME = "Photograp hy Principals" COURSE_NBR = "HY101" COURSE_GRD = "C" COURSE_NAME = "Western Civi lization"/> <CGA-MV SEMESTER = "SP94" COURSE_NBR = "FA121" COURSE_GRD = "A" COURSE_NAME = "Watercorlors" COURSE_NBR = "FA231" COURSE_GRD = "B" COURSE_NAME = "Photography Practicum" COURSE_NBR = "HY102" COURSE_GRD = "I" COURSE_NAME = "Western Civiliza tion - 1500 to 1945"/> </STUDENT.F_record> <STUDENT.F_record _ID = "221345665"> <CGA-MV SEMESTER = "FA93" COURSE_NBR = "EG110" COURSE_GRD = "C"
5-23
COURSE_NAME = "Engineering Principles" COURSE_NBR = "MA220" COURSE_GRD = "B" COURSE_NAME = "Ca lculus- I" COURSE_NBR = "PY100" COURSE_GRD = "B" COURSE_NAME = "Introduction to Psychology"/> <CGA-MV SEMESTER = "SP94" COURSE_NBR = "EG140" COURSE_GRD = "B" COURSE_NAME = "Fluid Mechanics" COURSE_NBR = "EG240" COURSE_GRD = "B" COURSE_NAME = "Circut Th eory" COURSE_NBR = "MA221" COURSE_GRD = "B" COURSE_NAME = "Calculus - II"/> </STUDENT.F_record> <STUDENT.F_record _ID = "291222021"> <CGA-MV SEMESTER = "SP94" COURSE_NBR = "FA100" COURSE_GRD = "B" COURSE_NAME = "Visual Thinking"/> </STUDENT.F_record> <STUDENT.F_record _ID = "414446545"> <CGA-MV SEMESTER = "FA93" COURSE_NBR = "CS104" COURSE_GRD = "D" COURSE_NAME = "Database Design" COURSE_NBR = "MA101" COURSE_GRD = "C" COURSE_NAME = "Math Prin cipals" COURSE_NBR = "FA100" COURSE_GRD = "C" COURSE_NAME = "Visual Thinking"/> <CGA-MV SEMESTER = "SP94" COURSE_NBR = "CS105" COURSE_GRD = "B" COURSE_NAME = "Database Design" COURSE_NBR = "MA102" COURSE_GRD = "C" COURSE_NAME = "Algebra" COURSE_NBR = "PY100" COURSE_GRD = "C" COURSE_NAME = "Introduction to Psychology" /> </STUDENT.F_record> </ROOT> >
5-24
Creating an Element-centric XML Document

To create an element-centric XML document, use the ELEMENTS keyword.
>LIST STUDENT.F SEMESTER COURSE_NBR COURSE_GRD COURSE_NAME TOXML ELEMENTS Validate XML name changed display name from '@ID' to '_ID'
<?xml version="1.0"?> <ROOT> <STUDENT.F_record _ID = "424325656"> <CGA-MV SEMESTER = "SP94" COURSE_NBR = "PY100" COURSE_GRD = "C" COURSE_NAME = "Introduction to Psychology" COURSE_NBR = "PE100" COURSE_GRD = "C" COURSE_NAME = "Golf - I"/> </STUDENT.F_record> <STUDENT.F_record _ID = "521814564"> <CGA-MV SEMESTER = "FA93" COURSE_NBR = "CS130" COURSE_GRD = "A" COURSE_NAME = "Intro to Operating Systems" COURSE_NBR = "CS100" COURSE_GRD = "B" COURSE_NAME = "Intro to Computer Science" COURSE_NBR = "PY100" COURSE_GRD = "B" COURSE_NAME = "Introduction to Psychology"/> <CGA-MV SEMESTER = "SP94" COURSE_NBR = "CS131" COURSE_GRD = "B" COURSE_NAME = "Intro to Operating Systems" COURSE_NBR = "CS101" COURSE_GRD = "B" COURSE_NAME = "Intro to Computer Science" COURSE_NBR = "PE220" COURSE_GRD = "A" COURSE_NAME = "Racquetball"/> </STUDENT.F_record> <STUDENT.F_record _ID = "978766676"> <CGA-MV SEMESTER = "FA93" COURSE_NBR = "FA120" COURSE_GRD = "A" COURSE_NAME = "Finger Painting" COURSE_NBR = "FA230" COURSE_GRD = "C" COURSE_NAME = "Photograp hy Principals" COURSE_NBR = "HY101" COURSE_GRD = "C" COURSE_NAME = "Western Civi lization"/> <CGA-MV SEMESTER = "SP94" COURSE_NBR = "FA121" COURSE_GRD = "A" COURSE_NAME = "Watercorlors" COURSE_NBR = "FA231" COURSE_GRD = "B" COURSE_NAME = "Photography Practicum" COURSE_NBR = "HY102" COURSE_GRD = "I" COURSE_NAME = "Western Civiliza tion - 1500 to 1945"/> </STUDENT.F_record> <STUDENT.F_record _ID = "221345665"> <CGA-MV SEMESTER = "FA93" COURSE_NBR = "EG110" COURSE_GRD = "C" COURSE_NAME =
5-25
"Engineering Principles" COURSE_NBR = "MA220" COURSE_GRD = "B" COURSE_NAME = "Ca lculus- I" COURSE_NBR = "PY100" COURSE_GRD = "B" COURSE_NAME = "Introduction to Psychology"/> <CGA-MV SEMESTER = "SP94" COURSE_NBR = "EG140" COURSE_GRD = "B" COURSE_NAME = "Fluid Mechanics" COURSE_NBR = "EG240" COURSE_GRD = "B" COURSE_NAME = "Circut Th eory" COURSE_NBR = "MA221" COURSE_GRD = "B" COURSE_NAME = "Calculus - II"/> </STUDENT.F_record> <STUDENT.F_record _ID = "291222021"> <CGA-MV SEMESTER = "SP94" COURSE_NBR = "FA100" COURSE_GRD = "B" COURSE_NAME = "Visual Thinking"/> </STUDENT.F_record> <STUDENT.F_record _ID = "414446545"> <CGA-MV SEMESTER = "FA93" COURSE_NBR = "CS104" COURSE_GRD = "D" COURSE_NAME = "Database Design" COURSE_NBR = "MA101" COURSE_GRD = "C" COURSE_NAME = "Math Prin cipals" COURSE_NBR = "FA100" COURSE_GRD = "C" COURSE_NAME = "Visual Thinking"/> <CGA-MV SEMESTER = "SP94" COURSE_NBR = "CS105" COURSE_GRD = "B" COURSE_NAME = "Database Design" COURSE_NBR = "MA102" COURSE_GRD = "C" COURSE_NAME = "Algebra" COURSE_NBR = "PY100" COURSE_GRD = "C" COURSE_NAME = "Introduction to Psychology" /> </STUDENT.F_record> </ROOT> >
5-26
Creating a Mixed-mode XML Document

Using the mapping file described in The Mapping File, the following example creates a mixed-mode XML document. To use a mapping file, specify the XMLMAPPING keyword in the RetrieVe statement.
>LIST STUDENT.F LNAME FNAME SEMESTER COURSE_NBR COURSE_GRD COURSE_NAME TOXML XMLMAPPING STUDENT_MAP Validate XML name changed display name from '@ID' to '_ID'
<?xml version="1.0"?> <SCHOOL xmlns:IBM="HTTP://WWW.IBM.COM" > <IBM:STUDENT_REC _ID = "424325656" LNAME = "Martin" FNAME = "Sally"> <CGA-MV> <SEMESTER>SP94</SEMESTER> <CGA-MS> <COURSE_NBR>PY100</COURSE_NBR> <COURSE_GRD>C</COURSE_GRD> <COURSE_NAME>Introduction to Psychology</COURSE_NAME> </CGA-MS> <CGA-MS> <COURSE_NBR>PE100</COURSE_NBR> <COURSE_GRD>C</COURSE_GRD> <COURSE_NAME>Golf - I</COURSE_NAME> </CGA-MS> </CGA-MV> </IBM:STUDENT_REC> <IBM:STUDENT_REC _ID = "521814564" LNAME = "Smith" FNAME = "Harry"> <CGA-MV> <SEMESTER>FA93</SEMESTER> <CGA-MS> <COURSE_NBR>CS130</COURSE_NBR> <COURSE_GRD>A</COURSE_GRD> <COURSE_NAME>Intro to Operating Systems</COURSE_NAME> </CGA-MS> <CGA-MS> <COURSE_NBR>CS100</COURSE_NBR> <COURSE_GRD>B</COURSE_GRD> <COURSE_NAME>Intro to Computer Science</COURSE_NAME> </CGA-MS> <CGA-MS> <COURSE_NBR>PY100</COURSE_NBR> <COURSE_GRD>B</COURSE_GRD> <COURSE_NAME>Introduction to Psychology</COURSE_NAME> </CGA-MS> </CGA-MV> <CGA-MV>
5-27
<SEMESTER>SP94</SEMESTER> <CGA-MS> <COURSE_NBR>CS131</COURSE_NBR> <COURSE_GRD>B</COURSE_GRD> <COURSE_NAME>Intro to Operating Systems</COURSE_NAME> </CGA-MS> <CGA-MS> <COURSE_NBR>CS101</COURSE_NBR> <COURSE_GRD>B</COURSE_GRD> <COURSE_NAME>Intro to Computer Science</COURSE_NAME> </CGA-MS> <CGA-MS> <COURSE_NBR>PE220</COURSE_NBR> <COURSE_GRD>A</COURSE_GRD> <COURSE_NAME>Racquetball</COURSE_NAME> </CGA-MS> </CGA-MV> </IBM:STUDENT_REC> <IBM:STUDENT_REC _ID = "978766676" LNAME = "Muller" FNAME = "Gerhardt"> <CGA-MV> <SEMESTER>FA93</SEMESTER> <CGA-MS> <COURSE_NBR>FA120</COURSE_NBR> <COURSE_GRD>A</COURSE_GRD> <COURSE_NAME>Finger Painting</COURSE_NAME> </CGA-MS> <CGA-MS> <COURSE_NBR>FA230</COURSE_NBR> <COURSE_GRD>C</COURSE_GRD> <COURSE_NAME>Photography Principals</COURSE_NAME> </CGA-MS> <CGA-MS> <COURSE_NBR>HY101</COURSE_NBR> <COURSE_GRD>C</COURSE_GRD> <COURSE_NAME>Western Civilization</COURSE_NAME> </CGA-MS> </CGA-MV> <CGA-MV> <SEMESTER>SP94</SEMESTER> <CGA-MS> <COURSE_NBR>FA121</COURSE_NBR> <COURSE_GRD>A</COURSE_GRD> <COURSE_NAME>Watercorlors</COURSE_NAME> </CGA-MS> <CGA-MS> <COURSE_NBR>FA231</COURSE_NBR> <COURSE_GRD>B</COURSE_GRD> <COURSE_NAME>Photography Practicum</COURSE_NAME> </CGA-MS> <CGA-MS> <COURSE_NBR>HY102</COURSE_NBR> <COURSE_GRD>I</COURSE_GRD> <COURSE_NAME>Western Civilization - 1500 to
5-28
1945</COURSE_NAME> </CGA-MS> </CGA-MV> </IBM:STUDENT_REC> <IBM:STUDENT_REC _ID = "221345665" LNAME = "Miller" FNAME = "Susan"> <CGA-MV> <SEMESTER>FA93</SEMESTER> <CGA-MS> <COURSE_NBR>EG110</COURSE_NBR> <COURSE_GRD>C</COURSE_GRD> <COURSE_NAME>Engineering Principles</COURSE_NAME> </CGA-MS> <CGA-MS> <COURSE_NBR>MA220</COURSE_NBR> <COURSE_GRD>B</COURSE_GRD> <COURSE_NAME>Calculus- I</COURSE_NAME> </CGA-MS> <CGA-MS> <COURSE_NBR>PY100</COURSE_NBR> <COURSE_GRD>B</COURSE_GRD> <COURSE_NAME>Introduction to Psychology</COURSE_NAME> </CGA-MS> </CGA-MV> <CGA-MV> <SEMESTER>SP94</SEMESTER> <CGA-MS> <COURSE_NBR>EG140</COURSE_NBR> <COURSE_GRD>B</COURSE_GRD> <COURSE_NAME>Fluid Mechanics</COURSE_NAME> </CGA-MS> <CGA-MS> <COURSE_NBR>EG240</COURSE_NBR> <COURSE_GRD>B</COURSE_GRD> <COURSE_NAME>Circut Theory</COURSE_NAME> </CGA-MS> <CGA-MS> <COURSE_NBR>MA221</COURSE_NBR> <COURSE_GRD>B</COURSE_GRD> <COURSE_NAME>Calculus - II</COURSE_NAME> </CGA-MS> </CGA-MV> </IBM:STUDENT_REC> <IBM:STUDENT_REC _ID = "291222021" LNAME = "Smith" FNAME = "jojo"> <CGA-MV> <SEMESTER>SP94</SEMESTER> <CGA-MS> <COURSE_NBR>FA100</COURSE_NBR> <COURSE_GRD>B</COURSE_GRD> <COURSE_NAME>Visual Thinking</COURSE_NAME> </CGA-MS> </CGA-MV> </IBM:STUDENT_REC> <IBM:STUDENT_REC _ID = "414446545" LNAME = "Offenbach" FNAME =
5-29
"Karl"> <CGA-MV> <SEMESTER>FA93</SEMESTER> <CGA-MS> <COURSE_NBR>CS104</COURSE_NBR> <COURSE_GRD>D</COURSE_GRD> <COURSE_NAME>Database Design</COURSE_NAME> </CGA-MS> <CGA-MS> <COURSE_NBR>MA101</COURSE_NBR> <COURSE_GRD>C</COURSE_GRD> <COURSE_NAME>Math Principals</COURSE_NAME> </CGA-MS> <CGA-MS> <COURSE_NBR>FA100</COURSE_NBR> <COURSE_GRD>C</COURSE_GRD> <COURSE_NAME>Visual Thinking</COURSE_NAME> </CGA-MS> </CGA-MV> <CGA-MV> <SEMESTER>SP94</SEMESTER> <CGA-MS> <COURSE_NBR>CS105</COURSE_NBR> <COURSE_GRD>B</COURSE_GRD> <COURSE_NAME>Database Design</COURSE_NAME> </CGA-MS> <CGA-MS> <COURSE_NBR>MA102</COURSE_NBR> <COURSE_GRD>C</COURSE_GRD> <COURSE_NAME>Algebra</COURSE_NAME> </CGA-MS> <CGA-MS> <COURSE_NBR>PY100</COURSE_NBR> <COURSE_GRD>C</COURSE_GRD> <COURSE_NAME>Introduction to Psychology</COURSE_NAME> </CGA-MS> </CGA-MV> </IBM:STUDENT_REC> </SCHOOL> >
Notice in the XML document that LNAME and FNAME are attribute-centric, and the rest of the elements are element-centric.
5-30
Creating an XML Document with a DTD

If you only include the TOXML keyword in the RetrieVe statement, the resulting XML document does not include the DTD. To create an XML document that includes a DTD, use the WITHDTD keyword.
LIST STUDENT.F SEMESTER COURSE_NBR COURSE_GRD COURSE_NAME TOXML WITHDTD Validate XML name changed display name from '@ID' to '_ID'
<?xml version="1.0"?> <!DOCTYPE ROOT[ <!ELEMENT ROOT (STUDENT.F_record*)> <!ELEMENT STUDENT.F_record ( CGA-MV* )> <!ATTLIST STUDENT.F_record _ID CDATA #REQUIRED > <!ELEMENT CGA-MV EMPTY> <!ATTLIST CGA-MV SEMESTER CDATA #IMPLIED COURSE_NBR CDATA #IMPLIED COURSE_GRD CDATA #IMPLIED COURSE_NAME CDATA #IMPLIED > ]> <ROOT> <STUDENT.F_record _ID = "424325656"> <CGA-MV SEMESTER = "SP94" COURSE_NBR = "PY100" COURSE_GRD = COURSE_NAME = "Introduction to Psychology" COURSE_NBR = "PE100" COURSE_GRD = COURSE_NAME = "Golf - I"/> </STUDENT.F_record> <STUDENT.F_record _ID = "521814564"> <CGA-MV SEMESTER = "FA93" COURSE_NBR = "CS130" COURSE_GRD = COURSE_NAME = "Intro to Operating Systems" COURSE_NBR = "CS100" COURSE_GRD = COURSE_NAME = "Intro to Computer Science" COURSE_NBR = "PY100" COURSE_GRD = COURSE_NAME = "Introduction to Psychology"/> <CGA-MV SEMESTER = "SP94" COURSE_NBR = "CS131" COURSE_GRD = COURSE_NAME = "Intro to Operating Systems" COURSE_NBR = "CS101" COURSE_GRD = COURSE_NAME = "Intro to Computer Science" COURSE_NBR = "PE220" COURSE_GRD = COURSE_NAME = "Racquetball"/> </STUDENT.F_record> <STUDENT.F_record _ID = "978766676"> <CGA-MV SEMESTER = "FA93" COURSE_NBR = "FA120" COURSE_GRD =
"C" "C"
"A" "B" "B"
"B" "B" "A"
"A"
5-31
COURSE_NAME = "Finger Painting" COURSE_NBR = "FA230" COURSE_GRD = "C" COURSE_NAME = "Photograp hy Principals" COURSE_NBR = "HY101" COURSE_GRD = "C" COURSE_NAME = "Western Civi lization"/> <CGA-MV SEMESTER = "SP94" COURSE_NBR = "FA121" COURSE_GRD = "A" COURSE_NAME = "Watercorlors" COURSE_NBR = "FA231" COURSE_GRD = "B" COURSE_NAME = "Photography Practicum" COURSE_NBR = "HY102" COURSE_GRD = "I" COURSE_NAME = "Western Civiliza tion - 1500 to 1945"/> </STUDENT.F_record> <STUDENT.F_record _ID = "221345665"> <CGA-MV SEMESTER = "FA93" COURSE_NBR = "EG110" COURSE_GRD = "C" COURSE_NAME = "Engineering Principles" COURSE_NBR = "MA220" COURSE_GRD = "B" COURSE_NAME = "Ca lculus- I" COURSE_NBR = "PY100" COURSE_GRD = "B" COURSE_NAME = "Introduction to Psychology"/> <CGA-MV SEMESTER = "SP94" COURSE_NBR = "EG140" COURSE_GRD = "B" COURSE_NAME = "Fluid Mechanics" COURSE_NBR = "EG240" COURSE_GRD = "B" COURSE_NAME = "Circut Th eory" COURSE_NBR = "MA221" COURSE_GRD = "B" COURSE_NAME = "Calculus - II"/> </STUDENT.F_record> <STUDENT.F_record _ID = "291222021"> <CGA-MV SEMESTER = "SP94" COURSE_NBR = "FA100" COURSE_GRD = "B" COURSE_NAME = "Visual Thinking"/> </STUDENT.F_record> <STUDENT.F_record _ID = "414446545"> <CGA-MV SEMESTER = "FA93" COURSE_NBR = "CS104" COURSE_GRD = "D" COURSE_NAME = "Database Design" COURSE_NBR = "MA101" COURSE_GRD = "C" COURSE_NAME = "Math Prin cipals" COURSE_NBR = "FA100" COURSE_GRD = "C" COURSE_NAME = "Visual Thinking"/> <CGA-MV SEMESTER = "SP94" COURSE_NBR = "CS105" COURSE_GRD = "B" COURSE_NAME = "Database Design" COURSE_NBR = "MA102" COURSE_GRD = "C" COURSE_NAME = "Algebra" COURSE_NBR = "PY100" COURSE_GRD = "C" COURSE_NAME = "Introduction to Psychology" /> </STUDENT.F_record> </ROOT> >
5-32
Using WITHSCHEMA
Use the WITHSCHEMA keyword with the RetrieVe LIST command and the UniVerse SQL SELECT command. The syntax for the LIST command is: LIST [DICT | USING [DICT] dictname] filename ... [TOXML [ELEMENTS][WITHSCHEMA][WITHDTD] TO filename [XMLMAPPING mapping_file]]... The syntax for the UniVerse SQL SELECT command is: To create an XML document from UniVerse SQL, use the UniVerse SQL
SELECT command. SELECT clause FROM clause [WHERE clause] [WHEN clause [WHEN clause]...] [GROUP BY clause] [HAVING clause] [ORDER BY clause] [report_qualifiers] [processing_qualifiers] [TOXML [ELEMENTS] [WITHDTD][WITHSCHEMA] [XMLMAPPING mapping_file]] [XMLDATA extraction_mapping_file];
WITHSCHEMA creates an XML schema filename.xsd. By default, UniVerse writes this file to the &XML& directory. If you do not specify a targetNamespace in the mapping file, the filename.xmls root element contains the following:
noNamespaceSchemaLocation=filename.xsd
to define the schema location. If you specify the targetNamespace in the mapping file, the following is generated:
schemaLocation=namespaceURL filename.xsd
In both of these cases, you can validate the files using the XML schema validator, or the UniVerse BASIC API XDOMValidate() function.
5-33
The following example illustrates the output from a LIST statement using WITHSCHEMA:
>LIST STUDENT FNAME SEMESTER TEACHER COURSE_NBR TOXML WITHSCHEMA
<?xml version="1.0"?> <xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema"> <xsd:annotation> <xsd:documentation xml:lang="en"> account: C:\IBM\UV command: LIST STUDENT FNAME SEMESTER TEACHER COURSE_NBR TOXML WITHSCHEMA </xsd:documentation> </xsd:annotation> <xsd:element name="ROOT"> <xsd:complexType> <xsd:sequence maxOccurs="unbounded"> <xsd:element ref="STUDENT_record" maxOccurs="unbounded"/> </xsd:sequence> </xsd:complexType> </xsd:element> <xsd:element name="STUDENT_record"> <xsd:complexType> <xsd:sequence maxOccurs="unbounded"> <xsd:element ref="CGA-MV" minOccurs="0" maxOccurs="unbounded"/> </xsd:sequence> <xsd:attribute name="_ID"/> <xsd:attribute name="FNAME"/> </xsd:complexType> </xsd:element> <xsd:element name="CGA-MV"> <xsd:complexType> <xsd:attribute name="SEMESTER"/> <xsd:attribute name="TEACHER"/> <xsd:attribute name="COURSE_NBR"/> </xsd:complexType> </xsd:element> </xsd:schema> <?xml version="1.0"?> <ROOT xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <STUDENT_record _ID = "424325656" FNAME = "Sally"> <CGA-MV SEMESTER = "SP94" TEACHER = "Masters" COURSE_NBR = "PY100" TEACHER = " Fisher" COURSE_NBR = "PE100"/> </STUDENT_record> <STUDENT_record _ID = "521814564" FNAME = "Harry"> <CGA-MV SEMESTER = "FA93" TEACHER = "James" COURSE_NBR = "CS130" TEACHER = "Gi bson" COURSE_NBR = "CS100" TEACHER = "Masters" COURSE_NBR = "PY100"/>
5-34
<CGA-MV SEMESTER = "SP94" TEACHER = "Aaron" COURSE_NBR = "CS131" TEACHER = "Gi bson" COURSE_NBR = "CS101" TEACHER = "Fisher" COURSE_NBR = "PE220"/> </STUDENT_record> . . . </ROOT> >
5-35
Creating an XML Document with UniVerse SQL

In addition to RetrieVe, you can also create XML documents using UniVerse SQL. To create an XML document through UniVerse SQL, complete the following steps:
1.
Analyze the DTD associated with the application to which you are sending the XML file. Determine which of your dictionary attributes correspond to the DTD elements. Create an XML mapping file, if necessary. List the appropriate fields using the UniVerse SQL SELECT command.
2. 3.

UniVerse stores XML mapping files and XSL files in the &XML& directory file. To create this file, enter the following command: CREATE.FILE &XML& 19 To create an XML document from UniVerse SQL, use the UniVerse SQL SELECT command. SELECT clause FROM clause [WHERE clause] [WHEN clause [WHEN clause]...] [GROUP BY clause] [HAVING clause] [ORDER BY clause] [report_qualifiers] [processing_qualifiers] [TOXML [ELEMENTS] [WITHDTD] [XMLMAPPING mapping_file]] [XMLDATA extraction_mapping_file];
5-36

Parameter SELECT clause FROM clause WHERE clause WHEN clause GROUP BY clause HAVING clause ORDER BY clause report_qualifiers processing_qualifiers TOXML ELEMENTS WITHDTD XMLMAPPING mapping_file XMLDATA extraction_mapping_file Description Specifies the columns to select from the database. Specifies the tables containing the selected columns. Specifies the criteria that rows must meet to be selected. Specifies the criteria that values in a multivalued column must meet for an association row to be output. Groups rows to summarize results. Specifies the criteria that grouped rows must meet to be selected. Sorts selected rows. Formats a report generated by the SELECT statement. Modifies or reports on the processing of the SELECT statement. Outputs SELECT results in XML format. Outputs results in element-centric format. Output produces a DTD corresponding to the query. Specifies a mapping file containing transformation rules for display. This file must exist in the &XML& file. Specifies the file containing the extraction rules for the XML document. This file is used for receiving an XML file. SELECT Parameters
You must specify clauses in the SELECT statement in the order shown in the syntax. You can use the SELECT statement with type 1, type 19, and type 25 files only if the current isolation level is 0 or 1. For a full discussion of the UniVerse SQL SELECT statement clauses, see the UniVerse SQL Reference.
5-37
Processing Rules for UniVerse SQL SELECT Statements

UniVerse processes SELECT statements much the same as it processes LIST statements, with a few exceptions. The processing rules for a UniVerse SQL SELECT statement against a single table are the same as the RetrieVe LIST rules. For a discussion of how UniVerse SQL processes these statements, see Creating an XML Document from RetrieVe.
Processing Multiple Tables

When processing a UniVerse SQL SELECT statement involving multiple files, UniVerse attempts to keep the nesting inherited in the query in the resulting XML document. Because of this, the order in which you specify the fields in the UniVerse SQL SELECT statement is important for determining how the elements are nested.
Processing in Attribute-centric Mode

As with RetrieVe, the attribute-centric mode is the default mapping mode. For more information about the attribute-centric mode, see Attribute-centric Mode. In this mode, UniVerse uses the name of the file containing the first field you specify in the SELECT statement as the outer-most element in the XML output. Any singlevalued fields you specify in the SELECT statement that belong to this file become attributes of this element. UniVerse processes the SELECT statement in the order you specify. If it finds a field that belongs to another file, UniVerse creates a sub-element. The name of this sub-element is the new file name. All singlevalued fields found in the SELECT statement that belong to this file are created as attributes for the sub-element. If UniVerse finds a multivalued or multi-subvalued field in the SELECT statement, it creates a sub-element. The name of this element is the name of the association of which this field is a member. When you execute UNNEST against an SQL table, it flattens the multivalues into single values. UniVerse processes the ELEMENTS, WITHDTD, and XMLMAPPING keywords in the same manner as it processes them for the RetrieVe LIST command.
5-38
Processing in Element-centric Mode

When using the element-centric mode, UniVerse automatically prefixes each file name to the association name. For example, the CGA association in the STUDENT file is named STUDENT_CGA in the resulting XML file.
XML Limitations in UniVerse SQL

The TOXML keyword is not allowed in the following cases: In a sub-query In a SELECT statement that is part of an INSERT statement. In a SELECT statement that is part of a UNION definition. In a SELECT statement that is part of a VIEW definition.
Examples
This section illustrates XML output from the UniVerse SQL SELECT statement. The examples use sample CUSTOMER, TAPES, and STUDENT files. The following example lists the dictionary records from the CUSTOMER file that are used in the examples:
DICT CUSTOMER 04:31:35pm 11 Oct 2001 Page 1
Type & Field......... Field. Field........ Conversion.. Column......... Output Depth & Name.......... Number Definition... Code........ Heading........ Format Assoc.. NAME TAPES_RENTED TAPE_INFO D D PH 1 7 TAPES_RENTED DATE_OUT DATE_DUE DAYS_BETWEEN TAPE_COST TAPE_NAME UP_NAMES TAPE_CAT 11 Oct 2001 Page 1 Customer Name Tapes 15T 10L S M TAPE_ INFO
DICT TAPES
04:33:47pm
Type & Field......... Field. Field........ Conversion.. Column......... Output Depth & Name.......... Number Definition... Code........ Heading........ Format Assoc.. @ID NAME CAT_NAME D D I 0 1 TRANS('CATEGO RIES',CATEGOR TAPES Tape Name Tape Type 10L 20T 20L S S S CATS
5-39
IES,'NAME','X ') 1 records listed. >
5-40
Creating an XML Document From Multiple Files in Attributecentric Mode

In the following example, UniVerse creates an XML document from the CUSTOMER.F and TAPES.F file in the attribute-centric mode.
>SELECT CUSTOMER.F.NAME, TAPES.F.NAME, CAT_NAME FROM CUSTOMER.F,TAPES.F WHERETAPES_RENTED = TAPES.F.@ID ORDER BY CUSTOMER.F.NAME TOXML;
<?xml version="1.0"?> <ROOT> <CUSTOMER.F_record NAME = "Barrie, Dick"> <TAPES.F NAME = "Citizen Kane"> <TAPES.F_CATS_MV CAT_NAME = "Old Classic"/> <TAPES.F_CATS_MV CAT_NAME = "Drama"/> <TAPES.F_CATS_MV CAT_NAME = "Horror"/> </TAPES.F> </CUSTOMER.F_record> <CUSTOMER.F_record NAME = "Best, George"> <TAPES.F NAME = "Love Story"> <TAPES.F_CATS_MV CAT_NAME = "Romance"/> <TAPES.F_CATS_MV CAT_NAME = "Tear Jerker"/> </TAPES.F> </CUSTOMER.F_record> <CUSTOMER.F_record NAME = "Bowie, David"> <TAPES.F NAME = "The Stalker"> <TAPES.F_CATS_MV CAT_NAME = "Avant Garde"/> <TAPES.F_CATS_MV CAT_NAME = "Science Fiction"/> </TAPES.F> </CUSTOMER.F_record> <CUSTOMER.F_record NAME = "Chase, Carl"> <TAPES.F NAME = "'Round Midnight"> <TAPES.F_CATS_MV CAT_NAME = "Musical"/> <TAPES.F_CATS_MV CAT_NAME = "Drama"/> </TAPES.F> </CUSTOMER.F_record> <CUSTOMER.F_record NAME = "Chase, Carl"> <TAPES.F NAME = "American Graffiti "> <TAPES.F_CATS_MV CAT_NAME = "Comedy"/> <TAPES.F_CATS_MV CAT_NAME = "Childrens Movie"/> </TAPES.F> </CUSTOMER.F_record> <CUSTOMER.F_record NAME = "Chase, Carl"> <TAPES.F NAME = "Flash Gordon"> <TAPES.F_CATS_MV CAT_NAME = "Science Fiction"/> <TAPES.F_CATS_MV CAT_NAME = "Childrens Movie"/> </TAPES.F> </CUSTOMER.F_record> <CUSTOMER.F_record NAME = "Faber, Harry"> <TAPES.F NAME = "To Kill A Mockingbird"> <TAPES.F_CATS_MV CAT_NAME = "Horror"/>
5-41
<TAPES.F_CATS_MV CAT_NAME = "Political"/> <TAPES.F_CATS_MV CAT_NAME = "Drama"/> </TAPES.F> </CUSTOMER.F_record> <CUSTOMER.F_record NAME = "Fischer, Carrie"> <TAPES.F NAME = "Girl Friday"> <TAPES.F_CATS_MV CAT_NAME = "Comedy"/> <TAPES.F_CATS_MV CAT_NAME = "Old Classic"/> </TAPES.F> </CUSTOMER.F_record> <CUSTOMER.F_record NAME = "James, Bob"> <TAPES.F NAME = "Blue Velvet"> <TAPES.F_CATS_MV CAT_NAME = "Horror"/> <TAPES.F_CATS_MV CAT_NAME = "Drama"/> <TAPES.F_CATS_MV CAT_NAME = "Avant Garde"/> </TAPES.F> </CUSTOMER.F_record> <CUSTOMER.F_record NAME = "Jamieson, Dale"> <TAPES.F NAME = "2001"> <TAPES.F_CATS_MV CAT_NAME = "Science Fiction"/> <TAPES.F_CATS_MV CAT_NAME = "Drama"/> </TAPES.F> </CUSTOMER.F_record> <CUSTOMER.F_record NAME = "Jones, Bob"> <TAPES.F NAME = "Z"> <TAPES.F_CATS_MV CAT_NAME = "Political"/> <TAPES.F_CATS_MV CAT_NAME = "Drama"/> </TAPES.F> </CUSTOMER.F_record> <CUSTOMER.F_record NAME = "Jones, Freddie"> <TAPES.F NAME = "Help"> <TAPES.F_CATS_MV CAT_NAME = "Childrens Movie"/> <TAPES.F_CATS_MV CAT_NAME = "Comedy"/> <TAPES.F_CATS_MV CAT_NAME = "Musical"/> </TAPES.F> </CUSTOMER.F_record> <CUSTOMER.F_record NAME = "Jones, Mable"> <TAPES.F NAME = "Psycho"> <TAPES.F_CATS_MV CAT_NAME = "Horror"/> <TAPES.F_CATS_MV CAT_NAME = "Drama"/> </TAPES.F> </CUSTOMER.F_record> <CUSTOMER.F_record NAME = "Jones, Mable"> <TAPES.F NAME = "Gone With The Wind"> <TAPES.F_CATS_MV CAT_NAME = "Romance"/> </TAPES.F> </CUSTOMER.F_record> <CUSTOMER.F_record NAME = "Jones, Samuel"> <TAPES.F NAME = "'Round Midnight"> <TAPES.F_CATS_MV CAT_NAME = "Musical"/> <TAPES.F_CATS_MV CAT_NAME = "Drama"/> </TAPES.F> </CUSTOMER.F_record> <CUSTOMER.F_record NAME = "Jones, Samuel">
5-42
<TAPES.F NAME = "Flash Gordon"> <TAPES.F_CATS_MV CAT_NAME = "Science Fiction"/> <TAPES.F_CATS_MV CAT_NAME = "Childrens Movie"/> </TAPES.F> </CUSTOMER.F_record> <CUSTOMER.F_record NAME = "Partner, Bonnie"> <TAPES.F NAME = "Tammy"> <TAPES.F_CATS_MV CAT_NAME = "Romance"/> </TAPES.F> </CUSTOMER.F_record> <CUSTOMER.F_record NAME = "Partner, Bonnie"> <TAPES.F NAME = "Love Story"> <TAPES.F_CATS_MV CAT_NAME = "Romance"/> <TAPES.F_CATS_MV CAT_NAME = "Tear Jerker"/> </TAPES.F> </CUSTOMER.F_record> <CUSTOMER.F_record NAME = "Smith, Harry"> <TAPES.F NAME = "Journey Abroad"> <TAPES.F_CATS_MV CAT_NAME = "B - Movie"/> </TAPES.F> </CUSTOMER.F_record> <CUSTOMER.F_record NAME = "Smith, Harry"> <TAPES.F NAME = "Catch 22"> <TAPES.F_CATS_MV CAT_NAME = "Comedy"/> <TAPES.F_CATS_MV CAT_NAME = "Avant Garde"/> </TAPES.F> </CUSTOMER.F_record> <CUSTOMER.F_record NAME = "Smith, Harry"> <TAPES.F NAME = "Blue Velvet"> <TAPES.F_CATS_MV CAT_NAME = "Horror"/> <TAPES.F_CATS_MV CAT_NAME = "Drama"/> <TAPES.F_CATS_MV CAT_NAME = "Avant Garde"/> </TAPES.F> </CUSTOMER.F_record> </ROOT> >
5-43
The next example illustrates the results of a UniVerse SQL statement against the same fields with a different SELECT order and a different sorting option:
01 SELECT TAPES.F.NAME, CUSTOMER.F.NAME, CAT_NAME FROM CUSTOMER.F, TAPES.F WHERE TAPES_RENTED = TAPES.F.@ID ORDER BY TAPES.F.NAME TOXML;
<?xml version="1.0"?> <ROOT> <TAPES.F_record NAME = "'Round Midnight"> <CUSTOMER.F NAME = "Jones, Samuel"/> <TAPES.F_CATS_MV CAT_NAME = "Musical"/> <TAPES.F_CATS_MV CAT_NAME = "Drama"/> </TAPES.F_record> <TAPES.F_record NAME = "'Round Midnight"> <CUSTOMER.F NAME = "Chase, Carl"/> <TAPES.F_CATS_MV CAT_NAME = "Musical"/> <TAPES.F_CATS_MV CAT_NAME = "Drama"/> </TAPES.F_record> <TAPES.F_record NAME = "2001"> <CUSTOMER.F NAME = "Jamieson, Dale"/> <TAPES.F_CATS_MV CAT_NAME = "Science Fiction"/> <TAPES.F_CATS_MV CAT_NAME = "Drama"/> </TAPES.F_record> <TAPES.F_record NAME = "American Graffiti "> <CUSTOMER.F NAME = "Chase, Carl"/> <TAPES.F_CATS_MV CAT_NAME = "Comedy"/> <TAPES.F_CATS_MV CAT_NAME = "Childrens Movie"/> </TAPES.F_record> <TAPES.F_record NAME = "Blue Velvet"> <CUSTOMER.F NAME = "Smith, Harry"/> <TAPES.F_CATS_MV CAT_NAME = "Horror"/> <TAPES.F_CATS_MV CAT_NAME = "Drama"/> <TAPES.F_CATS_MV CAT_NAME = "Avant Garde"/> </TAPES.F_record> <TAPES.F_record NAME = "Blue Velvet"> <CUSTOMER.F NAME = "James, Bob"/> <TAPES.F_CATS_MV CAT_NAME = "Horror"/> <TAPES.F_CATS_MV CAT_NAME = "Drama"/> <TAPES.F_CATS_MV CAT_NAME = "Avant Garde"/> </TAPES.F_record> <TAPES.F_record NAME = "Catch 22"> <CUSTOMER.F NAME = "Smith, Harry"/> <TAPES.F_CATS_MV CAT_NAME = "Comedy"/> <TAPES.F_CATS_MV CAT_NAME = "Avant Garde"/> </TAPES.F_record> <TAPES.F_record NAME = "Citizen Kane"> <CUSTOMER.F NAME = "Barrie, Dick"/> <TAPES.F_CATS_MV CAT_NAME = "Old Classic"/> <TAPES.F_CATS_MV CAT_NAME = "Drama"/> <TAPES.F_CATS_MV CAT_NAME = "Horror"/> </TAPES.F_record> <TAPES.F_record NAME = "Flash Gordon">
5-44
<CUSTOMER.F NAME = "Chase, Carl"/> <TAPES.F_CATS_MV CAT_NAME = "Science Fiction"/> <TAPES.F_CATS_MV CAT_NAME = "Childrens Movie"/> </TAPES.F_record> <TAPES.F_record NAME = "Flash Gordon"> <CUSTOMER.F NAME = "Jones, Samuel"/> <TAPES.F_CATS_MV CAT_NAME = "Science Fiction"/> <TAPES.F_CATS_MV CAT_NAME = "Childrens Movie"/> </TAPES.F_record> <TAPES.F_record NAME = "Girl Friday"> <CUSTOMER.F NAME = "Fischer, Carrie"/> <TAPES.F_CATS_MV CAT_NAME = "Comedy"/> <TAPES.F_CATS_MV CAT_NAME = "Old Classic"/> </TAPES.F_record> <TAPES.F_record NAME = "Gone With The Wind"> <CUSTOMER.F NAME = "Jones, Mable"/> <TAPES.F_CATS_MV CAT_NAME = "Romance"/> </TAPES.F_record> <TAPES.F_record NAME = "Help"> <CUSTOMER.F NAME = "Jones, Freddie"/> <TAPES.F_CATS_MV CAT_NAME = "Childrens Movie"/> <TAPES.F_CATS_MV CAT_NAME = "Comedy"/> <TAPES.F_CATS_MV CAT_NAME = "Musical"/> </TAPES.F_record> <TAPES.F_record NAME = "Journey Abroad"> <CUSTOMER.F NAME = "Smith, Harry"/> <TAPES.F_CATS_MV CAT_NAME = "B - Movie"/> </TAPES.F_record> <TAPES.F_record NAME = "Love Story"> <CUSTOMER.F NAME = "Partner, Bonnie"/> <TAPES.F_CATS_MV CAT_NAME = "Romance"/> <TAPES.F_CATS_MV CAT_NAME = "Tear Jerker"/> </TAPES.F_record> <TAPES.F_record NAME = "Love Story"> <CUSTOMER.F NAME = "Best, George"/> <TAPES.F_CATS_MV CAT_NAME = "Romance"/> <TAPES.F_CATS_MV CAT_NAME = "Tear Jerker"/> </TAPES.F_record> <TAPES.F_record NAME = "Psycho"> <CUSTOMER.F NAME = "Jones, Mable"/> <TAPES.F_CATS_MV CAT_NAME = "Horror"/> <TAPES.F_CATS_MV CAT_NAME = "Drama"/> </TAPES.F_record> <TAPES.F_record NAME = "Tammy"> <CUSTOMER.F NAME = "Partner, Bonnie"/> <TAPES.F_CATS_MV CAT_NAME = "Romance"/> </TAPES.F_record> <TAPES.F_record NAME = "The Stalker"> <CUSTOMER.F NAME = "Bowie, David"/> <TAPES.F_CATS_MV CAT_NAME = "Avant Garde"/> <TAPES.F_CATS_MV CAT_NAME = "Science Fiction"/> </TAPES.F_record> <TAPES.F_record NAME = "To Kill A Mockingbird"> <CUSTOMER.F NAME = "Faber, Harry"/>
5-45
<TAPES.F_CATS_MV CAT_NAME = "Horror"/> <TAPES.F_CATS_MV CAT_NAME = "Political"/> <TAPES.F_CATS_MV CAT_NAME = "Drama"/> </TAPES.F_record> <TAPES.F_record NAME = "Z"> <CUSTOMER.F NAME = "Jones, Bob"/> <TAPES.F_CATS_MV CAT_NAME = "Political"/> <TAPES.F_CATS_MV CAT_NAME = "Drama"/> </TAPES.F_record> </ROOT> >
5-46
Creating an XML Document From Multiple Files in Element-centric Mode

The following example illustrates creating an XML document from multiple files in element-centric mode, using the ELEMENTS keyword.
>SELECT CUSTOMER.NAME, TAPES.NAME, CAT_NAME FROM CUSTOMER, TAPES WHERE TAPES_RENTED = TAPES.@ID ORDER BY CUSTOMER.NAME TOXML ELEMENTS; Validate XML name changed display name from 'Customer Name' to 'Customer_Name' Validate XML name changed display name from 'Tape Name' to 'Tape_Name' Validate XML name changed display name from 'Tape Type' to 'Tape_Type'
<?xml version="1.0"?> <ROOT> <CUSTOMER_record> <Customer_Name>Chase, Carl</Customer_Name> <TAPES> <Tape_Name>American Graffiti</Tape_Name> <TAPES_CATS_MV> <Tape_Type>Comedy</Tape_Type> </TAPES_CATS_MV> <TAPES_CATS_MV> <Tape_Type>Childrens Movie</Tape_Type> </TAPES_CATS_MV> </TAPES> </CUSTOMER_record> <CUSTOMER_record> <Customer_Name>Chase, Carl</Customer_Name> <TAPES> <Tape_Name>Flash Gordon</Tape_Name> <TAPES_CATS_MV> <Tape_Type>Science Fiction</Tape_Type> </TAPES_CATS_MV> <TAPES_CATS_MV> <Tape_Type>Childrens Movie</Tape_Type> </TAPES_CATS_MV> </TAPES> </CUSTOMER_record> <CUSTOMER_record> <Customer_Name>Chase, Carl</Customer_Name> <TAPES> <Tape_Name>'Round Midnight</Tape_Name> <TAPES_CATS_MV> <Tape_Type>Musical</Tape_Type> </TAPES_CATS_MV> <TAPES_CATS_MV> <Tape_Type>Drama</Tape_Type> </TAPES_CATS_MV>
5-47
</TAPES> </CUSTOMER_record> <CUSTOMER_record> <Customer_Name>Jamieson, Dale</Customer_Name> <TAPES> <Tape_Name>2001</Tape_Name> <TAPES_CATS_MV> <Tape_Type>Science Fiction</Tape_Type> </TAPES_CATS_MV> <TAPES_CATS_MV> <Tape_Type>Drama</Tape_Type> </TAPES_CATS_MV> </TAPES> </CUSTOMER_record> <CUSTOMER_record> <Customer_Name>Jones, Bob</Customer_Name> <TAPES> <Tape_Name>Z</Tape_Name> <TAPES_CATS_MV> <Tape_Type>Political</Tape_Type> </TAPES_CATS_MV> <TAPES_CATS_MV> <Tape_Type>Drama</Tape_Type> </TAPES_CATS_MV> </TAPES> </CUSTOMER_record> </ROOT> >
5-48
Creating an XML Document From Multiple Files with a Multivalued Field

The next example illustrates creating an XML document from multiple files with a multivalued field. In the example, TAPES_RENTED is multivalued and belongs to the TAPE_INFO association in the CUSTOMER file. In the XML document, TAPES_RENTED appears in the CUSTOMER_TAPE_INFO_MV element.
>SELECT CUSTOMER.F.NAME, TAPES.F.NAME, CAT_NAME, TAPES_RENTED FROM CUSTOMER.F, TAPES.F WHERE TAPES_RENTED = TAPES.F.@ID ORDER BY CUSTOMER.F.NAME TOXML;
<?xml version="1.0"?> <ROOT> <CUSTOMER.F_record NAME = "Barrie, Dick"> <TAPES.F NAME = "Citizen Kane"> <TAPES.F_CATS_MV CAT_NAME = "Old Classic"/> <TAPES.F_CATS_MV CAT_NAME = "Drama"/> <TAPES.F_CATS_MV CAT_NAME = "Horror"/> </TAPES.F> <CUSTOMER.F_TAPE_INFO_MV TAPES_RENTED = "V996"/> </CUSTOMER.F_record> <CUSTOMER.F_record NAME = "Best, George"> <TAPES.F NAME = "Love Story"> <TAPES.F_CATS_MV CAT_NAME = "Romance"/> <TAPES.F_CATS_MV CAT_NAME = "Tear Jerker"/> </TAPES.F> <CUSTOMER.F_TAPE_INFO_MV TAPES_RENTED = "B2297"/> </CUSTOMER.F_record> <CUSTOMER.F_record NAME = "Bowie, David"> <TAPES.F NAME = "The Stalker"> <TAPES.F_CATS_MV CAT_NAME = "Avant Garde"/> <TAPES.F_CATS_MV CAT_NAME = "Science Fiction"/> </TAPES.F> <CUSTOMER.F_TAPE_INFO_MV TAPES_RENTED = "V9961"/> </CUSTOMER.F_record> <CUSTOMER.F_record NAME = "Chase, Carl"> <TAPES.F NAME = "'Round Midnight"> <TAPES.F_CATS_MV CAT_NAME = "Musical"/> <TAPES.F_CATS_MV CAT_NAME = "Drama"/> </TAPES.F> <CUSTOMER.F_TAPE_INFO_MV TAPES_RENTED = "V8481"/> <CUSTOMER.F_TAPE_INFO_MV TAPES_RENTED = "V1254"/> <CUSTOMER.F_TAPE_INFO_MV TAPES_RENTED = "V4951"/> </CUSTOMER.F_record> <CUSTOMER.F_record NAME = "Chase, Carl"> <TAPES.F NAME = "American Graffiti "> <TAPES.F_CATS_MV CAT_NAME = "Comedy"/> <TAPES.F_CATS_MV CAT_NAME = "Childrens Movie"/> </TAPES.F> <CUSTOMER.F_TAPE_INFO_MV TAPES_RENTED = "V8481"/>
5-49
<CUSTOMER.F_TAPE_INFO_MV TAPES_RENTED = "V1254"/> <CUSTOMER.F_TAPE_INFO_MV TAPES_RENTED = "V4951"/> </CUSTOMER.F_record> <CUSTOMER.F_record NAME = "Chase, Carl"> <TAPES.F NAME = "Flash Gordon"> <TAPES.F_CATS_MV CAT_NAME = "Science Fiction"/> <TAPES.F_CATS_MV CAT_NAME = "Childrens Movie"/> </TAPES.F> <CUSTOMER.F_TAPE_INFO_MV TAPES_RENTED = "V8481"/> <CUSTOMER.F_TAPE_INFO_MV TAPES_RENTED = "V1254"/> <CUSTOMER.F_TAPE_INFO_MV TAPES_RENTED = "V4951"/> </CUSTOMER.F_record> <CUSTOMER.F_record NAME = "Faber, Harry"> <TAPES.F NAME = "To Kill A Mockingbird"> <TAPES.F_CATS_MV CAT_NAME = "Horror"/> <TAPES.F_CATS_MV CAT_NAME = "Political"/> <TAPES.F_CATS_MV CAT_NAME = "Drama"/> </TAPES.F> <CUSTOMER.F_TAPE_INFO_MV TAPES_RENTED = "V5151"/> </CUSTOMER.F_record> <CUSTOMER.F_record NAME = "Fischer, Carrie"> <TAPES.F NAME = "Girl Friday"> <TAPES.F_CATS_MV CAT_NAME = "Comedy"/> <TAPES.F_CATS_MV CAT_NAME = "Old Classic"/> </TAPES.F> <CUSTOMER.F_TAPE_INFO_MV TAPES_RENTED = "V110"/> </CUSTOMER.F_record> <CUSTOMER.F_record NAME = "James, Bob"> <TAPES.F NAME = "Blue Velvet"> <TAPES.F_CATS_MV CAT_NAME = "Horror"/> <TAPES.F_CATS_MV CAT_NAME = "Drama"/> <TAPES.F_CATS_MV CAT_NAME = "Avant Garde"/> </TAPES.F> <CUSTOMER.F_TAPE_INFO_MV TAPES_RENTED = "V2001"/> </CUSTOMER.F_record> <CUSTOMER.F_record NAME = "Jamieson, Dale"> <TAPES.F NAME = "2001"> <TAPES.F_CATS_MV CAT_NAME = "Science Fiction"/> <TAPES.F_CATS_MV CAT_NAME = "Drama"/> </TAPES.F> <CUSTOMER.F_TAPE_INFO_MV TAPES_RENTED = "V6670"/> </CUSTOMER.F_record> <CUSTOMER.F_record NAME = "Jones, Bob"> <TAPES.F NAME = "Z"> <TAPES.F_CATS_MV CAT_NAME = "Political"/> <TAPES.F_CATS_MV CAT_NAME = "Drama"/> </TAPES.F> <CUSTOMER.F_TAPE_INFO_MV TAPES_RENTED = "V4341"/> </CUSTOMER.F_record> <CUSTOMER.F_record NAME = "Jones, Freddie"> <TAPES.F NAME = "Help"> <TAPES.F_CATS_MV CAT_NAME = "Childrens Movie"/> <TAPES.F_CATS_MV CAT_NAME = "Comedy"/> <TAPES.F_CATS_MV CAT_NAME = "Musical"/>
5-50
</TAPES.F> <CUSTOMER.F_TAPE_INFO_MV TAPES_RENTED = "V9431"/> </CUSTOMER.F_record> <CUSTOMER.F_record NAME = "Jones, Mable"> <TAPES.F NAME = "Psycho"> <TAPES.F_CATS_MV CAT_NAME = "Horror"/> <TAPES.F_CATS_MV CAT_NAME = "Drama"/> </TAPES.F> <CUSTOMER.F_TAPE_INFO_MV TAPES_RENTED = "V1249"/> <CUSTOMER.F_TAPE_INFO_MV TAPES_RENTED = "V4499"/> </CUSTOMER.F_record> <CUSTOMER.F_record NAME = "Jones, Mable"> <TAPES.F NAME = "Gone With The Wind"> <TAPES.F_CATS_MV CAT_NAME = "Romance"/> </TAPES.F> <CUSTOMER.F_TAPE_INFO_MV TAPES_RENTED = "V1249"/> <CUSTOMER.F_TAPE_INFO_MV TAPES_RENTED = "V4499"/> </CUSTOMER.F_record> <CUSTOMER.F_record NAME = "Jones, Samuel"> <TAPES.F NAME = "'Round Midnight"> <TAPES.F_CATS_MV CAT_NAME = "Musical"/> <TAPES.F_CATS_MV CAT_NAME = "Drama"/> </TAPES.F> <CUSTOMER.F_TAPE_INFO_MV TAPES_RENTED = "V1254"/> <CUSTOMER.F_TAPE_INFO_MV TAPES_RENTED = "V8481"/> </CUSTOMER.F_record> <CUSTOMER.F_record NAME = "Jones, Samuel"> <TAPES.F NAME = "Flash Gordon"> <TAPES.F_CATS_MV CAT_NAME = "Science Fiction"/> <TAPES.F_CATS_MV CAT_NAME = "Childrens Movie"/> </TAPES.F> <CUSTOMER.F_TAPE_INFO_MV TAPES_RENTED = "V1254"/> <CUSTOMER.F_TAPE_INFO_MV TAPES_RENTED = "V8481"/> </CUSTOMER.F_record> <CUSTOMER.F_record NAME = "Partner, Bonnie"> <TAPES.F NAME = "Tammy"> <TAPES.F_CATS_MV CAT_NAME = "Romance"/> </TAPES.F> <CUSTOMER.F_TAPE_INFO_MV TAPES_RENTED = "B914"/> <CUSTOMER.F_TAPE_INFO_MV TAPES_RENTED = "B2297"/> </CUSTOMER.F_record> <CUSTOMER.F_record NAME = "Partner, Bonnie"> <TAPES.F NAME = "Love Story"> <TAPES.F_CATS_MV CAT_NAME = "Romance"/> <TAPES.F_CATS_MV CAT_NAME = "Tear Jerker"/> </TAPES.F> <CUSTOMER.F_TAPE_INFO_MV TAPES_RENTED = "B914"/> <CUSTOMER.F_TAPE_INFO_MV TAPES_RENTED = "B2297"/> </CUSTOMER.F_record> <CUSTOMER.F_record NAME = "Smith, Harry"> <TAPES.F NAME = "Journey Abroad"> <TAPES.F_CATS_MV CAT_NAME = "B - Movie"/> </TAPES.F> <CUSTOMER.F_TAPE_INFO_MV TAPES_RENTED = "V2001"/>
5-51
<CUSTOMER.F_TAPE_INFO_MV TAPES_RENTED = "V5004"/> <CUSTOMER.F_TAPE_INFO_MV TAPES_RENTED = "V8181"/> </CUSTOMER.F_record> <CUSTOMER.F_record NAME = "Smith, Harry"> <TAPES.F NAME = "Catch 22"> <TAPES.F_CATS_MV CAT_NAME = "Comedy"/> <TAPES.F_CATS_MV CAT_NAME = "Avant Garde"/> </TAPES.F> <CUSTOMER.F_TAPE_INFO_MV TAPES_RENTED = "V2001"/> <CUSTOMER.F_TAPE_INFO_MV TAPES_RENTED = "V5004"/> <CUSTOMER.F_TAPE_INFO_MV TAPES_RENTED = "V8181"/> </CUSTOMER.F_record> <CUSTOMER.F_record NAME = "Smith, Harry"> <TAPES.F NAME = "Blue Velvet"> <TAPES.F_CATS_MV CAT_NAME = "Horror"/> <TAPES.F_CATS_MV CAT_NAME = "Drama"/> <TAPES.F_CATS_MV CAT_NAME = "Avant Garde"/> </TAPES.F> <CUSTOMER.F_TAPE_INFO_MV TAPES_RENTED = "V2001"/> <CUSTOMER.F_TAPE_INFO_MV TAPES_RENTED = "V5004"/> <CUSTOMER.F_TAPE_INFO_MV TAPES_RENTED = "V8181"/> </CUSTOMER.F_record> </ROOT> >
5-52
Creating an XML Document From Multiple Files with a DTD

The following example illustrates creating an XML document from multiple files with a DTD. To include the DTD, use the WITHDTD keyword.
>SELECT CUSTOMER.F.NAME, TAPES.F.NAME, CAT_NAME, TAPES_RENTED FROM CUSTOMER.F, TAPES.F WHERE TAPES_RENTED = TAPES.F.@ID ORDER BY CUSTOMER.F.NAME TOXML WITHDTD;
<?xml version="1.0"?> <!DOCTYPE ROOT[ <!ELEMENT ROOT (CUSTOMER.F_record*)> <!ELEMENT CUSTOMER.F_record ( TAPES.F* , CUSTOMER.F_TAPE_INFO_MV* )> <!ATTLIST CUSTOMER.F_record NAME CDATA #REQUIRED > <!ELEMENT TAPES.F ( TAPES.F_CATS_MV* )> <!ATTLIST TAPES.F NAME CDATA #IMPLIED > <!ELEMENT TAPES.F_CATS_MV EMPTY> <!ATTLIST TAPES.F_CATS_MV CAT_NAME CDATA #IMPLIED > <!ELEMENT CUSTOMER.F_TAPE_INFO_MV EMPTY> <!ATTLIST CUSTOMER.F_TAPE_INFO_MV TAPES_RENTED CDATA #IMPLIED > ]> <ROOT> <CUSTOMER.F_record NAME = "Barrie, Dick"> <TAPES.F NAME = "Citizen Kane"> <TAPES.F_CATS_MV CAT_NAME = "Old Classic"/> <TAPES.F_CATS_MV CAT_NAME = "Drama"/> <TAPES.F_CATS_MV CAT_NAME = "Horror"/> </TAPES.F> <CUSTOMER.F_TAPE_INFO_MV TAPES_RENTED = "V996"/> </CUSTOMER.F_record> <CUSTOMER.F_record NAME = "Best, George"> <TAPES.F NAME = "Love Story"> <TAPES.F_CATS_MV CAT_NAME = "Romance"/> <TAPES.F_CATS_MV CAT_NAME = "Tear Jerker"/> </TAPES.F> <CUSTOMER.F_TAPE_INFO_MV TAPES_RENTED = "B2297"/> </CUSTOMER.F_record> <CUSTOMER.F_record NAME = "Bowie, David"> <TAPES.F NAME = "The Stalker"> <TAPES.F_CATS_MV CAT_NAME = "Avant Garde"/> <TAPES.F_CATS_MV CAT_NAME = "Science Fiction"/> </TAPES.F> <CUSTOMER.F_TAPE_INFO_MV TAPES_RENTED = "V9961"/>
5-53
</CUSTOMER.F_record> <CUSTOMER.F_record NAME = "Chase, Carl"> <TAPES.F NAME = "'Round Midnight"> <TAPES.F_CATS_MV CAT_NAME = "Musical"/> <TAPES.F_CATS_MV CAT_NAME = "Drama"/> </TAPES.F> <CUSTOMER.F_TAPE_INFO_MV TAPES_RENTED = "V8481"/> <CUSTOMER.F_TAPE_INFO_MV TAPES_RENTED = "V1254"/> <CUSTOMER.F_TAPE_INFO_MV TAPES_RENTED = "V4951"/> </CUSTOMER.F_record> <CUSTOMER.F_record NAME = "Chase, Carl"> <TAPES.F NAME = "American Graffiti "> <TAPES.F_CATS_MV CAT_NAME = "Comedy"/> <TAPES.F_CATS_MV CAT_NAME = "Childrens Movie"/> </TAPES.F> <CUSTOMER.F_TAPE_INFO_MV TAPES_RENTED = "V8481"/> <CUSTOMER.F_TAPE_INFO_MV TAPES_RENTED = "V1254"/> <CUSTOMER.F_TAPE_INFO_MV TAPES_RENTED = "V4951"/> </CUSTOMER.F_record> <CUSTOMER.F_record NAME = "Chase, Carl"> <TAPES.F NAME = "Flash Gordon"> <TAPES.F_CATS_MV CAT_NAME = "Science Fiction"/> <TAPES.F_CATS_MV CAT_NAME = "Childrens Movie"/> </TAPES.F> <CUSTOMER.F_TAPE_INFO_MV TAPES_RENTED = "V8481"/> <CUSTOMER.F_TAPE_INFO_MV TAPES_RENTED = "V1254"/> <CUSTOMER.F_TAPE_INFO_MV TAPES_RENTED = "V4951"/> </CUSTOMER.F_record> <CUSTOMER.F_record NAME = "Faber, Harry"> <TAPES.F NAME = "To Kill A Mockingbird"> <TAPES.F_CATS_MV CAT_NAME = "Horror"/> <TAPES.F_CATS_MV CAT_NAME = "Political"/> <TAPES.F_CATS_MV CAT_NAME = "Drama"/> </TAPES.F> <CUSTOMER.F_TAPE_INFO_MV TAPES_RENTED = "V5151"/> </CUSTOMER.F_record> <CUSTOMER.F_record NAME = "Fischer, Carrie"> <TAPES.F NAME = "Girl Friday"> <TAPES.F_CATS_MV CAT_NAME = "Comedy"/> <TAPES.F_CATS_MV CAT_NAME = "Old Classic"/> </TAPES.F> <CUSTOMER.F_TAPE_INFO_MV TAPES_RENTED = "V110"/> </CUSTOMER.F_record> <CUSTOMER.F_record NAME = "James, Bob"> <TAPES.F NAME = "Blue Velvet"> <TAPES.F_CATS_MV CAT_NAME = "Horror"/> <TAPES.F_CATS_MV CAT_NAME = "Drama"/> <TAPES.F_CATS_MV CAT_NAME = "Avant Garde"/> </TAPES.F> <CUSTOMER.F_TAPE_INFO_MV TAPES_RENTED = "V2001"/> </CUSTOMER.F_record> <CUSTOMER.F_record NAME = "Jamieson, Dale"> <TAPES.F NAME = "2001"> <TAPES.F_CATS_MV CAT_NAME = "Science Fiction"/>
5-54
<TAPES.F_CATS_MV CAT_NAME = "Drama"/> </TAPES.F> <CUSTOMER.F_TAPE_INFO_MV TAPES_RENTED = "V6670"/> </CUSTOMER.F_record> <CUSTOMER.F_record NAME = "Jones, Bob"> <TAPES.F NAME = "Z"> <TAPES.F_CATS_MV CAT_NAME = "Political"/> <TAPES.F_CATS_MV CAT_NAME = "Drama"/> </TAPES.F> <CUSTOMER.F_TAPE_INFO_MV TAPES_RENTED = "V4341"/> </CUSTOMER.F_record> <CUSTOMER.F_record NAME = "Jones, Freddie"> <TAPES.F NAME = "Help"> <TAPES.F_CATS_MV CAT_NAME = "Childrens Movie"/> <TAPES.F_CATS_MV CAT_NAME = "Comedy"/> <TAPES.F_CATS_MV CAT_NAME = "Musical"/> </TAPES.F> <CUSTOMER.F_TAPE_INFO_MV TAPES_RENTED = "V9431"/> </CUSTOMER.F_record> <CUSTOMER.F_record NAME = "Jones, Mable"> <TAPES.F NAME = "Psycho"> <TAPES.F_CATS_MV CAT_NAME = "Horror"/> <TAPES.F_CATS_MV CAT_NAME = "Drama"/> </TAPES.F> <CUSTOMER.F_TAPE_INFO_MV TAPES_RENTED = "V1249"/> <CUSTOMER.F_TAPE_INFO_MV TAPES_RENTED = "V4499"/> </CUSTOMER.F_record> <CUSTOMER.F_record NAME = "Jones, Mable"> <TAPES.F NAME = "Gone With The Wind"> <TAPES.F_CATS_MV CAT_NAME = "Romance"/> </TAPES.F> <CUSTOMER.F_TAPE_INFO_MV TAPES_RENTED = "V1249"/> <CUSTOMER.F_TAPE_INFO_MV TAPES_RENTED = "V4499"/> </CUSTOMER.F_record> <CUSTOMER.F_record NAME = "Jones, Samuel"> <TAPES.F NAME = "'Round Midnight"> <TAPES.F_CATS_MV CAT_NAME = "Musical"/> <TAPES.F_CATS_MV CAT_NAME = "Drama"/> </TAPES.F> <CUSTOMER.F_TAPE_INFO_MV TAPES_RENTED = "V1254"/> <CUSTOMER.F_TAPE_INFO_MV TAPES_RENTED = "V8481"/> </CUSTOMER.F_record> <CUSTOMER.F_record NAME = "Jones, Samuel"> <TAPES.F NAME = "Flash Gordon"> <TAPES.F_CATS_MV CAT_NAME = "Science Fiction"/> <TAPES.F_CATS_MV CAT_NAME = "Childrens Movie"/> </TAPES.F> <CUSTOMER.F_TAPE_INFO_MV TAPES_RENTED = "V1254"/> <CUSTOMER.F_TAPE_INFO_MV TAPES_RENTED = "V8481"/> </CUSTOMER.F_record> <CUSTOMER.F_record NAME = "Partner, Bonnie"> <TAPES.F NAME = "Tammy"> <TAPES.F_CATS_MV CAT_NAME = "Romance"/> </TAPES.F>
5-55
<CUSTOMER.F_TAPE_INFO_MV TAPES_RENTED = "B914"/> <CUSTOMER.F_TAPE_INFO_MV TAPES_RENTED = "B2297"/> </CUSTOMER.F_record> <CUSTOMER.F_record NAME = "Partner, Bonnie"> <TAPES.F NAME = "Love Story"> <TAPES.F_CATS_MV CAT_NAME = "Romance"/> <TAPES.F_CATS_MV CAT_NAME = "Tear Jerker"/> </TAPES.F> <CUSTOMER.F_TAPE_INFO_MV TAPES_RENTED = "B914"/> <CUSTOMER.F_TAPE_INFO_MV TAPES_RENTED = "B2297"/> </CUSTOMER.F_record> <CUSTOMER.F_record NAME = "Smith, Harry"> <TAPES.F NAME = "Journey Abroad"> <TAPES.F_CATS_MV CAT_NAME = "B - Movie"/> </TAPES.F> <CUSTOMER.F_TAPE_INFO_MV TAPES_RENTED = "V2001"/> <CUSTOMER.F_TAPE_INFO_MV TAPES_RENTED = "V5004"/> <CUSTOMER.F_TAPE_INFO_MV TAPES_RENTED = "V8181"/> </CUSTOMER.F_record> <CUSTOMER.F_record NAME = "Smith, Harry"> <TAPES.F NAME = "Catch 22"> <TAPES.F_CATS_MV CAT_NAME = "Comedy"/> <TAPES.F_CATS_MV CAT_NAME = "Avant Garde"/> </TAPES.F> <CUSTOMER.F_TAPE_INFO_MV TAPES_RENTED = "V2001"/> <CUSTOMER.F_TAPE_INFO_MV TAPES_RENTED = "V5004"/> <CUSTOMER.F_TAPE_INFO_MV TAPES_RENTED = "V8181"/> </CUSTOMER.F_record> <CUSTOMER.F_record NAME = "Smith, Harry"> <TAPES.F NAME = "Blue Velvet"> <TAPES.F_CATS_MV CAT_NAME = "Horror"/> <TAPES.F_CATS_MV CAT_NAME = "Drama"/> <TAPES.F_CATS_MV CAT_NAME = "Avant Garde"/> </TAPES.F> <CUSTOMER.F_TAPE_INFO_MV TAPES_RENTED = "V2001"/> <CUSTOMER.F_TAPE_INFO_MV TAPES_RENTED = "V5004"/> <CUSTOMER.F_TAPE_INFO_MV TAPES_RENTED = "V8181"/> </CUSTOMER.F_record> </ROOT> >
Creating an XML Document From Multiple Files Using a Mapping File

As with RetrieVe, you can create a mapping file to define transformation rules differing from the defaults. For information about creating the mapping file, see The Mapping File.
5-56
The following mapping file defines rules for the CUSTOMER and TAPES file.
<?XML version= 1.0 ?> <U2xml-mapping xmlns:U2xml=http://www.informix.com/U2-xml> <! -- CUSTOMER AND TAPE MAPPING FILE --> <U2xml:mapping file = TAPES.F field = CAT_NAME map-to= Cat_name TYPE= MV /> <U2xml:mapping file = CUSTOMER.F field = TAPES_RENTED map-to=Tapes_rented TYPE=MV /> <U2xml:mapping file = CUSTOMER.F field = DATE_OUT TYPE=MV /> <U2xml:mapping file = CUSTOMER.F field = DATE_DUE TYPE=MV /> </U2xml-mapping>
To use this mapping file in the SELECT statement, specify the XMLMAPPING keyword, as shown in the following example:
5-57
Note: You must surround the name of the mapping file in single quotation marks.
02 SELECT CUSTOMER.F.NAME, TAPES.F.NAME, CAT_NAME, DATE_OUT, DATE_DUE FROM CUSTOMER.F, TAPES.F WHERE TAPES_RENTED = TAPES.F.@ID ORDER BY CUSTOMER.F.NAME TOXML XMLMAPPING 'CUST.TAPE.MAP';
<?xml version="1.0"?> <ROOT> <CUSTOMER.F_record NAME = "Barrie, Dick"> <TAPES.F NAME = "Citizen Kane"> <TAPES.F_CATS_MV CAT_NAME = "Old Classic"/> <TAPES.F_CATS_MV CAT_NAME = "Drama"/> <TAPES.F_CATS_MV CAT_NAME = "Horror"/> </TAPES.F> <TAPES.F_CATS-MV DATE_OUT = "03/29/94" DATE_DUE </CUSTOMER.F_record> <CUSTOMER.F_record NAME = "Best, George"> <TAPES.F NAME = "Love Story"> <TAPES.F_CATS_MV CAT_NAME = "Romance"/> <TAPES.F_CATS_MV CAT_NAME = "Tear Jerker"/> </TAPES.F> <TAPES.F_CATS-MV DATE_OUT = "03/29/94" DATE_DUE </CUSTOMER.F_record> <CUSTOMER.F_record NAME = "Bowie, David"> <TAPES.F NAME = "The Stalker"> <TAPES.F_CATS_MV CAT_NAME = "Avant Garde"/> <TAPES.F_CATS_MV CAT_NAME = "Science Fiction"/> </TAPES.F> <TAPES.F_CATS-MV DATE_OUT = "04/15/94" DATE_DUE </CUSTOMER.F_record> <CUSTOMER.F_record NAME = "Chase, Carl"> <TAPES.F NAME = "'Round Midnight"> <TAPES.F_CATS_MV CAT_NAME = "Musical"/> <TAPES.F_CATS_MV CAT_NAME = "Drama"/> </TAPES.F> <TAPES.F_CATS-MV DATE_OUT = "04/20/94" DATE_DUE <TAPES.F_CATS-MV DATE_OUT = "04/20/94" DATE_DUE <TAPES.F_CATS-MV DATE_OUT = "04/21/94" DATE_DUE </CUSTOMER.F_record> <CUSTOMER.F_record NAME = "Chase, Carl"> <TAPES.F NAME = "American Graffiti "> <TAPES.F_CATS_MV CAT_NAME = "Comedy"/> <TAPES.F_CATS_MV CAT_NAME = "Childrens Movie"/> </TAPES.F> <TAPES.F_CATS-MV DATE_OUT = "04/20/94" DATE_DUE <TAPES.F_CATS-MV DATE_OUT = "04/20/94" DATE_DUE <TAPES.F_CATS-MV DATE_OUT = "04/21/94" DATE_DUE </CUSTOMER.F_record> <CUSTOMER.F_record NAME = "Chase, Carl"> <TAPES.F NAME = "Flash Gordon"> <TAPES.F_CATS_MV CAT_NAME = "Science Fiction"/> <TAPES.F_CATS_MV CAT_NAME = "Childrens Movie"/> </TAPES.F>
= "03/31/94"/>
= "03/31/94"/>
= "04/17/94"/>
= "04/22/94"/> = "04/22/94"/> = "04/23/94"/>
= "04/22/94"/> = "04/22/94"/> = "04/23/94"/>
5-58
<TAPES.F_CATS-MV DATE_OUT = "04/20/94" DATE_DUE <TAPES.F_CATS-MV DATE_OUT = "04/20/94" DATE_DUE <TAPES.F_CATS-MV DATE_OUT = "04/21/94" DATE_DUE </CUSTOMER.F_record> <CUSTOMER.F_record NAME = "Faber, Harry"> <TAPES.F NAME = "To Kill A Mockingbird"> <TAPES.F_CATS_MV CAT_NAME = "Horror"/> <TAPES.F_CATS_MV CAT_NAME = "Political"/> <TAPES.F_CATS_MV CAT_NAME = "Drama"/> </TAPES.F> <TAPES.F_CATS-MV DATE_OUT = "04/19/94" DATE_DUE </CUSTOMER.F_record> <CUSTOMER.F_record NAME = "Fischer, Carrie"> <TAPES.F NAME = "Girl Friday"> <TAPES.F_CATS_MV CAT_NAME = "Comedy"/> <TAPES.F_CATS_MV CAT_NAME = "Old Classic"/> </TAPES.F> <TAPES.F_CATS-MV DATE_OUT = "04/23/94" DATE_DUE </CUSTOMER.F_record> <CUSTOMER.F_record NAME = "James, Bob"> <TAPES.F NAME = "Blue Velvet"> <TAPES.F_CATS_MV CAT_NAME = "Horror"/> <TAPES.F_CATS_MV CAT_NAME = "Drama"/> <TAPES.F_CATS_MV CAT_NAME = "Avant Garde"/> </TAPES.F> <TAPES.F_CATS-MV DATE_OUT = "04/25/94" DATE_DUE </CUSTOMER.F_record> <CUSTOMER.F_record NAME = "Jamieson, Dale"> <TAPES.F NAME = "2001"> <TAPES.F_CATS_MV CAT_NAME = "Science Fiction"/> <TAPES.F_CATS_MV CAT_NAME = "Drama"/> </TAPES.F> <TAPES.F_CATS-MV DATE_OUT = "04/24/94" DATE_DUE </CUSTOMER.F_record> <CUSTOMER.F_record NAME = "Jones, Bob"> <TAPES.F NAME = "Z"> <TAPES.F_CATS_MV CAT_NAME = "Political"/> <TAPES.F_CATS_MV CAT_NAME = "Drama"/> </TAPES.F> <TAPES.F_CATS-MV DATE_OUT = "04/24/94" DATE_DUE </CUSTOMER.F_record> <CUSTOMER.F_record NAME = "Jones, Freddie"> <TAPES.F NAME = "Help"> <TAPES.F_CATS_MV CAT_NAME = "Childrens Movie"/> <TAPES.F_CATS_MV CAT_NAME = "Comedy"/> <TAPES.F_CATS_MV CAT_NAME = "Musical"/> </TAPES.F> <TAPES.F_CATS-MV DATE_OUT = "04/23/94" DATE_DUE </CUSTOMER.F_record> <CUSTOMER.F_record NAME = "Jones, Mable"> <TAPES.F NAME = "Psycho"> <TAPES.F_CATS_MV CAT_NAME = "Horror"/> <TAPES.F_CATS_MV CAT_NAME = "Drama"/> </TAPES.F>
= "04/22/94"/> = "04/22/94"/> = "04/23/94"/>
= "04/21/94"/>
= "04/25/94"/>
= "04/27/94"/>
= "04/26/94"/>
= "04/26/94"/>
= "04/25/94"/>
5-59
<TAPES.F_CATS-MV DATE_OUT = "04/23/94" DATE_DUE <TAPES.F_CATS-MV DATE_OUT = "04/25/94" DATE_DUE </CUSTOMER.F_record> <CUSTOMER.F_record NAME = "Jones, Mable"> <TAPES.F NAME = "Gone With The Wind"> <TAPES.F_CATS_MV CAT_NAME = "Romance"/> </TAPES.F> <TAPES.F_CATS-MV DATE_OUT = "04/23/94" DATE_DUE <TAPES.F_CATS-MV DATE_OUT = "04/25/94" DATE_DUE </CUSTOMER.F_record> <CUSTOMER.F_record NAME = "Jones, Samuel"> <TAPES.F NAME = "'Round Midnight"> <TAPES.F_CATS_MV CAT_NAME = "Musical"/> <TAPES.F_CATS_MV CAT_NAME = "Drama"/> </TAPES.F> <TAPES.F_CATS-MV DATE_OUT = "04/24/94" DATE_DUE <TAPES.F_CATS-MV DATE_OUT = "04/25/94" DATE_DUE </CUSTOMER.F_record> <CUSTOMER.F_record NAME = "Jones, Samuel"> <TAPES.F NAME = "Flash Gordon"> <TAPES.F_CATS_MV CAT_NAME = "Science Fiction"/> <TAPES.F_CATS_MV CAT_NAME = "Childrens Movie"/> </TAPES.F> <TAPES.F_CATS-MV DATE_OUT = "04/24/94" DATE_DUE <TAPES.F_CATS-MV DATE_OUT = "04/25/94" DATE_DUE </CUSTOMER.F_record> <CUSTOMER.F_record NAME = "Partner, Bonnie"> <TAPES.F NAME = "Tammy"> <TAPES.F_CATS_MV CAT_NAME = "Romance"/> </TAPES.F> <TAPES.F_CATS-MV DATE_OUT = "01/01/94" DATE_DUE <TAPES.F_CATS-MV DATE_OUT = "01/03/94" DATE_DUE </CUSTOMER.F_record> <CUSTOMER.F_record NAME = "Partner, Bonnie"> <TAPES.F NAME = "Love Story"> <TAPES.F_CATS_MV CAT_NAME = "Romance"/> <TAPES.F_CATS_MV CAT_NAME = "Tear Jerker"/> </TAPES.F> <TAPES.F_CATS-MV DATE_OUT = "01/01/94" DATE_DUE <TAPES.F_CATS-MV DATE_OUT = "01/03/94" DATE_DUE </CUSTOMER.F_record> <CUSTOMER.F_record NAME = "Smith, Harry"> <TAPES.F NAME = "Journey Abroad"> <TAPES.F_CATS_MV CAT_NAME = "B - Movie"/> </TAPES.F> <TAPES.F_CATS-MV DATE_OUT = "04/24/94" DATE_DUE <TAPES.F_CATS-MV DATE_OUT = "04/23/94" DATE_DUE <TAPES.F_CATS-MV DATE_OUT = "04/24/94" DATE_DUE </CUSTOMER.F_record> <CUSTOMER.F_record NAME = "Smith, Harry"> <TAPES.F NAME = "Catch 22"> <TAPES.F_CATS_MV CAT_NAME = "Comedy"/> <TAPES.F_CATS_MV CAT_NAME = "Avant Garde"/> </TAPES.F>
= "04/25/94"/> = "04/27/94"/>
= "04/25/94"/> = "04/27/94"/>
= "04/26/94"/> = "04/27/94"/>
= "04/26/94"/> = "04/27/94"/>
= "01/03/94"/> = "01/05/94"/>
= "01/03/94"/> = "01/05/94"/>
= "04/26/94"/> = "04/25/94"/> = "04/26/94"/>
5-60
<TAPES.F_CATS-MV DATE_OUT = "04/24/94" DATE_DUE <TAPES.F_CATS-MV DATE_OUT = "04/23/94" DATE_DUE <TAPES.F_CATS-MV DATE_OUT = "04/24/94" DATE_DUE </CUSTOMER.F_record> <CUSTOMER.F_record NAME = "Smith, Harry"> <TAPES.F NAME = "Blue Velvet"> <TAPES.F_CATS_MV CAT_NAME = "Horror"/> <TAPES.F_CATS_MV CAT_NAME = "Drama"/> <TAPES.F_CATS_MV CAT_NAME = "Avant Garde"/> </TAPES.F> <TAPES.F_CATS-MV DATE_OUT = "04/24/94" DATE_DUE <TAPES.F_CATS-MV DATE_OUT = "04/23/94" DATE_DUE <TAPES.F_CATS-MV DATE_OUT = "04/24/94" DATE_DUE </CUSTOMER.F_record> </ROOT> >
= "04/26/94"/> = "04/25/94"/> = "04/26/94"/>
= "04/26/94"/> = "04/25/94"/> = "04/26/94"/>
5-61
UniVerse BASIC Example

The following example illustrates an UniVerse BASIC program that generates an XML document:
CMD = "LIST STUDENT LNAME SEMESTER COURSE_NBR '424325656' TOXML XMLMAPPING student.map" STATUS = XMLEXECUTE(CMD,myvar) PRINT "XMLEXECUTE finished" PRINT myvar END
The next example illustrates the output from the program described in the previous example:
>RUN ENGTESTS XMLEXECUTE XMLEXECUTE finished <STUDENT_record> <_ID>424325656</_ID> <LNAME>Martin</LNAME> <SEMESTER>SP94</SEMESTER> <COURSE_NBR>PY100</COURSE_NBR> <COURSE_NBR>PE100</COURSE_NBR> </STUDENT_record>
The following example illustrates the root element of the student.map file:
<U2 root="STUDENT" schema = "type" hidemv="yes" hidems="yes" hideroot="1" />
5-62
Chapter
The Simple Object Access Protocol

SOAP Components . . . . . . . The SOAP API for BASIC . . . . . . Sending a SOAP Request. . . . . . SOAP API for BASIC Programmatic Interfaces SOAPSetDefault . . . . . . . . SOAPGetDefault . . . . . . . . SOAPCreateRequest . . . . . . . SOAPSetParameters . . . . . . . SOAPSetRequestHeader . . . . . . SOAPSetRequestBody . . . . . . SOAPSetRequestContent. . . . . . SOAPRequestWrite . . . . . . . SOAPSubmitRequest . . . . . . . SOAPGetResponseHeader . . . . . SOAPGetFault . . . . . . . . . protocolLogging . . . . . . . . SOAP API for BASIC Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-2 6-4 6-4 6-5 6-5 6-6 6-7 6-10 6-12 6-13 6-14 6-15 6-17 6-18 6-19 6-21 6-23
The Simple Object Access Protocol (SOAP) is an XML-based protocol for exchanging structured information in a distributed environment. It allows the sender and receiver of XML documents over the web to support a common data transfer protocol, and is language and platform independent. Its most common method of operation is as a means of issuing Remote Procedure Calls across a network. However, it can also be used in other manners, such as the posting of XML documents to servers for processing.
SOAP Components
A SOAP message contains three major blocks, the envelope, the header, and the body. Envelope Defines the start and end of a SOAP message. Header Carries application-defined information associated with the message, such as security tokens, message correlation mechanisms, and transaction identifiers. A header is optional in a SOAP message. Body One or more body blocks containing the SOAP message itself.
The Envelope
The envelope is the outermost element in a SOAP message, and is the root element of the message. Use the env namespace prefix to specify the envelope, and the Envelope element. The envelope specifies the version of SOAP you are using. If you are using a v1.1-compliant SOAP processor, it generates a fault if it receives a message containing a v1.2 envelope namespace. The envelope element namespace for the difference SOAP versions follows:
v1.1 <SOAP-ENV:Envelope xmlns:SOAPENV=http://www.w3.org/2001/12/soap-envelope v1.1 SOAP-ENV:http://schemas.xmlsoap.org/soap/envelope/
You can also specify an encoding namespace in the SOAP envelope.
SOAP Header
The header is an optional part of a SOAP message, and is the first immediate child element of the envelope. You can have multiple SOAP headers.
6-2
SOAP headers are used to include additional functionality, such as security, and other attributes associated with the message. A SOAP header can have attributes for intermediary processing, such as a user name and password, that may not be processed at the final SOAP processor destination. You can include a the mustUnderstand attribute in a SOAP header to require the receiver of the message to understand a header. If you include the mustUnderstand attribute with a value of true, the SOAP node you target must process the SOAP block using the requirements defined in the header, or not process the message and return an error code.
SOAP Body
The SOAP body contains the XML data defined by the application. You must define the SOAP body within the envelope, and it must appear after any SOAP headers. For complete information about SOAP, see the W3C technical publications website at http://www.w3.org/TR.
6-3 Simple Object Access Protocol (SOAP) API For UniVerse BASIC
The SOAP API for BASIC

The SOAP API for BASIC provides the capability of issuing requests to SOAP servers from UniVerse BASIC through the standard HTTP protocol. The SOAP API for BASIC makes use of UniVerse CallHTTP to send and receive SOAP messages. SOAP responses retrieved from a SOAP server can be parsed via the XML API for UniVerse BASIC.
Sending a SOAP Request

Sending a SOAP message to a server from the SOAP API for BASIC typically involves some variation of the following procedure:
1.
Set Protocol Defaults You must define the SOAP default settings, including the version of SOAP you are using. Use SOAPSetDefault to define the SOAP version, and SetHTTPDefault to define any HTTP headers you may need. Create the SOAP Request Use the SOAPCreateRequest function to define the SOAP request. Set the SOAP Request Content Use one of the following functions to set the SOAP request content: SOAPSetRequestHeader You can use this function to set any SOAP header blocks for the SOAP request. SOAPSetParameters Sets the SOAP body according to the RPC style of communication, based on the input parameters to the function, SOAPSetRequestBody This function is similar to SOAPSetParameters, but you can also use this function for non-RPC styles of communication, and add multiple body elements to the SOAP request. SOAPSetRequestContent Sets the entire SOAP message content, either from an input string or from the contents of a file.
2. 3.
4.
Submit the SOAP Request Use the SOAPSubmitRequest to submit the SOAP request. The output parameters respData and respHeaders contain the response from the SOAP server. You can use the XML API for UniVerse BASIC to parse the resulting SOAP response.
6-4
SOAP API for BASIC Programmatic Interfaces

This section describes the SOAP API for UniVerse BASIC functions.
SOAPSetDefault
Syntax
SOAPSetDefault(option, value)
Description
Use the SOAPSetDefault function to define default SOAP settings, such as the SOAP version. By default, the SOAP version is 1.1, although you can specify version 1.2. For SOAP version 1.1, the namespace prefixes "env" and "enc" are associated with the SOAP namespace names http://schemas.xmlsoap.org/soap/envelope/ and http://schemas.xmlsoap.org/soap/encoding/ respectively. The namespace prefixed "xsi" and "xsd" are associated with the namespace names http://www.w3.org/1999/XMLSchema-instance and http://www.w3.org/1999/XMLSchema respectively. The SOAP version can be set to 1.2 to support the newer SOAP 1.2 protocol. The namespace prefixes "env" and "enc" are associated with the SOAP namespace names "http://www.w3.org/2001/12/soap-envelope" and "http://www.w3.org/2001/12/soap-encoding" respectively. The namespace prefixes "xsd" and "xsi" will be associated with the namespace names "http://www.w3.org/2001/XMLSchema" and "http://www.w3.org/2001/XMLSchema-instance" respectively. Note: All defaults set by SOAPSetDefault remain in effect until the end of the current UniVerse session. If you do not want the setting to affect subsequent programs, clear it before exiting the current program. Along with SOAPSetDefault, you can use the CallHTTP function setHTTPDefault to set HTTP-specific settings or headers, if the HTTP default settings are not sufficient.
Parameters
Parameter option value Description A string containing an option name. UniVerse currently only supports the VERSION option. [IN] A string containing the appropriate option value. For the VERSION option, the string should be 1.0, 1.1, or 1.2. [IN] SOAPSetDefault Parameters
Return Codes
The return code indicating success or failure. The following table describes the value of each return code.
Return Code 0 1 2
Description Function completed successfully. Invalid option (currently, UniVerse only supports VERSION). Invalid value. If you do not specify a value, UniVerse uses the default of 1.1.
You can also use the UniVerse BASIC STATUS() function to obtain the return status from the function.
SOAPGetDefault
Syntax
SOAPGetDefault(option, value)
6-6
Description
The SOAPGetDefault function retrieves default SOAP settings, such as the SOAP version.
Parameters
Parameter option value Description A string containing an option name. UniVerse currently only supports the VERSION option. [IN] A string returning the option value. [OUT] SOAPGetDefault Parameters
Return Codes
Return Code Description 0 1 Function completed successfully. Invalid option (currently, UniVerse only supports the VERSION option). SOAPGetDefault Return Codes
SOAPCreateRequest
Syntax
SOAPCreateRequest(URL, soapAction, Request)
Description
The SOAPCreateRequest creates a SOAP request and returns a handle to the request.
Parameters
Parameter URL Description A string containing the URL where the web service is located. UniVerse sends the SOAP request to this URL. For information about the format of the URL, see URL Format. [IN] A string UniVerse uses as the SOAPAction HTTP header for this SOAP request. [IN] The returned handle to the SOAP request. You can use this handle can be used in subsequent calls to the SOAP API for UniVerse BASIC. [OUT] SOAPCreateRequest Parameters
soapAction Request
URL Format
The URL you specify must follow the syntax defined in RFS 1738. The general format is: http://<host>:<port>/path>?<searchpart> The following table describes each parameter of the syntax.
Parameter host port Description Either a name string or an IP address of the host system. The port number to which you want to connect. If you do not specify port, UniVerse defaults to 80. Omit the preceding colon if you do not specify this parameter. Defines the file you want to retrieve on the web server. If you do not specify path, UniVerse defaults to the home page. Use searchpart to send additional information to a web server. URL Parameters 6-8
path searchpart
Note: If the URL you define contains a searchpart, you must define it in its encoded format. For example, a space is converted to +, and other nonalphanumeric characters are converted to %HH format. You do not need to specify the host and path parameters in their encoded formats. UniVerse BASIC encodes these parameters prior to communicating with the web server.
Return Code
Return Code 0 1 2 Description Function complete successfully. Invalid URL syntax. Invalid HTTP method (indicates the POST method is not supported by the HTTP server). SOAPCreateRequest Return Codes
Example
The following code segment illustrates the SOAPCreateRequest function:
* Create the Request Ret = SoapCreateRequest(URL, SoapAction, SoapReq) IF Ret <> 0 THEN STOP "Error in SoapCreateRequest: " : Ret END . . .
SOAPSetParameters
Syntax
SOAPSetParameters(Request, URI, serviceName, paramArray)
Description
The SOAPSetParameters function sets up the SOAP request body, specifying a remote method to call along with the method's parameter list.
Parameters
Parameter Request namespace serviceName paramArray Description Handle to the request created with SOAPCreateRequest. [IN] A string is used as the namespace URI for the SOAP call. [IN] The name of the SOAP service. [IN] A dynamic array containing the method parameters for the SOAP call. Each method parameter consists of the following values: A parameter name A parameter value A parameter type (if type is omitted, xsd:string will be used. name, value, and type are separated by @VM. Additional parameters are separated by @AM, as shown in the following example: <param1Name>@VM<param1Value>@VM<param1Type>@AM <param2Name>@VM<param2Value>@VM<param2Type>...[IN] SOAPSetParameters Parameters
6-10
Return Codes
Return Code 0 1 Description Function completed successfully. Invalid request handle was passed to the function. SOAPSetParameters Return Codes
Example
As an example, the following inputs:
Input serviceName namespace paramArray Description getStockQuote http://host/#StockQuoteService symbol:@VM:IBM:@VM:xsd:string
set the SOAP body as follows:

<SOAP-ENV:Body> <ns1:getStockQuote xmlns:ns1="http://host/#StockQuoteService"> <symbol xsi:type="xsd:string">IBM</symbol> </ns1:getQuote> <SOAP-ENV:Body>
The following code example illustrates the SOAPSetParameters function:

* Set up the Request Body Ret = SoapSetParameters(SoapReq, NameSpace, Method, MethodParms) IF Ret <> 0 THEN STOP "Error in SoapSetParameters: " : Ret END
SOAPSetRequestHeader
Syntax
SOAPSetRequestHeader(Request, value)
Description
The SOAPSetRequestHeader sets up a SOAP request header. By default, there is no SOAP header.
Parameters
Parameter Request value Description Handle to the request created with SOAPCreateRequest. [IN] A dynamic array containing SOAP header blocks, for example: <header block>@AM<header block>...[IN] SOAPSetRequestHeader Parameters
Return Codes
Return Code 0 1
Description Function completed successfully. Invalid request handle.
SOAPSetRequestHeader Return Codes
6-12
SOAPSetRequestBody
Syntax
SOAPSetRequestBody(Request, value)
Description
The SOAPSetRequestBody function sets up a SOAP request body directly, as opposed to having it constructed via the SOAPSetParameters function. With this function, you can also attach multiple body blocks to the SOAP request. Each SOAP request should include at least one body block.
Parameters
Parameter Request value Description Handle to the request created with SOAPCreateRequest. [IN] A dynamic array containing SOAP body blocks, for example: <body block>@AM<body block>... [IN] SOAPSetRequestBody Parameters
Return Codes
Return Code 0 1
Description Function completed successfully. Invalid request handle.
SOAPSetRequestBody Return Codes
6-13
Simple Object Access Protocol (SOAP) API For UniVerse BASIC
SOAPSetRequestContent
Syntax
SOAPSetRequestContent(Request, reqDoc, docTypeFlag)
Description
The SOAPSetRequestContent function sets the entire SOAP request's content from an input string or from a file.
Parameters
Parameter Request reqDoc docTypeFlag Description Handle to the request created with SOAPCreateRequest. [IN] The input document to use as the SOAP request content. [IN] A flag indicating whether reqDoc is a string holding the actual content, or the path to a file holding the content. 0 reqDoc is a file holding the request content. 1 reqDoc is a string holding the request content. [IN] SOAPSetRequestContent Parameters
6-14
Return Codes
The return code indicating success or failure. The following table describes the status of each return code.
Return Code 0 1 2 3 Description Function completed successfully. Invalid request handle. Unable to open the file named by reqDoc. Unable to read the file named by reqDoc. SOAPSetRequestContent Return Codes
SOAPRequestWrite
Syntax
SOAPRequestWrite(Request, reqDoc, docTypeFlag)
Description
The SOAPRequestWrite function outputs the SOAP request, in XML format, to a string or to a file.
6-15
Parameters
Parameter Request reqDoc Description Handle to the request created with SOAPCreateRequest. [IN] Depending on docTypeFlag, either an output string containing the SOAP request content, or a path to a file where the SOAP request content will be written. [OUT] A flag indicating whether reqDoc is an output string that is to hold the request content, or a path to a file where the SOAP request content will be written. 0 reqDoc is a file where the request content will be written upon successful completion. 1 reqDoc is a string that will hold the request upon successful completion. [IN] SOAPRequestWrite Parameters
docTypeFlag
Return Codes
Return Code Description 0 1 2 3 Function completed successfully. Invalid request handle. Unable to open the file named by reqDoc. Unable to write to the file named by reqDoc. SOAPRequestWrite Return Codes
6-16
SOAPSubmitRequest
Syntax
SOAPSubmitRequest(Request, timeout, respHeaders, respData, soapStatus)
Description
The SOAPSubmitRequest function submits a request and gets the response. Internally, SOAPSubmitRequest utilizes CallHTTP's submitRequest() function to send the SOAP message. The soapStatus variable holds the status from the underlying CallHTTP function. If an error occurs on the SOAP server while processing the request, soapStatus will indicate an HTTP 500 "Internal Server Error", and respData will be a SOAP Fault message indicating the server-side processing error.
Parameters
Parameter Request timeout respHeaders respData soapStatus Description Handle to the request created with SOAPCreateRequest. [IN] Timeout, in milliseconds, to wait for a response. [IN] Dynamic array of HTTP response headers and their associated values. [OUT] The SOAP response message. [OUT] Dynamic array containing status code and explanatory text. [OUT] SOAPSubmitRequest Parameters
6-17
Return Codes
Return Code 0 1 2 3 4 Description Function completed successfully. Invalid request handle. Request timed out. Network error occurred. Other error occurred. SOAPSubmitRequest Return Codes
Example
The following code sample illustrates the SOAPSubmitRequest function:
* Submit the Request Ret = SoapSubmitRequest(SoapReq, Timeout, RespHeaders, RespData, SoapStatus) IF Ret <> 0 THEN STOP "Error in SoapSubmitRequest: " : Ret END PRINT "Response status : " : SoapStatus PRINT "Response headers: " : RespHeaders PRINT "Response data : " : RespData . . .
SOAPGetResponseHeader
Syntax
SOAPGetResponseHeader(Request, headerName, headerValue)
6-18
Description
The SOAPGetResponseHeader function gets a specific response header after issuing a SOAP request.
Parameters
Parameter Request headerName headerValue Description Handle to the request created with SOAPCreateRequest. [IN] The header name whose value is being queried. [IN] The header value, if present in the response, or empty string if not (in which case the return status of the function is 2). [OUT] SOAPGetResponseHeader Parameters
Return Codes
Return Code 0 1 2 Description Function completed successfully. Invalid request handle. Header not found in set of response headers. SOAPGetResponseHeader Return Codes
You can also use the UniVerse BASIC STATUS() function o obtain the return status from the function.
SOAPGetFault
Syntax
SOAPGetFault(respData, soapFault)
Description
If the SOAPSubmitRequest function receives a SOAP Fault, the SOAPGetFault function parses the response data from SOAPSubmitRequest into a dynamic array of SOAP Fault components.
Parameters
Parameter respData soapFault Description Response data from SOAPSubmitRequest after receiving a SOAP fault. [IN] Dynamic array consisting of Fault Code, Fault String, and optional Fault Detail, for example: <faultcode>@AM<faultstring>@AM<faultdetail>@AM<faultactor> Fault code values are XML-qualified names, consisting of: VersionMismatch MustUnderstand DTDNotSupported DataEncoding Unknown Sender Receiver SOAPGetFault Parameters
Return Codes
Return Code 0 1 2 Description Function completed successfully. Invalid response data, possibly not a valid XML document. SOAP Fault not found in response data. SOAPGetFault Return Codes 6-20
protocolLogging
Syntax
protocolLogging(logFile, logAction, logLevel)
Description
The protocolLogging function starts or stops logging. By default, no logging takes place. The function parses the response data from SOAPSubmitRequest, after receiving a SOAP Fault, into a dynamic array of SOAP Fault components.
Parameters
Parameter logFile logAction logLevel Description The name of the log file [IN] Flag (values ON or OFF) indicating whether logging should be turned on or off. [IN] Controls the level of log detail. 0 No logging takes place. 1 Only errors are logged. 3 Warnings and errors are logged. 7 All SOAP actions are logged. [IN] protocolLogging Parameters
6-21
Return Codes
Return Code 0 1 Description Function completed successfully. An error occurred starting or stopping logging. protocol Logging Return Codes
6-22
SOAP API for BASIC Example

* * Example of Sending a SOAP Request from BASIC * URL SoapAction NameSpace Method MethodParms Timeout = = = = = = "http://u2.ibm.com/webservices/AddressBookService" "http://u2.ibm.com/AddressBook#getAddressFromName" "http://u2.ibm.com/AddressBook" "getAddressFromName" "name":@VM:"John Doe":@VM:"xsd:string" 30000
* Create the Request Ret = SoapCreateRequest(URL, SoapAction, SoapReq) IF Ret <> 0 THEN STOP "Error in SoapCreateRequest: " : Ret END * Set up the Request Body Ret = SoapSetParameters(SoapReq, NameSpace, Method, MethodParms) IF Ret <> 0 THEN STOP "Error in SoapSetParameters: " : Ret END * Submit the Request Ret = SoapSubmitRequest(SoapReq, Timeout, RespHeaders, RespData, SoapStatus) IF Ret <> 0 THEN STOP "Error in SoapSubmitRequest: " : Ret END PRINT "Response status : " : SoapStatus PRINT "Response headers: " : RespHeaders PRINT "Response data : " : RespData
6-23
Chapter
The Document Object Model
XPath and the Document Object Model . . A Sample XML document . . . . . Opening and Closing a DOM Document . Navigating the DOM Tree . . . . . Building DOM Trees from Scratch . . . Transforming XML documents . . . . XML for BASIC API Programmatic Interfaces XDOMOpen. . . . . . . . . . XDOMCreateNode . . . . . . . XDOMCreateRoot . . . . . . . . XDOMWrite. . . . . . . . . . XDOMClose . . . . . . . . . XDOMValidate . . . . . . . . . XDOMLocate . . . . . . . . . XDOMLocateNode . . . . . . . XDOMRemove . . . . . . . . . XDOMAppend . . . . . . . . . XDOMInsert . . . . . . . . . XDOMReplace . . . . . . . . . XDOMAddChild . . . . . . . . XDOMClone . . . . . . . . . XDOMTransform . . . . . . . . XDOMGetNodeValue . . . . . . . XDOMGetNodeType . . . . . . . XDOMGetAttribute . . . . . . . XDOMGetOwnerDocument . . . . . XDOMGetUserData . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . .
8-4 8-4 8-4 8-5 8-6 8-8 8-12 8-12 8-13 8-14 8-15 8-16 8-17 8-19 8-20 8-26 8-27 8-29 8-30 8-32 8-33 8-34 8-36 8-37 8-38 8-39 8-40
Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta
XDOMSetNodeValue . . XDOMSetUserData . . XMLGetError . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . . . . .
. . .
8-41 8-42 8-43
7-2 UniVerse Basic Extensions
The Document Object Model (DOM) provides a standard way for you to manipulate XML documents. You can use the DOM API to delete, remove, and update an XML document, as well as create new XML documents. The DOM represents a document as a tree of Nodes. Each node has a parent (except for the "root" node), and optional children. The DOM provides functions to traverse and manipulate these nodes. Another technology, XPath, (also supported in the XML for UniVerse BASIC API) provides the ability to locate nodes in the DOM based on search criteria. The DOM defines different types of nodes, with the Element type being the most commonly used: Document DocumentFragment DocumentType EntityReference Element Attr ProcessingInstruction Comment Text CDATASection Entity Notation
7-2
XPath and the Document Object Model

XPath is a language that gives the ability to address specific parts of an XML document. It allows you to execute node searches through expressions such as "find the node whose name is LASTNAME and whose value starts with Smith and is a child node of Employee. The XML for UniVerse BASIC API provides support for XPath by allowing you to specify XPath search strings in some of its API calls. For example, XDOMLocate takes an Xpath string to locate a particular node in the DOM tree. XDOMRemove also takes an Xpath search string to evaluate which node(s) to remove.
A Sample XML document

The following document, "sample.xml," will be used to help illustrate usage of the XML for UniVerse BASIC API. It is a simple address book with two entries:
<?xml version = "1.0"?> <ADDRBOOK> <ENTRY ID="id1"> <NAME>Name One</NAME> <ADDRESS>101 Some Way</ADDRESS> <PHONENUM DESC="Work">303-111-1111</PHONENUM> < PHONENUM DESC="Fax">303-111-2222</PHONENUM> <PHONENUM DESC="Pager">303-111-3333</PHONENUM> <EMAIL>name.one@some.com</EMAIL> </ENTRY> <ENTRY ID="id2"> <NAME>Name Two</NAME> <ADDRESS>202 Some Way</ADDRESS> <PHONENUM DESC="Work">303-222-1111</PHONENUM> <PHONENUM DESC="Fax">303-222-2222</PHONENUM> <PHONENUM DESC="Home">303-222-3333</PHONENUM> <EMAIL>name.two@some.com</EMAIL> </ENTRY> </ADDRBOOK>
Opening and Closing a DOM Document

Use XDOMOpen to load an XML document and build a DOM tree in memory.
XDOMOpen("sample.xml", XML.FROM.FILE, mydom)
If the first parameter is the XML document itself, the second parameter is XML.FROM.STRING. You can reference the DOM handle, mydom, later in other XML for UniVerse BASIC API calls. When finished with an XML document, use XDOMClose to destroy the DOM tree in memory:
XDOMClose(mydom)
Navigating the DOM Tree

Use XDOMLocate to locate the context node.
XDOMLocate(xmlHandle, xpathString, nsMap, nodeHandle)
For example,
XDOMLocate(mydom, "/ADDRBOOK", "", myctx)
puts the element ADDRBOOK in variable myctx. You can use the context handle, which is also a node handle and more generically an xml handle, in other API calls later. Use XDOMLocateNode to navigate the DOM tree without bothering with XPath:
XDOMLocateNode(nodeHandle, direction, childIndex, nodeType, newNodeHandle)
For example,
XDOMLocateNode(mydom, XDOM.CHILD, XDOM.FIRST.CHILD, XDOM.ELEMENT.NODE, thefirst)
puts the ADDRBOOK element, which is the first child of the root in handle thefirst. And,
XDOMLocateNode(thefirst, XDOM.CHILD, 2, XDOM.ELEMENT.NODE, entrynode2)
puts the second ENTRY element in handle entrynode2. Then,

XDOMLocateNode(entrynode2, XDOM.PREV.SIBLING, 0, XDOM.ELEMENT.NODE, entrynode1)
7-4
puts the first ENTRY element in handle entrynode1.
Building DOM Trees from Scratch

There are two API calls available to build a DOM tree from scratch:
XDOMCreateRoot(domHandle) XDOMCreateNode(xmlHandle, nodeName, nodeValue, nodeType, nodeHandle)
XDOMCreateRoot creates a DOM tree with one root, whose type is DOCUMENT. XDOMCreateNode creates a node that bears the name, value and type you specify with the parameters. For example,
XDOMCreateRoot(newdom)
creates this tree in memory:
And
XDOMCreateNode(newdom, "Website","", XDOM.ELEMENT.NODE, newnode)
newdom
creates a new element node with name Website, which you can reference through the handle newnode.
newnode
WEBSITE
Now we create a text node

XDOMCreateNode(newnode, "", "www.anyname.com", XDOM.TEXT.NODE, newtext) XDOMAddChild(newnode, "/Website", "", newtext, XDOM.NODUP)
The subtree becomes:
newnode
WEBSITE newtext
www.anyname.com
7-6
Transforming XML documents

Use XDOMTransform to transform an XML document via an XSL document. For example, using the style sheet defined in the following example, "sample.xsl":
<?xml version="1.0"?> <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0"> <xsl:output method='html' indent='yes'/> <!-Template 1 --> <xsl:template match="/"> <HTML><HEAD><TITLE>Address Book</TITLE></HEAD> <BODY> <H1>Address Book</H1> <xsl:apply-templates/> </BODY> </HTML> </xsl:template> <!-Template 2 --> <xsl:template match="ENTRY"> <TABLE> <TR> <TD COLSPAN='2'> Contact: <xsl:value-of select='NAME'/> (ID: <xsl:value-of select='@ID'/>) </TD> </TR> <xsl:apply-templates select='ADDRESS|PHONENUM|EMAIL'/> </TABLE> <xsl:if test='not(position()=last())'><HR/></xsl:if> </xsl:template> <!-Template 3 --> <xsl:template match="ADDRESS"> <TR><TD>Address</TD><TD><xsl:apply-templates/></TD></TR> </xsl:template> <!-Template 4 --> <xsl:template match="PHONENUM"> <TR> <TD><xsl:value-of select='@DESC'/> Phone Number</TD> <TD><xsl:apply-templates/></TD> </TR> </xsl:template> <!-Template 5 --> <xsl:template match="EMAIL"> <TR><TD>E-mail Address</TD><TD><xsl:apply-
templates/></TD></TR> </xsl:template> </xsl:stylesheet>
The XML for UniVerse BASIC API function XDOMTransform can transform the sample Address Book DOM document (referenced by mydom) into a new DOM document using the following command:
XDOMTransform(mydom, "sample.xsl", XML.FROM.FILE, newdom)
7-8
The handle newdom will point to the transformed document, which will be:
<HTML> <HEAD> <META http-equiv="Content-Type" content="text/html; charset=UTF8"> <TITLE>Address Book</TITLE> </HEAD> <BODY> <H1>Address Book</H1> <TABLE> <TR> <TD COLSPAN="2"> Contact: Name One (ID: id1) </TD> </TR> <TR> <TD>Address</TD><TD>101 Some Way</TD> </TR> <TR> <TD>Work Phone Number</TD><TD>303-111-1111</TD> </TR> <TR> <TD>Fax Phone Number</TD><TD>303-111-2222</TD> </TR> <TR> <TD>Pager Phone Number</TD><TD>303-111-3333</TD> </TR> <TR> <TD>E-mail Address</TD><TD>name.one@some.com</TD> </TR> </TABLE> <HR> <TABLE> <TR> <TD COLSPAN="2"> Contact: Name Two (ID: id2) </TD> </TR> <TR> <TD>Address</TD><TD>202 Some Way</TD> </TR> <TR> <TD>Work Phone Number</TD><TD>303-222-1111</TD> </TR> <TR> <TD>Fax Phone Number</TD><TD>303-222-2222</TD> </TR> <TR> <TD>Home Phone Number</TD><TD>303-222-3333</TD> </TR> <TR> <TD>E-mail Address</TD><TD>name.two@some.com</TD>
</TR> </TABLE> <HR> </BODY> </HTML>
7-10
XML for BASIC API Programmatic Interfaces

This section describes the XML for UniVerse BASIC API functions.
XDOMOpen
Syntax
XDOMOpen(xmlDocument, docLocation, domHandle)
Description
The XDOMOpen function reads an xmlDocument and creates DOM structure. If the DTD is included in the document, UniVerse validates the document. The xmlDocument can be from a string or from a file, depending on the docLocation flag.
Parameters
Parameter xmlDocument docLocation Description The XML document. [IN] A flag to specify whether xmlDocument is a string holding the XML document, or it is a file containing the XML document. Valid values are: XML.FROM.FILE XML.FROM.STRING [IN] domHandle Handle to the opened DOM structure. [OUT] XDOMOpen Parameters
Return Codes
Return Code XML.SUCCESS XML.ERROR XML.INVALID.HANDLE Description Function completed successfully. An error occurred. Invalid DOM handle passed to the function.
XDOMOpen Return Codes
XDOMCreateNode
Syntax
XDOMCreateNode(xmlhandle, nodeName, nodeValue, nodeType, nodeHandle)
Description
The XDOMCreateNode function creates a new node, whose name and value and nodeName and nodeValue, respectively. Valid values for nodeType are: XDOM.ELEMENT.NODE XDOM.ATTR.NODE XDOM.TEXT.NODE XDOM.CDATA.NODE XDOM.ENTITY.REF.NODE XDOM.PROC.INST.NODE XDOM.COMMENT.NODE XDOM.DOC.NODE XDOM.DOC.TYPE.NODE XDOM.DOC.FRAG.NODE XDOM.NOTATION.NODE
7-12
XDOM.XML.DECL.NODE
Parameters
Parameter xmlHandle nodeName nodeValue nodeType nodeHandle Description Handle to the DOM structure. [IN] The name for the new node. [IN] The value for the new node. [IN] The type of the new node. [IN] The handle to the new node. [OUT] XDOMCreateNode Parameters
Return Codes
Return Code XML.SUCCESS XML.ERROR Description Function completed successfully. An error occurred.
XDOMCreateNode Return Codes
XDOMCreateRoot
Syntax
XDOMCreateRoot(domHandle)
7-13
Description
The XDOMCreateRoot function creates a new DOM structure with root only. You can use the result handle in other functions where a DOM handle or node handle is needed.
Parameters
The following table describes the parameter of the syntax.
Parameter domHandle Description Handle to the opened DOM structure. [OUT] XDOMCreateRoot Parameter
Return Codes
Return Code XML.SUCCESS XML.ERROR Description Function completed successfully. An error occurred.
XDOMCreateRoot Return Codes
XDOMWrite
Syntax
XDOMWrite(domHandle, xmlDocument, docLocation)
Description
The XDOMWrite function writes the DOM structure to xmlDocument. xmlDocument can be a string or a file, depending on the value of the docLocation flag.
7-14
Parameters
Parameter domHandle xmlDocument docLocation Description The handle to the opened DOM structure. [IN] The XML document [OUT] A flag to specify whether xmlDocument is an output string which should hold the XML document, or it is a file where the XML document should be written. Valid values are: XML.TO.FILE XML.TO.STRING [IN]
Return Codes
XDOMWrite Return Codes
XDOMClose
Syntax
XDOMClose(domHandle)
7-15
Description
The XDOMClose function frees the DOM structure.
Parameters
The following table describes the parameter of the syntax.
Parameter domHandle Description Handle to the DOM structure. [IN] XDOMClose Parameter
Return Codes
XDOMClose Return Codes
XDOMValidate
Syntax
XDOMValidate(xmlDocument, docLocation, schFile, schLocation)
Description
The XDOMValidate function validates the DOM document using the schema specified by schFile.
7-16
Parameters
Parameter xmlDocument docLocation Description The name of the XML document. [IN] A flag to specify whether xmlDocument is the document itself, or the document file name. Valid values are: XML.FROM.FILE (default) XML.FROM.STRING XML.FROM.DOM [IN] schFile schLocation The schema file. A flag to specify whether schFile is the schema itself, or the schema file name. Valid values are: XML.FROM.FILE (default) XML.FROM.STRING [IN] XDOMValidate Parameters
Return Codes
Return Code XML.SUCCESS XML.ERROR XML.INVALID.HANDLE Description Function completed successfully. An error occurred. An invalid DOM handle was passed to the function. XDOMValidate Return Codes
7-17
XDOMLocate
Syntax
XDOMLocate(xmlHandle, xpathString, nsMap, nodeHandle)
Description
The XDOMLocation function finds a starting point for relative XPath searching in context xmlHandle in the DOM structure. The xpathString should specify only one node; otherwise, this function returns an error.
Parameters
Parameter xmlHandle xpathString nsMAP Description A handle to the DOM structure. [IN] A string to specify the starting point. [IN] The map of namespaces which resolve the prefixes in the xpathString. The format is: xmlns=default_url xmlns:prefix1=prefix1_url xmlns:prefix2=prefix2_url For example: xmlns=http://myproject.mycompany.com xmlns:a_prefix=a.mycompany.com [IN] nodeHandle Handle to the found node. [OUT] XDOMLocate Parameters
7-18
Return Codes
Return Code XML.SUCCESS XML.ERROR XML.INVALID.HANDLE Description Function completed successfully. An error occurred. An invalid handle was returned to the function. XDOMLocate Return Codes
Note: In this document, xmlHandle is a generic type, it can be domHandle or nodeHandle. DomHandle stands for a whole document, while nodeHandle stands for a subtree. DomHandle is also a nodeHandle.
XDOMLocateNode
Syntax
XDOMLocateNode(nodeHandle, direction, childIndex, nodeType, newNodeHandle)
Description
The XDOMLocateNode function traverses from nodeHandle and gets the next node according to direction and childIndex.
7-19
Parameters
Parameter nodeHandle direction Description The handle to the starting node. [IN] Direction to traverse. Valid values are: XDOM.PREV.SIBLING XDOM.NEXT.SIBLING XDOM.NEXT.SIBLING.WITH.SAME.NAME XDOM.PREV.SIBLING.WITH.SAME.NAME XDOM.PARENT XDOM.CHILD [IN] XDOMLocateNode Parameters
7-20
Parameter childIndex
Description The index in the child array. Valid values are: XDOM.FIRST.CHILD XDOM.LAST.CHILD Positive Integer [IN] XDOMLocateNode Parameters (Continued)
7-21
Parameter nodeType
Description The type of node to be located. Valid values are: XDOM.NONE XDOM.ELEMENT.NODE XDOM.ATTR.NODE XDOM.TEXT.NODE XDOM.CDATA.NODE XDOM.ENTITY.REF.NODE XDOM.ENTITY.NODE XDOM.PROC.INST.NODE XDOM.COMMENT.NODE XDOM.DOC.NODE XDOM.DOC.TYPE.NODE XDOM.DOC.FRAG.NODE XDEOM.NOTATION.NODE XDOM.XML.DECL.NODE If nodeType is not XDOM.NONE, UniVerse uses this argument, along with direction and childIndex, to get the right typed node. For example, if direction is XDOM.PREV.SIBLING, and nodeType is XDOM.ELEMENT.NODE, UniVerse finds the element node which is the first previous sibling of nodeHandle. If direction is XDOM.CHILD, childIndex is XDOM.FIRST.CHILD, and nodeType is XDOM.ELEMENT.NODE, UniVerse finds the element node which is the first element child of nodeHandle. If the direction is XDOM.CHILD, childIndex is 2, and nodeType is XDOM.ELEMENT.NODE, UniVerse finds the element node which is the second element child of nodeHandle. When the direction is XDOM.NEXT.SIBLING.WITH.SAME.NAME, XDOM.PREV.SIBLING.WITH.SAME.NAME, or XDOM.PARENT, this argument is not used. [IN]
newNodeHandle
Handle to the found node. [OUT] XDOMLocateNode Parameters (Continued)
7-22
Return Codes
Return Code XML.SUCCESS XML.ERROR XM.INVALID.HANDLE Description The function completed successfully. An error occurred. An invalid handle was returned to the function. XDOMLocateNode Return Codes
XDOMEvaluate
Syntax
XDOMEvaluate(xmlHandle, xpathString, nsMap, aValue)
Description
The XDOMEvaluate function returns the value of the xpathString in the context xmlHandle in the DOM structure.
7-23
Parameters
Parameter xmlHandle xpathString nsMap Description Handle to the context. [IN] Relative or absolute Xpath string. [IN] The map of namespaces which resolves the prefixes in the xpathString. Format is xmlns=default_url xmlns:prefix1=prefix1_url xmlns:prefix2=prefix2_url For example: xmlns=http://myproject.mycompany.com xmlns:a_prefix=a.mycompany.com [IN] aValue The value of xpathString. [OUT] XDOMEvaluate Parameters
Return Codes
Return Code XML.SUCCESS XML.ERROR XML.INVALID.HANDLE Description The function completed successfully. An error occurred. An invalid DOM handle was returned to the function.
XDOMEvaluate Return Codes
7-24
XDOMRemove
Syntax
XDOMRemove(xmlHandle, xpathString, nsMap, attrName, nodeHandle)
Description
The XDOMRemove function finds the xpathString in the context xmlHandle in DOM structure, removes the found node or its attribute with name attrName.
Parameters
Parameter xmlHandle xpathString nsMap Description Handle to the context. [IN] Relative or absolute Xpath string. [IN] The map of namespaces which resolve the prefixes in the xpathString. Format is xmlns=default_url xmlns:prefix1_url xmlns:prefix2=prefix2_url For example: xmlns=http://myproject.mycompany.com xmlns:a_prefix=a.mycompany.com [IN] attrName nodeHandle The attribute name. [IN] The removed node, if nodeHandle is not NULL. [OUT] XDOMRemove Parameters
7-25
Return Codes
Return Code XML.SUCCESS XML.ERROR XML.INVALID.HANDLE Description The function completed successfully. An error occurred. An invalid DOM handle was returned to the function. XDOMRemove Return Codes
XDOMAppend
Syntax
XDOMAppend(xmlHandle, xpathString, nsMap, nodeHandle, dupFlag)
Description
The XDOMAppend function finds the xpathString in the context xmlHandle in the DOM structure, and inserts nodeHandle into the DOM structure as next sibling of found node. If the inserted node type is XDOM.ATTR.NODE, this node is inserted as an attribute.
7-26
Parameters
Parameter xmlHandle xpathString nsMap Description The handle to the context. [IN] Relative or absolute XPath string. [IN] The map of namespaces which resolve the prefixes in the xpathString. Format is xmlns=default_url xmlns:prefix1=prefix1_url xmlns:prefix2=prefix2_url For example: xmlns=http://myproject.mycompany.com xmlns:a_prefix=a.mycompany.com [IN] nodeHandle dupFlag Handle to a DOM subtree. If nodeHandle points to a DOM document, all of its children are inserted, in the same order. [IN] XDOM.DUP: Clones nodeHandle, and insert the duplicate node. XDOM.NODUP: Inserts the original node. The subtree is also removed from its original location. [IN] XDOMAppend Parameters
Return Codes
Return Code XML.SUCCESS XML.ERROR XML.INVALID.HANDLE Description The function completed successfully. An error occurred. An invalid DOM handle was returned to the function. XDOMAppend Return Codes
7-27
XDOMInsert
Syntax
XDOMInsert (xmlHandle, xpathString, nsMap, nodeHandle, dupFlag)
Description
The XDOMInsert function finds the xpathString in the context xmlHandle in the DOM structure and inserts nodeHandle into the DOM structure as a previous sibling of the found node. If the inserted node type is XDOM.ATTR.NODE, this node is inserted as an attribute.
Parameters
Parameter xmlHandle xpathString nsMap Description The handle to the context. [IN] Relative or absolute xpath string. [IN] The map of namespaces which resolves the prefixes in the xpathString. Format is xmlns=default_url xmlns:prefix1=prefix1_url xmlns:prefix2=prefix2_url For example: xmlns=http://myproject.mycompany.com xmlns:a_prefix=a.mycompany.com [IN] nodeHandle dupFlag The handle to a DOM subtree. If nodeHandle points to a DOM document, all of its children are inserted, in the same order. [IN] XDOM.DUP: Clones nodeHandle, and inserts the duplicate node. XDOM.NODUP: Inserts the original node and removes the subtree from its original location. XDOMInsert Parameters
7-28
Return Codes
Return Code XML.SUCCESS XML.ERROR XML.INVALID.HANDLE Description The function completed successfully. An error occurred. An invalid DOM handle was returned to the function. XDOMInsert Return Codes
XDOMReplace
Syntax
XDOMReplace(xmlHandle, xpathString, nsMap, nodeHandle, dupFlag)
Description
The XDOMReplace function finds the xpathString in the context xmlHandle in the DOM structure, and replaces the found node with nodeHandle.
7-29
Parameters
Parameter xmlHandle xpathString nsMap Description The handle to the context. [IN] Relative or absolute Xpath string. [IN] The map of namespaces which resolve the prefixes in the xpathString. Format is xmlns=default_url xmlns:prefix1=prefix1_url xmlns:prefix2=prefix2_url For example: xmlns=http://myproject.mycompany.com xmlns:a_prefix=a.mycompany.com [IN] nodeHandle Handle to a DOM subtree. If nodeHandle points to a DOM document, the found node is replaced by all of nodeHandle children, which are inserted in the same order. [IN] XDOM.DUP: Clones nodeHandle, and replaces it with the duplicate node. XDOM.NODUP: Replaces with the original node. The subtree is also removed from its original location. [IN] XDOMReplace Parameters
dupFlag
Return Codes
Return Code XML.SUCCESS XML.ERROR XML.INVALID.HANDLE Description The function completed successfully. An error occurred. An invalid DOM handle was returned to the function. XDOMReplace Return Codes
7-30
XDOMAddChild
Syntax
XDOMAddChild(xmlHandle, xpathString, nsMap, nodeHandle, dupFlag)
Description
The XDOMAddChild function finds the xpathString in the context xmlHandle in the DOM structure and inserts a node nodeHandle as the last child of the found node. If the inserted node type is XDOM.ATTR.NODE, this node is inserted as an attribute.
Parameters
Parameter xmlHandle xpathString nsMap Description The handle to the context. [IN] Relative or absolute Xpath string. [IN] The map of namespaces which resolve the prefixes in the xpath string. Format is xmlns=default_url xmlns:prefix1=prefix1_url xmlns:prefix2=prefix2_url For example: xmlns=http://myproject.mycompany.com xmlns:a_prefix=a.mycompany.com [IN] nodeHandle dupFlag Handle to a DOM subtree. If nodeHandle points to a DOM document, all of its children are inserted, in the same order. [IN] XDOM.DUP: Clones nodeHandle, and inserts the duplicate node. XDOM.NODUP: Inserts the original node. The subtree is also removed from its original location. [IN] XDOMAddChild Parameters
7-31
Return Code XML.SUCCESS XML.ERROR XML.INVALID.HANDLE Description The function completed successfully. An error occurred. An invalid DOM handle was returned to the function. XDOMAddChild Return Codes
XDOMClone
Syntax
XDOMClone (xmlHandle, newXmlHandle, depth)
Description
The XDOMClone function duplicates the DOM subtree specified by xmlHandle to a new subtree newXmlHandle. The duplicate node has no parent (parentNode returns null.). Cloning an element copies all attributes and their values, including those generated by the XML processor, to represent defaulted attributes, but this method does not copy any text it contains unless it is a deep clone, since the text is contained in a child text node. Cloning any other type of node simply returns a copy of this node.
7-32
Parameters
Parameter xmlHandle newXmlHandle depth Description Handle to the DOM subtree. [IN] Handle to the new DOM subtree. [IN] XDOM.FALSE: Clone only the node itself. XDOM.TRUE: Recursively clone the subtree under the specified node. [IN] XDOMClone Parameters
Return Codes
Return Code XML.SUCCESS XML.ERROR XML.INVALID.HANDLE Description The function completed successfully. An error occurred. An invalid DOM handle was returned to the function. XDOMClone Return Codes
XDOMTransform
Syntax
XDOMTransform(domHandle, styleSheet, ssLocation, outDomHandle)
Description
The XDOMTransform function transforms input DOM structure using the style sheet specified by styleSheet to output DOM structure.
7-33
Parameters
Parameter domHandle styleSheet ssLocation Description Handle to the DOM structure. [IN] Handle to the context [IN] A flag to specify whether styleSheet contains style sheet itself, or is just the style sheet file name. Value values are: XML.FROM.FILE (default) XML.FROM.STRING [IN] outDomHandle Handle to the resulting DOM structure. [OUT] XDOMTransform Parameters
Return Codes
Return Code XML.SUCCESS XML.ERROR XML.INVALID.HANDLE Description The function completed successfully. An error occurred. An invalid DOM handle was returned to the function. XDOMTransform Return Codes
XDOMGetNodeName
Syntax
XDOMGetNodeName(nodeHandle, nodeName)
7-34
Description
The XDOMGetNodeName function returns the node name.
Parameters
Parameter nodeHandle nodeName Description Handle to the DOM node. [IN] String to store the node name. [OUT] XDOMGetNodeName Parameters
Return Codes
XDOMGetNodeName Return Codes
XDOMGetNodeValue
Syntax
XDOMGetNodeValue(nodeHandle, nodeValue)
Description
The XDOMGetNodeValue returns the node value.
7-35
Parameters
Parameter nodeHandle nodeValue Description The handle to the DOM node. [IN] The string to hold the node value. [OUT] XDOMGetNodeValue Parameters
Return Codes
XDOMGetNodeValue Return Codes
XDOMGetNodeType
Syntax
XDOMGetNodeType(nodeHandle, nodeType)
Description
The XDOMGetNodeType function returns the node type.
7-36
Parameters
Parameter nodeHandle nodeType Description The handle to the DOM node. [IN] An integer to store the node type. [OUT] XDOMGetNodeType Parameters
Return Codes
XDOMGetNodeType Return Codes
XDOMGetAttribute
Syntax
XDOMGetAttribute(nodeHandle, attrName, nodeHandle)
Description
The XDOMGetAttribute function returns the node's attribute node, whose attribute name is attrName.
7-37
Parameters
Parameter nodeHandle attrName nodeHandle Description Handle to the DOM node. [IN] Attribute name. [IN] Handle to the found attribute node. [OUT] XDOMGetAttribute Parameters
Return Codes
XDOMGetAttribute Return Codes
XDOMGetOwnerDocument
Syntax
XDOMGetOwnerDocument(nodeHandle, domHandle)
Description
The XDOMGetOwnerDocument function returns the DOM handle to which nodeHandle belongs.
7-38
Parameters
Parameter nodeHandle domHandle Description Handle to the DOM node. [IN] Handle to the DOM structure. [OUT]
XDOMGetOwnerDocument Parameters
Return Codes
XDOMGetOwnerDocument Return Codes
XDOMGetUserData
Syntax
XDOMGetUserData(nodeHandle, userData)
Description
The XDOMGetUserData function returns the user data associated with the node.
7-39
Parameters
Parameter nodeHandle userData Description The handle to the DOM node. [IN] String to hold the user data. [OUT] XDOMGetUserData Parameters
Return Codes
XDOMGetUserData Return Codes
XDOMSetNodeValue
Syntax
XDOMSetNodeValue(nodeHandle, nodeValue)
Description
XDOMSetNodeValue sets the node value.
7-40
Parameters
Parameter nodeHandle nodeValue Description The handle to the DOM node. [IN] String to hold the node value. [IN] XDOMSetNodeValue Parameters
Return Codes
XDOMSetNodeValue Return Codes
XDOMSetUserData
Syntax
XDOMSetUserData(nodeHandle, userData)
Description
The XDOMSetUserData function sets the user data associated with the node.
7-41
Parameters
Parameter nodeHandle userData Description Handle to the DOM node. [IN] String to hold the user data. [IN] XDOMSetUserData Parameters
Return Codes
XDOMSetUserData Return Codes
XMLGetError
Syntax
XMLGetError(errorCode, errorMessage)
Description
The XMLGetError function returns the error code and error message after the previous XML API failed.
7-42
Parameters
Parameter errorCode errorMessage Description The error code. [OUT] The error message. [OUT]
XMLGetError Parameters
Return Codes
Return Code XML.SUCCESS XML.ERROR Description The function completed successfully. An error occurred. XDOMGetError Return Codes
7-43
Chapter
Data Transfer Between XML Documents and UniVerse Files

Transferring Data From XML to the Database . . . . . . Populating the Database . . . . . . . . . . . . . . Populating the Database from TCL. . . . . . . . . . Populating the Database Using the UniVerse BASIC XMAP API The XMAP API . . . . . . . . . . . . . . . . . XMAPOpen Function . . . . . . . . . . . . . . XMAPClose Function. . . . . . . . . . . . . . XMAPCreate Function . . . . . . . . . . . . . XMAPReadNext Function . . . . . . . . . . . . XMAPAppendRec Function . . . . . . . . . . . . XMAPToXMLDoc Function. . . . . . . . . . . . Examples . . . . . . . . . . . . . . . . . . Transferring Data from the Database to XML . . . . . . . . Creating an XML Document from TCL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-2 8-10 8-10 8-12 8-13 8-13 8-14 8-15 8-16 8-17 8-18 8-19 8-22 8-22
The new XMLDB data transfer capability extends the existing XML support in UniVerse. It consists of the data transfer utilities and the UniVerse BASIC XMAP API. The data transfer utilities consist of two TCL commands, XML.TODB and DB.TOXML, and two UniVerse BASIC functions, XMLTODB() and DBTOXML(). The UniVerse BASIC XMAP API consists of the following six UniVerse BASIC functions: XMAPOpen() XMAPClose() XMAPCreate() XMAPReadNext() XMAPAppendRec() XMAPToXMLDoc() These new TCL commands and UniVerse BASIC functions enable data transfer between XML documents and UniVerse files.
Transferring Data From XML to the Database

You can store data contained in an XML document in UniVerse files. This process is called shredding. You can also create XML documents from data contained in UniVerse files. Prior to this release, transferring information from an XML document to UniVerse supported limited levels of nesting. At this release, you can transfer an unlimited levels of XML data to UniVerse files, although one UniVerse file can contain no more than three levels of data. If you are extracting more than three levels of data, you must write the data to more than one UniVerse file.
The following example shows a sample XML document containing information about students in different school districts:
<?xml version=1.0 ?> <ROOT> <SCHOOL SCHOOLID=CO001 NAME=Fairview DISTRICT=BVSD> <CLASS CLASSOF=2004 <STUDENT ID=521814564 NAME=Harry Smith DOB=1985-02-08> <TERM SEMESTER=FA02> <COURSE NAME=MA130 GRADE=A /> <COURSE NAME=CH100 GRADE=B /> <COURSE NAME=PY100 GRADE=B /> </TERM> <TERM SEMESTER=SP03> <COURSE NAME=MA131 GRADE=B /> <COURSE NAME=CH101 GRADE=B /> <COURSE NAME=PE220 GRADE=A /> </TERM> </STUDENT> <STUDENT ID=414446545 NAME=Karl Offenbach DOB=1984-1226> ... </STUDENT> </CLASS> <CLASS CLASSOF=2005> ... </SCHOOL> <SCHOOL SCHOOLID=CO002 NAME=Golden DISTRICT=ACSD <CLASS CLASSOF=2004> <STUDENT ID=291222021 NAME=Jojo Smith DOB=1985-08-06> <TERM SEMESTER=SP03> <COURSE NAME=FR101 GRADE=B /> </TERM> </STUDENT> </CLASS> <CLASS CLASSOF=2005> <STUDENT ID=424325656 NAME=Sally Martin DOB=1985=12-01 <TERM SEMESTER=FA02 <COURSE NAME=PY100 GRADE=C /> <COURSE NAME=PE100 GRADE=C /> </TERM> </STUDENT> </CLASS> <SCHOOL SCHOOLID=CO003 NAME=Cherry Creek DISTRICT=CCSD ... </SCHOOL> </ROOT>
This document can be represented by the following XML document tree:

8-4
The following is an overview of the steps required to retrieve data from and XML database and store it in UniVerse files.
Generate Database Schema

First, you must understand the structure of the data in the incoming XML document. You can understand this structure by reviewing the DTD or Schema of the XML document.
Create UniVerse Data Files

After you review the DTD or Schema from the incoming XML document, you must create the corresponding UniVerse data and dictionary files, and create a dictionary record for each element or attribute in the corresponding XML document.
If you want to transfer all the data from this sample XML document to UniVerse, you must deal with five levels of nested elements, SCHOOL, CLASS, STUDENT, TERM and COURSES. Therefore, you have to map this XML document to two UniVerse files. Logically, you would map the bottom three elements, STUDENT, TERM, and COURSES, to one UniVerse file. We will call this file the STUDENT file. We will map the top two elements, SCHOOL and CLASS, to another UniVerse file. We will call this file the SCHOOL file. The ID, NAME, and DOB attributes of the element STUDENT will map to singlevalued fields in the STUDENT file, the attribute SEMESTER of the subelement TERM will map to a multivalued field, and the attributes NAME and GRADE of the third-level nested element COURSES will map to multivalued fields as well. However, we will separate the fields that correspond to the NAME and GRADE attributes with subvalue marks. Since the STUDENT file fields corresponding to XML attributes SEMESTER, NAME, and GRADE are all related, they will be combined into one association, called CGA. The element CLASS serves as a link between the two UniVerse files, and therefore the field CLASS_OF appears in both UniVerse files. The contents of the dictionary for each file follows:
DICT STUDENT 01:25:17pm 16 Sep 2003 Page 1
Type & Field......... Field. Field........ Conversion.. Column......... Output Depth & Name.......... Number Definition... Code........ Heading........ Format Assoc.. @ID NAME DOB CLASS_OF SEMESTER COURSE_NBR COURSE_GRD D D D D D D D 0 1 2 3 4 5 6 STUDENT Name DOB Class Of 10L 10L 10L 10L Semester Course No Grade S S S S 10L 10L 10L M CGA M CGA M CGA
D2
7 records listed. > DICT SCHOOL 01:27:14pm 16 Sep 2003 Page 1
Type & Field......... Field. Field........ Conversion.. Column......... Output Depth & Name.......... Number Definition... Code........ Heading........ Format Assoc.. @ID SCHOOLID SCHOOL_NAME SCHOOL_DISTRIC T CLASS_OF D D D D D 0 0 1 2 3 SCHOOL SchoolId Name District Class Of 10L 10L 10L 10L 10L S S S S S
5 records listed.
8-6
Create the U2XMAP File

The rules for transferring data between an XML document and database files are recorded in a separate file, referred to as the U2XMAP file. This file contains such information as the starting node of the XML document, names and relationships of database files that are being used to exchange data with a specified XML document, the mapping of XML attribute names to database field names, and other optional information, such as the mapping of NULL values and date format conversions. The following example illustrates a U2XMAP:
Each TABLECLASSMAP element defines where to find the data in the XML document, and where to place it in the UniVerse data file based on the dictionary definition of the field.
Syntax: TABLECLASSMAP MapName = xx StartNode = startnode TableName = UniVerse file name The following table describes each parameter of the syntax:
Parameter MapName StartNode TableName Description The name of the relationship between the portion of the XML document that starts with StartNode and the UniVerse data file. The XPath expression defining the starting position in the XML document. The name of the target UniVerse file. TABLECLASSMAP Parameters
To map a particular XML attribute to a UniVerse field, use the ColumnMap element. Syntax: ColumnMap Node=XPath expression, Column = UniVerse record field The ColumnMap node defines the location of the node in the XML document. The ColumnMap Column defines the field in the UniVerse file to which you want to map the XML data. The UniVerse file must exist, and the dictionary record for the field must be defined.
Mapping XML Data to Multivalued Fields

If you want to map an XML attribute to a multivalued field in the UniVerse record, specify a comma (,) before the name of the XML attribute, as shown in the following example: ColumnMap Node = CLASS, @CLASSOF Column = CLASS_OF
8-8
If you want the values of the corresponding UniVerse data files to be separated by subvalue marks, such as COURSE_NBR and COURSE_GRADE in the STUDENT file, specify a comma before the attribute of the next level subelement and another comma before the attribute of the next level subelement, as shown in the following example: ColumnMap Node="TERM, COURSES, @NAME" Column="COURSE_NBR" ColumnMap Node="TERM, COURSES, @GRADE" Column="COURSE_GRD"
Defining a Map Relationship

If you are mapping the XML attributes to more than one UniVerse data file, you must define a dependent map using the TableMap Node element. TableMap Node=CLASS/STUDENT MapName=M2 In this example, MapName M2 is defined within the MapName M1 element as a dependent map to M1.
<TABLECLASSMAP MapName=M1 StartNode=/ROOT/SCHOOL TableName=SCHOOL> <ColumnMap Node=@SCHOOLID Column=SCOOLID /> <ColumnMap Node=@NAME Column=SCHOOL_NAME /> <ColumnMap Node=@DISTRICT Column=SCHOOL_DISTRICT /> <ColumnMap Node=CLASS, @CLASSOF Column=CLASS_OF /> <TableMap Node = CLASS/STUDENT MapName=M2 /> </TABLECLASSMAP>
Defining Related Tables

If you are mapping more than three levels of data, you must map the data to more than one UniVerse file, since a UniVerse file can support no more than three levels of data. In the U2XMAP file, you define the files that are related to each other using the RelatedTable element. Use the MapParentKey element to define the parent file (the file corresponding to the top portion of the XML subtree being transformed). Use the MapChildKey to define each child file of the parent file, as shown in the following example:
<RelatedTable> <MapParentKey TableName=SCHOOL Column=CLASS_OF Key Generate=No /> <MapChildKey TableName=STUDENT Column=CLASS_OF /> </RelatedTable>
In this example, SCHOOL is the parent UniVerse file which contains one child file, STUDENT. You must define a field that appears in both UniVerse files using the Column element. In this case, CLASS_OF appears in both the SCHOOL and STUDENT files. The KeyGenerate element determines if UniVerse generates the parent/child key or not.
8-10
Populating the Database

After you define the U2XMAP file, you can populate the UniVerse database from TCL or UniVerse BASIC.
Populating the Database from TCL

Use the XML.TODB command to populate the UniVerse database from TCL. Syntax: XML.TODB <XML Document> <U2XMAP File> The following example assumes that the XML document STUDENT.XML and the U2XMAP STUDENT.MAP are located in the &XML& file.
XML.TODB STUDENT.XML STUDENT.MAP

LIST SCHOOL SCHOOL..... CO001 CO002 CO003 Name...... Fairview Golden Cherry Creek District.. BVSD ACSD CCSD Class Of 2004 2005 2004 2005 2004 2005
LIST STUDENT STUDENT..... Name 414446545 Karl Offenbach
DOB 24 DEC 84
Class Of 2004
Semester.. FA02
Course NO. HY104 MA101 FR100 HY105 MA102 FR101 PY100
Grade D C C B C C C
SP03
4243255656
Sally Martin
01 DEC 85 ........
2005
FA02
Populating the Database using the UniVerse BASIC XMLTODB() function

You can also populate the UniVerse database by calling the UniVerse BASIC XMLTODB function. XMLTODB does the same thing as the TCL XML.TODB command. If you want to transform specific data, use the XMAP API. Syntax: XMLTODB(xml_document, doc_flag, u2xmapping_rules, u2xmap_ flag, status) The following table describes each parameter of the syntax.
Parameter xml_document doc_flag Description The name of the XML document. A flag defining the type of xml_document. Valid values are: XML.FROM.DOM - xml_document is a DOM handle. XML.FROM.FILE - xml_document is a file name. XML.FROM.STRING - xml_document is the name of variable containing the XML document u2xmapping_rules u2xmap_flag The mapping rules for the XML document. A flag indicating if the mapping file is the U2XMAP file itself or a string located within the UniVerse BASIC program. Valid values are: XMAP.FROM.FILE - the mapping rules are contained in a U2XMAP file. XMAP.FROM.STRING - u2xmap_flag is the name of the variable containing the mapping rules. Status The return status. XMAPOpen Parameters
8-12
Populating the Database Using the UniVerse BASIC XMAP API

While the TCL command XML.TODB and the UniVerse BASIC function XMLTODB() provide easy ways of transferring data from an XML document to a set of related database files, you may want to have greater control over which part of the XML document you want to use for transferring data. For example, neither XML.TODB or XMLTODB() let you start the data transfer from a particular sibling of the start node. An example of such finer control is transferring only the second school data and its dependent subtree to the database from the sample XML document. You can accomplish this using a combination of the DOM API functions and the XMAP API functions. In order to provide a record-by-record mapping between the XML document and the corresponding UniVerse files, the UniVerse engine generates an internal structure, called U2XMAP dataset. This internal structure contains information about the mapped XML elements and attributes, as well as how they relate to the fields in the corresponding UniVerse files. The U2XMAP dataset is not directly accessible to Basic programs, but instead referenced by its handle, called U2XMAP dataset handle.
8-13
The XMAP API

The UniVerse XMAP API consists of the following UniVerse BASIC functions: XMAPOpen() XMAPClose() XMAPCreate() XMAPReadNext() XMAPAppendRec() XMAPToXMLDoc()
XMAPOpen Function
The XMAPOpen function opens an XML document as a U2XMAP data set.
Syntax:
XMAPOpen(xml_document, doc_flag, u2xmapping_rules, u2xmap_flag, XMAPhandle)
Parameters
Parameter xml_document doc_flag Description The name of the XML document. A flag defining the type of xml_document. Valid values are: XML.FROM.DOM - xml_document is a DOM handle. XML.FROM.FILE - xml_document is a file name. XML.FROM.STRING -xml_document is the name of variable containing the XML document. XMAPOpen Parameters
8-14
Parameter u2xmapping_rules u2xmap_flag
Description The name of the U2XMAP file, or the UniVerse BASIC variable containing the XML to Database mapping rules. A flag indicating if the mapping file is the U2XMAP file itself or a string located within the UniVerse BASIC program. Valid values are: XMAP.FROM.FILE - the mapping rules are contained in a U2XMAP file. XMAP.FROM.STRING - u2xmap_flag is the name of the variable containing the mapping rules.
XMAPhandle
The handle to the XMAP dataset. XMAPOpen Parameters (Continued)
Return Values
The following table describes the return values for the XMAPOpen function.
Return Value XML_SUCCESS XML_ERROR Description The XML document was opened successfully. An error occurred opening the XML document. XMAPOpen Return Values
XMAPClose Function
The XMAPClose function closes the U2XMAP dataset handle and frees all related structures and memory.
Syntax
XMAPClose(XMAPhandle) where XMAPhandle is the handle to the U2XMAP dataset.
8-15
Return Values
The following table describes the return values from the XMAPClose function.
Return Value XML_SUCCESS XML_ERROR XML_INVALID_HANDLE Description The XML document was closed successfully. An error occurred closing the XML document. The XMAP dataset was invalid. XMAPClose Return Values
XMAPCreate Function
The XMAPCreate function creates an empty XML document for transferring data from the UniVerse database to XML according the mapping rules you define.
Syntax
XMAPCreate(u2xmapping_rules, mapping_flag, XMAPhandle)
Parameters
Parameter u2xmapping_rules mapping_flag Description The name of the U2XMAP file, or the UniVerse BASIC variable containing the XML to Database mapping rules. A flag indicating if the mapping file is the U2XMAP file itself or a string located within the UniVerse BASIC program. Valid values are: XMAP.FROM.FILE - the mapping rules are contained in a U2XMAP file. XMAP.FROM.STRING - u2xmapping_rules is the name of the variable containing the mapping rules. XMAPhandle The handle to the XMAP dataset. XMAPCreate Parameters
8-16
Return Values
The following table describes the return values for the XMAPCreate function.
Return Value XML_SUCCESS XML_ERROR XML_INVALID_HANDLE Description The XML document was opened successfully. An error occurred opening the XML document. The XMAP dataset was invalid.
XMAPCreate Return Values
XMAPReadNext Function
The XMAPReadNext function retrieves the next record from the U2XMAP dataset and formats it as a record of the UniVerse file that is being mapped.
Syntax
XMAPReadNext(XMAPhandle, file_name, record)
Parameters
Parameter XMAPhandle file_name record Description The U2XMAP dataset handle. The name of the UniVerse file that is being mapped in the U2XMAP dataset. The data record formatted according to the dictionary record of the file. XMAPReadNext Parameters
8-17
Return Values
The following table describes the return values for the XMAPReadNext function.
Return Value XML_SUCCESS XML_ERROR XML_INVALID_HANDLE XML_EOF Description The XMAPReadNext was executed successfully. Error in executing XMAPReadNext.
U2 XMAP dataset handle was invalid. The end of the U2XMAP dataset has been reached.
XMAPReadNext Return Values
XMAPAppendRec Function
The XMAPAppendRec function formats the specified record from the UniVerse file as a U2XMAP dataset record and appends it to the U2XMAP dataset.
Syntax
XMAPAppendRec(XMAPhandle, file_name, record)
Parameters
Parameter XMAPhandle file_name Description The handle to the U2XMAP dataset.
The name of the UniVerse file that is being mapped in the U2 XMAP dataset The data record formatted according to the dictionary record of the UniVerse file.
XMAPAppendRec Parameters
record
8-18
Return Values
The following table describes the return values of the XMAPAppendRec function.
XMAPAppendRec Return Values
XMAPToXMLDoc Function
The XMAPToXMLDoc function generates an XML document from the data in the U2XMAP dataset using the mapping rules you define. The XML document can be either an XML DOM handle or an XML document. UniVerse writes the data to a file or a UniVerse BASIC variable.
Syntax
XMAPToXMLDoc(XMAPhandle, xmlfile, doc_flag)
8-19
Parameters
Parameter XMAPhandle xmlfile doc_flag Description The handle to the U2XMAP dataset. The name of the XML file, or the name of a UniVerse BASIC variable to hold the XML document. Indicates where to write the XML document. Valid values are: XML.TO.DOM - Writes the XML document to an XML DOM handle. XML.TO.FILE - Writes the XML document to a file. XML.TO.STRING - Writes the XML document to a UniVerse BASIC variable. XMAPToXMLDoc Parameters
Return Values
The following table describes the return values of the XMAPToXMLDoc function.
XMAPToXMLDoc Return Values
Examples
The following example illustrates an XMLDOM tree containing information for three schools:
8-20
ROOT
SCHOOL CO001
SCHOOL CO002
SCHOOL CO003
CLASS 2004
CLASS 2005
CLASS 2004
CLASS 2005
CLASS 2004
CLASS 2005
STUDENT 521814564
STUDENT 414446545
STUDENT 221345665
STUDENT 978766676
STUDENT 291222021
STUDENT 424325656
STUDENT 102938475
STUDENT 044556661
ERM TERM A02 SP03
TERM TERM FA02 SP03
TERM TERM FA02 SP03
TERM FA02
TERM SP03
TERM SP03
TERM FA02
TERM SP03
TERM SP03
TERM FA02
TERM SP03
We will use the following U2XMAP to transfer the data to the UniVerse database:
<TABLECLASSMAP MapName="M2" StartNode="CLASS/STUDENT" TableName="STUDENT"> <ColumnMap Node="@ID" Column="@ID" /> <ColumnMap Node="@NAME" Column="NAME" /> <ColumnMap Node="@DOB" Column="DOB" /> <ColumnMap Node="TERM, @SEMESTER" Column="SEMESTER" /> <ColumnMap Node="TERM, COURSES, @NAME" Column="COURSE_NBR" /> <ColumnMap Node="TERM, COURSES, @GRADE" Column="COURSE_GRD" /> </TABLECLASSMAP>
8-21
The following UniVerse BASIC program segment illustrates extracting data for only SCHOOL CO002 to the STUDENT file in the UniVerse database:
$INCLUDE UNIVERSE.INCLUDE XML.H *Parse XML document and build DOM tree in memory STATUS = XDOMOpen(STUDENT.XML,XML.FROM.FILE,domH) *Position at a specific node STATUS = XDOMLocate(domH, /ROOT/SCHOOL[2], , domHandle) *Open XMAP dataset for reading STATUS = XMAPOpen(domHandle, XML.FROM.DOM, STUDENT.MAP, XML.FROM.FILE, Xfile) OPEN STUDENT TO F1 ELSE STOP Error opening file STUDENT *Read records from XMAP dataset, write to STUDENT file MOREDATA = 1 LOOP STATUS = XMAPReadNext(Xfile, STUDENT, RECORD) IF STATUS = XML.EOF THEN MOREDATA = 0 END WHILE MOREDATA DO ID = RECORD<1> REC = FIELD(RECORD, @FM, 2, 999) WRITE REC TO F1, ID ELSE STOP Write to file STUDENT failed REPEAT STATUS = XMAPClose(Xfile) RETURN END
8-22
Transferring Data from the Database to XML

There are multiple methods available to transfer data from the UniVerse database to an XML document: TCL LIST command SQL SELECT statement TCL DB.TOXML command and UniVerse BASIC DBTOXML() function UniVerse BASIC XMAP API (XMAPCreate Function, XMAPAppendRec Function, and XMAPToXMLDoc Function) For information about creating an XML document using the TCL LIST command or the SQL SELECT statement, see Creating XML Documents in the UniVerse BASIC Extensions manual. Note: XMLTODB() and DBTOXML() are not part of the XMAP API, they are standalone UniVerse BASIC functions completely equivalent to the corresponding TCL commands.
Creating an XML Document from TCL

To create an XML document from TCL, use the DB.TOXML command.
Syntax
DB.TOXML xml_doc_filename xmap_filename condition
8-23
Parameters
Parameter xml_doc_filename xmap_filename condition Description The name of the XML document to create. If you do not enter a full path, the file is written to the &XML& directory. The file name for the U2XMAP file. A UniVerse RetrieVe condition string, for example, WITH SCHOOL = CO002 DB.TOXML Parameters
Example
The following example illustrates using DB.TOXML from TCL to create an XML document.
DB.TOXML SCHOOL_STUDENT.XML STUDENT.MAP WITH SCHOOLID = CO002
Creating an XML Document from UniVerse BASIC

To create an XML document from the UniVerse database using UniVerse BASIC, use the DBTOXML function. Syntax: DBTOXML(xml_document, doc_location, u2xmap_file, u2xmap_location, condition, status)
8-24
Parameters
Parameter xml_document doc_flag Description The name of the XML document to create. A flag defining the type of xml_document. Valid values are: XML.FROM.FILE - xml_document is a file name. XML.FROM.STRING -xml_document is the name of variable containing the XML document. u2xmap_file u2xmap_location The name of the U2XMAP file to use to produce the XML document. The location of the U2XMAP file. XML.FROM.FILE - u2xmap_file is a file name. XML.FROM.STRING - is u2xmap_file the name of variable containing the mapping rules. condition
A query condition for selecting data from the UniVerse file, for example, WHERE SCHOOL = "CO002"
XML.SUCCESS or XML.FAILURE. DBTOXML Parameters
Status
8-25
Chapter
The XML/DB Tool
9
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-3 9-9 9-10 9-11 9-13 9-16 9-18 9-20 9-25 9-27 9-29 9-31 9-35 9-35 9-36 9-36 9-36 9-36 9-37 9-38 9-39 9-41 9-43
Installing the XML/DB Tool . . . . . Create the DTD or XML Schema . . . Using the XML/DB Tool . . . . . . Create Server Definition . . . . . Connect to Server . . . . . . . Creating a DTD . . . . . . . . . Creating or Displaying an XML Schema . Create a Mapping File . . . . . . . Create Relationship . . . . . . Mapping All Matching Elements . . Mapping to Multiple UniVerse Files . Defining Related Tables . . . . . Options . . . . . . . . . . . . Define How to Treat Empty Strings . Define Date Format . . . . . . Specify How to Treat Namespace . . Define Namespace . . . . . . . Define Cascade Rules . . . . . . Choose How To Treat Existing Records Importing and Exporting Mapping Files . Importing a Mapping File . . . . Exporting a Mapping File . . . . XML/DB Tool Logging . . . . . .
. . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . .
The XML/DB tool enables you to create a mapping file to use when creating XML documents from the UniVerse database, or when extracting data from an XML document and updating the UniVerse database. The XML/DB tool loads a DTD or XML Schema, validates the DTD or XML Schema, opens the associated data files, and produces an outline of the file structure. You can then map the DTD or XML Schema tags to the associated fields in the data file, and use this map with RetrieVe, UniVerse SQL, UniVerse BASIC, or the XMAP API.
Installing the XML/DB Tool

Complete the following steps to install the XML/DB tool.
1. Load the UniData Client CD

Place the UniData Client CD in your CD-Rom drive. The following menu appears:
From the menu Select UniVerse Tools. From the Welcome menu, click Next.
Review License Agreement

Review the license agreement. If you agree with the terms of the license agreement, select I accept the terms of the license agreement., and click Next. If you do not accept the terms of the license agreement, select I do not accept the terms of the license agreement and exit the installation.
9-3
Choose Destination
The Choose Destination Location dialog box appears, as shown in the following example:
By default, UniVerse installs the Web Tools in the C:\IBM\Tools directory. If you want to choose a different directory, click Browse and choose the directory where you want to install the Web Tools. Click Next to continue with the installation.
Select Components
From the Select Components dialog box, select the components you want to install. At this release, the only components available are the XML/DB Tool and the SSL Config Editor. Make sure the XMLDBTool check box is selected, as shown in the following example:
Click Next to continue with the installation.
9-5
Select Program Folder

The installation next prompts you for a program folder for UniVerse Tools, as shown in the following example:
Enter the name of the program folder for UniVerse Tools if you do not want to accept the default, then click Next to continue the installation process.
Copy Files
The installation process now has enough information to begin copying files, as shown in the following example. If you want to change any settings, click Back. Click Next to begin copying files.
9-7
Complete the Installation

Click Finish. You may want to restart your computer before you use the XML/DB tool. The installation process prompts if you want to restart your computer now or at a later time, as shown in the following example:
Choose when you want to restart your computer, then click Finish.
Create the DTD or XML Schema

The XML/DB Tool works with existing DTD or XML Schema files. You must create a DTD or XML Schema file before using the XML/DB mapping tool if one does not already exist. Use UniVerse SQL, UniVerse BASIC, or RetrieVe to create the file. When you use the RetrieVe LIST statement or the UniVerse SQL SELECT statement, UniVerse creates an XML Schema or DTD if you specify TOXML and the TO keyword in the same statement. UniVerse writes the file to the &XML& directory, with an extension of .xsd for an XML schema file or .dtd for a DTD file. In the following example, UniVerse creates a STUDENT.xsd file in the &XML& directory:
:LIST STUDENT FNAME LNAME MAJOR MINOR ADVISOR TOXML WITHSCHEMA TO STUDENT :ED &XML& STUDENT.xsd Top of "STUDENT.xsd" in "&XML&", 26 lines, 812 characters. *--: p 001: <?xml version="1.0"?> 002: <xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema"> 003: <xsd:annotation> 004: <xsd:documentation xml:lang="en"> 005: account: C:\IBM\ud61\Demo 006: command: LIST STUDENT FNAME LNAME MAJOR MINOR ADVISOR TOXML WITHSCHEMA TO STUDENT 007: </xsd:documentation> 008: </xsd:annotation> 009: <xsd:element name="ROOT"> 010: <xsd:complexType> 011: <xsd:sequence maxOccurs="unbounded"> 012: <xsd:element ref="STUDENT" maxOccurs="unbounded"/> 013: </xsd:sequence> 014: </xsd:complexType> 015: </xsd:element> 016: <xsd:element name="STUDENT"> 017: <xsd:complexType> 018: <xsd:attribute name="_ID"/> 019: <xsd:attribute name="FNAME"/> 020: <xsd:attribute name="LNAME"/> 021: <xsd:attribute name="MAJOR"/> 022: <xsd:attribute name="MINOR"/>
9-9
Using the XML/DB Tool

To start the XML/DB Tool, from the Start menu, select Programs, then select IBM U2, then select UniVerse Tools, then click XMLDB Tool. The following dialog box appears:
9-10
Create Server Definition

To establish a connection to a server, right-click U2 Servers, then click New U2 Server. The Create New U2 Server dialog box appears, as shown in the following example:
In the Name box, enter a unique name to identify the server. The name cannot contain a forward slash (/) or a back slash (\). In the Host box, enter the hostname or IP address of the server. In the Database box, select UniData or UniVerse as the underlying database you are using.
9-11
Click Advanced if you want to define the type of communication you are using, specify a port number that differs from default, define the RPC Service Name, or specify a login account. A dialog box similar to the following example appears:
In the Transport Type box, choose the type of communication you are using to the server. You can choose Default, TCP/IP, or Lan Manager. The default is TCP/IP. In the RPC Port# box, enter the UniRPC port number. In the RPC Service Name box, enter the name of the RPC service you are using. The default service name is udcs for UniData, or uvcs for UniVerse. Enter the name of the account to which you want to connect in the Login Account box. Click Finish to register the server.
Connect to Server
To connect to a server, double-click the server to which you want to connect. A dialog box similar to the following example appears:
Enter your user ID and password in the appropriate boxes, then click Finish.
9-13
Once you connect to the server, the XML/DB Tool displays all available accounts, data files, DTD files, XMAP files, and XSD files, as shown in the following example:
9-14
Filtering Accounts
You can filter the accounts that are available in the XML/DB tool. To filter accounts, select the Filter icon, as shown in the following example:
Filter icon
9-15
Creating a DTD
Use the DTD File wizard to create a new DTD. To display an existing DTD, doubleclick the file you want to display in the U2 XML/DB Explorer area. To access the file wizard, expand the account where you want to create the DTD, then right-click DTD Files. The Create a New DTD File dialog box appears, as shown in the following example:
In the DTD name box, enter the name of the DTD, then click Finish.
9-16
Enter the DTD in the dialog box. The following example illustrates a DTD.
The XML/DB tool automatically validates the DTD. Click the Problems tab to view any problems detected with the DTD, as shown in the following example:
9-17
Creating or Displaying an XML Schema

Use the XSD File wizard to create a new XML Schema or display an existing XML Schema. To display an existing XML Schema, double-click the file you want to display in the Account Explorer area. To access the file wizard, expand the account where you want to create the XML Schema, then right-click XSD Files, then click New XSD File. The Create a New XSD File dialog box appears, as shown in the following example:
9-18
In the XSD name box, enter the name of the XSD. Enter the XML schema in the dialog box that appears, as shown in the following example:
The XML/DB tool automatically validates the XML Schema. Click the Problems tab to view any problems detected with the XML Schema, as shown in the following example:
9-19
Create a Mapping File

The XML/DB Tool enables you to create a new XML mapping file based on an existing DTD or XML Schema file. Creating an XML mapping file includes the following steps: Select the target account Specify the XMap file name Select the data files Select the DTD or XSD file Specify the root element
9-20
To create a new mapping file, expand the account where you want to create the XML Schema, then right-click XMap Files, then click New XMap File. The Create a New XMap File dialog box appears, as shown in the following example:
In the Map name box, enter the name for the XMap, then click Next.
9-21
The Source U2 files dialog box appears, as shown in the following example:
9-22
Select one or more files for which you want to create a map from the DTD or XSD file, then click Next. A dialog box similar to the following example appears:
9-23
Select the DTD or XSD file for which you want to create a mapping file, then click Next. The Root Element dialog box appears, as shown in the following example:
In the Root Element box, select the name of the root element in the DTD or XSD file, then click Finish.
9-24
The Mapping Editor appears, as shown in the following example:
The names of the dictionary records for the file you specified appear in the Tables area of the editor. The elements of the DTD or XML Schema file you specified appear in the DTD/XML Schema area.
Create Relationship
To create a relationship between a dictionary item and a DTD or XML Schema element, click the dictionary record name. Detailed information about the dictionary records appears in the U2 Dictionary area, as shown in the following example:
9-25
Right-click the element that corresponds to the dictionary item in the DTD/XML Schema area, then click Create Mapping. Arrows appear next to the items you selected for mapping, and the mapping relationship appears in the Outline area of the dialog box, as shown in the following example:
If you want to remove the mapping relationship, right-click the mapping definition in the DTD/XML Schema area, then click Remove Mapping.
9-26
Mapping All Matching Elements

If you want to map all dictionary items that have a matching element name, click the file name in the Tables area of the dialog box, right-click the appropriate element in the DTD/XML Schema area, then click Match Mapping. The XML/DB tool prompts you to select how you want to update the database if a record in the XML document already exists in the database, as shown in the following example:
Following are the choices if a record already exists in the database:
Default If the record already exists in the database, do not update it. Replace Replace the data in the existing record with the data from the XML document. Append In the case of a multivalued field, append the new value to the existing multivalued field. If you have duplicate data, do not use the Append option, as the multivalued field may be updated with duplicate data.
9-27
Click Finish. The XML/DB Tool maps all like elements, as shown in the following example:
9-28
Mapping to Multiple UniVerse Files

You can map an XML document to multiple UniVerse files. Choose on the following methods to access the Add Tables dialog box: From the Mapping Editor, from the XML/DB menu, click Add Tables. Click the Add Tables icon from the toolbar, as shown in the following example:
Add Tables Icon
Right-click an existing table in the Tables portion of the XML/DB Mapping Tool, then click Add Tables.
9-29
The Source U2 files dialog box appears, as shown in the following example:
9-30
Click the tables you want to add to the mapping file, then click Finish. The new table is now added to the mapping editor, as shown in the following example:
Defining Related Tables

If you are mapping more than three levels of data, you must map the data to more than one UniData file, since a UniData file can support no more than three levels of data. Choose on the following methods to access the Define Related Tables dialog box: From the Mapping Editor, from the XML/DB menu, click Define Related Tables.
9-31
Click the Define Related Tables icon from the toolbar, as shown in the following example:
Define related tables icon
Right-click an existing table in the Tables portion of the XML/DB Mapping Tool, then click Define Related Table. The Define Related Tables dialog box appears, as shown in the following example:
9-32
In the Parent Table box, select the parent table. The parent table is the file corresponding to the top portion of the XML subtree being transformed. In the Parent Key area, click the dictionary item that represents the primary key for the parent table. In the Child Table box, select the child table of the parent table. In the Child Key box, click the dictionary item that represents the primary key for the child table.
9-33
Click Add. The Define Related Tables area is now populated, as shown in the following example:
Click Finish to save the definition, or click Cancel to exit without saving changes.
9-34
Options
From the Mapping Editor, click the Options tab. A dialog box similar to the following example appears:
Define How to Treat Empty Strings

If you select the Empty String is Null check box and click ON, when the value of an optional XML element is omitted, the corresponding database field value is set to NULL, otherwise it is considered missing. Similarly, when a database field value is NULL and you select ON, the corresponding value of an optional XML element is omitted, otherwise it is set to an empty string.
9-35
Define Date Format

Data Format is a conversion code UniVerse uses to perform the ICONV()/OCONV() function when getting the data from the XML document or creating the XML document. This code can be any conversion code understood by UniVerse. You can also use the value of XMLFormat which converts the data into a standard data format for the XML document, or takes the standard XML date format (yyyy-mmdd).
Specify How to Treat Namespace

If you select the Ignore Namespace check box, UniVerse ignores all the Namespace information. This option applies when converting the XML document to the UniVerse database.
Define Namespace
Namespace elements are not required. If they are used, the same URI or prefix cannot be used more than once. Zero-length prefixes ("") are not currently supported. If you do not define a Prefix, UniVerse uses the Default Name space, used only for generating the XML document. In this case, UniVerse puts a default NameSpace in the output document.
Define Cascade Rules

This option only applies when an XML document is mapped to more than one UniVerse file. By default, the cascade mode is off, which means that the system takes care of the parent-child record relationship according to the ReleatedTable rules described in the U2XMAP file. Setting the cascade mode ON allows you to control the parent-child record relationship. When the cascade mode is ON, once the current parent table record is established, all child table records that are either read from or written to the child table are associated with the current parent table record. This affords you the freedom of associating parent and child table records the way you see fit.
9-36
Choose How To Treat Existing Records

Following are the choices if a record already exists in the database:
Default If the record already exists in the database, do not update it. Replace Replace the data in the existing record with the data from the XML document. Append In the case of a multivalued field, append the new value to the existing multivalued field. If you have duplicate data, do not use the Append option, as the multivalued field may be updated with duplicate data.
For detailed information about the mapping file, see Appendix B, The U2XMAP File.
9-37
Importing and Exporting Mapping Files

You can import a mapping file, DTD, or XSD from another system-level directory to your account, or export a mapping file to another system-level account.
9-38
Importing a Mapping File

To import an operating system-level mapping file, right-click XMap Files, then click Import. The Import dialog box appears, as shown in the following example:
9-39
From the Import From area, in the Server box, enter the name of the server where the mapping file resides. In the Directory box, enter the full path to the location of the mapping file, or click Browse to search for the location. In the Import Into area, in the Server box, enter the name of the server where you want to write the mapping file. In the Account area, enter the name of the account where you want the mapping file to reside, or click Browse to search for the account. Select the Overwrite existing files without warning check box if you want to overwrite a mapping file of the same name that may exist in the target account. Click Finish to import the mapping file.
9-40
Exporting a Mapping File

To export a mapping file, right-click XMap Files, then click Export. The Export dialog box appears, as shown in the following example:
9-41
From the Export From area, in the Server box, where the mapping file resides. In the Account box, enter the full path to the location of the mapping file, or click Browse to search for the location. In the Export To area, in the Server box, enter the name of the server where you want to write the mapping file. In the Directory area, enter the name of the account where you want the mapping file to reside at the operating-system level, or click Browse to search for the account. Select the Overwrite existing files without warning check box if you want to overwrite a mapping file of the same name that may exist in the target account. Click Finish to import the mapping file.
9-42
XML/DB Tool Logging

To enable logging with the XML/DB Tool, create an empty record in the VOC file of the UV account you are using the XML/DB Tool called XTOOLDBG prior to initializing an XML/DB Tool session. The log file captures output from the XML/DB Tool to the client, and output from the client to the XML/DB Tool, along with the time logging started, and any error codes sent to the client. The log file, located in the /tmp directory on UNIX platforms and the C:\tmp directory on Windows platforms, has the format XTOOLSUB_dddd_ttttt.log, where dddd is the internal date stamp and ttttt is the internal time stamp. If the /tmp or C:\tmp directory does not exist, you must create it prior to initializing logging.
9-43
Appendix
MQSeries API for UniData and UniVerse Reason Codes

This appendix describes the MQSeries Application Program Interface Reason Codes.
C:\Program Files\Adobe\FrameMaker7.0\UniVerse 10.2\basicext\AppA.fm 9/22/06
Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta
Reason Code Number 0 1 2
Reason Code Name AMRC_NONE AMRC_UNEXPECTED_ERR AMRC_INVALID_Q_NAME
Description The request was successful with no error or warning required. An unexpected error occurred. The specified queue name was too long, or contained invalid characters. The specified sender service name was too long, contained invalid characters, or used the reserved prefix SYSTEM. The specified receiver service name was too long, contained invalid characters, or used the reserved prefix SYSTEM. The specified publisher service name was too long, contained invalid characters, or used the reserved prefix SYSTEM. The specified subscriber name was too long, contained invalid characters, or used the reserved prefix SYSTEM. The specified policy name was too long, contained invalid characters, or used the reserved prefix SYSTEM. The specified message name was too long, contained invalid characters, or used the reserved prefix SYSTEM.
AMRC_INVALID_SENDER_NAME
AMRC_INVALID_RECEIVER_NAME
AMRC_INVALID_PUBLISHER_NAME
AMRC_INVALID_SUBSCRIBER_NAME
AMRC_INVALID_POLICY_NAME
AMRC_INVALID_MSG_NAME
MQSeries API Reason Codes
A-2
Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Reason Code Number 9
Reason Code Name AMRC_INVALID_SESSION_NAME
Description The specified session name was too long, contained invalid characters, or used the reserved prefix SYSTEM. The specified distribution list name was too long, contained invalid characters, or used the reserved prefix SYSTEM. Reserved for future use. The service handle specified for a sender, receiver, distribution list, publisher, or subscriber was not valid. The specified message handle was not valid. The specified session handle was not valid. The specified browse options value was not valid or contained an invalid combination of options. There was not enough memory available to complete the requested operation. An attempt was made to set the wait time in a policy object for which the wait-time was readonly. The specified (sender, receiver, distribution list, publisher, or subscriber) service was not found, so the request was not carried out.
10
AMRC_INVALID_DIST_LIST_NAME
11 12
AMRC_POLICY_HANDLE_ERR AMRC_SERVICE_HANDLE_ERR
13 14 15
AMRC_MSG_HANDLE_ERR AMRC_SESSION_HANDLE_ERR AMRC_BROWSE_OPTIONS_ERR
16
AMRC_INSUFFICIENT_MEMORY
17
AMRC_WAIT_TIME_READ_ONLY
18
AMRC_SERVICE_NOT_FOUND
MQSeries API Reason Codes (Continued) A-3
Reason Code Number 19
Reason Code Name AMRC_MSG_NOT_FOUND
Description The specified message ws not found, so the request was not carried out. The specified policy was not found, so the request was not carried out. The specified name could not be resolved to a unique sender because more than one sender object with that name exists. The specified name could not be resolved to a unique receiver because more than one receiver object with that name exists. The specified name could not be resolved to a unique publisher because more than one publisher object with that name exists. The specified name could not be resolved to a unique subscriber because more than one subscriber object with that name exists. The specified name could not be resolved to a unique message because more than one message object with that name exists. The specified name could not be resolved to a unique policy because more than one policy with that name exists.
20
AMRC_POLICY_NOT_FOUND
21
AMRC_SENDER_NOT_UNIQUE
22
AMRC_RECEIVER_NOT_UNIQUE
23
AMRC_PUBLISHER_NOT_UNIQUE
24
AMRC_SUBSCRIBER_NOT_UNIQUE
25
AMRC_MSG_NOT_UNIQUE
26
AMRC_POLICY_NOT_UNIQUE
MQSeries API Reason Codes (Continued)
A-4
Reason Code Name AMRC_DIST_LIST_NOT_UNIQUE
Description The specified name could not be resolved to a unique distribution list because more than one distribution list with that name exists. The buffer pointer specified for receiving data was not valid. The buffer length specified for receiving data was not valid. The buffer pointer specified for sending data was not valid. The data length specified for sending data was not valid. The requested operation could not be performed because the specified service (sender, receiver, publisher, or subscriber) was open. The session was already closed (or terminated). Message data for a send operation was passed in an application data buffer or a file, and was also found in the specified message object. Data to be sent can be included in an application buffer or a message object, but not both. Similarly, data can be included in a file or a message object, but not both. If data is sent in an application buffer or file, the message object can be reset first to remove existing data.
28 29 30 31 32
AMRC_RECEIVE_BUFF_PTR_ERR AMRC_RECEIVE_BUFF_LEN_ERR AMRC_SEND_DATA_PTR_ERR AMRC_SEND_DATA_LEN_ERR AMRC_INVALID_IF SERVICE_OPEN
33 34
AMRC_SERVICE_ALREADY_OPEN AMRC_DATA_SOURCE_NOT_UNIQUE
A-5
Reason Code Name AMRC_NO_MSG_AVAILABLE
Description No message was available for a receive request after the specified wait time. The session was already open (or initialized). The session was already closed (or terminated). The specified element was not found. The specified element count pointer was not valid. The specified element name pointer was not valid. The specified element name length value was not valid. The specified element index value was not valid. The specified element pointer was not valid. The specified element structure was not valid. The structure id, version, or a reserved field contained an invalid value. At least one of the name (length and pointer) fields in the specified element structure was not valid. Ensure that the name length, pointer, and name string are valid.
36 37 38 39 40 41 42 43 44
AMRC_SESSION_ALREADY_OPEN AMRC_SESSION_ALREADY_CLOSED AMRC_ELEM_NOT_FOUND AMRC_ELEM_COUNT_PTR_ERR AMRC_ELEM_NAME_PTR_ERR AMRC_ELEM_NAME_LEN_ERR AMRC_ELEM_INDEX_ERR AMRC_ELEM_PTR_ERR AMRC_ELEM_STRUC_ERR
45
AMRC_ELEM_STRUC_NAME_ERR
A-6
Reason Code Name AMRC_ELEM_STRUC_VALUE_ERR
Description At least one of the value (length and pointer) fields in the specified element structure was not valid. Ensure that the value length, pointer, and value string are valid. At least one of the name buffer (length and pointer) fields in the specified element structure was not valid. At least one of the value buffer (length and pointer) fields in the specified structure was not valid. An error was reported by the underlying (MQSeries) message transport layer. The message transport reason code can be obtained by the secondary reason code value returned from a GetLastError request for the AMI object concerned. A warning was reported by the underlying (MQSeries) message transport layer. The message transport reason code can be obtained by the secondary reason code value returned from a GetLastError request for the AMI object concerned.
47
AMRC_ELEM_STRUC_NAME_BUFF_ ERR
48
AMRC_ELEM_STRUC_VALUE_BUFF_ ERR
49
AMRC_TRANSPORT_ERR
50
AMRC_TRANSPORT_WARNING
A-7
Reason Code Name AMRC_ENCODING_INCOMPLETE
Description The message contains mixed values for integer, decimal, and floating point encodings, one or more of which are undefined. The encoding value returned to the application reflects only the encoding values that were defined. The message contains mixed values for integer, decimal, and floating point encodings, one or more of which conflict. An encoding value of undefined was returned to the application. The specified encoding value was not valid. The begin request was not valid because there were no participating resource managers registered. A response sender service specified when attempting to receive a request message was not updated with reply-to information because the request message contained no reply-to information. An attempt to send a reply message using the response send will fail. The specified (sender, receiver, distribution list, publisher, or subscriber) service was already closed). The request failed because the session was not open.
52
AMRC_ENCODING_MIXED
53 54
AMRC_ENCODING_ERR AMRC_BEGIN_INVALID
55
AMRC_NO_REPLY_TO_INFO
56
AMRC_SERVICE_ALREADY_CLOSED
57
AMRC_SESSION_NOT_OPEN
A-8
Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Reason Code Number 58 59 60
Reason Code Name AMRC_DIST_LIST_INDEX_ERR AMRC_WAIT_TIME_ERR AMRC_SERVICE_NOT_OPEN
Description The specified distribution list index value was not valid. The specified wait-time value was not valid. The request failed because the specified (sender, receiver, distribution list, publisher, or subscriber) service was not open. The RFH header of the message was truncated. The RFH header of the message was not valid. The specified data length was not valid. The backout count of a received message was found to have exceeded its backout limit. The message was returned to the application. It could not be requeued to the backout requeue queue. The backout count of a received message was found to have exceeded its backout limit. The message was returned to the application. It could not be requeued to the backout requeue queue.
61 62 63 64
AMRC_HEADER_TRUNCATED AMRC_HEADER_INVALID AMRC_DATA_LEN_ERR AMRC_BACKOUT_REQUEUE_ERR
65
AMRC_BACKOUT_LIMIT_ERR
A-9
Reason Code Name AMRC_COMMAND_ALREADY_ EXISTS
Description A publish, subscribe, or unsubscribe command could not be added to the message because the message already contained a command element. If this message is generated from the high-level interface, it may mean that you have tried to use the same message name for sending and receiving publish/subscribe messages. It can also occur if the same message object is reused to send a message without being reset. An unexpected error occurred after a received message was removed from the underlying transport layer. The message was returned to the application. An unexpected error occurred after a message was successfully sent. Output information updated as a result of the send request should never occur. The specified sender service definition type was not valid for sending responses. To be valid for sending a response, a sender service must not have a repository definition, must have been specified as a response service when receiving a previous request message, and must not have been used for any purpose other than sending responses.
67
AMRC_UNEXPECTED_RECEIVE_ERR
68
AMRC_UNEXPECTED_SEND_ERR
70
AMRC_SENDER_USAGE_ERR
A-10 UniVerse BASIC Extensions
Reason Code Name AMRC_MSG_TRUNCATED
Description The received message that was returned to the application has been truncated. An error occurred while closing the session. The session is closed. The current data offset used for reading bytes from a message is not valid. A publish, subscribe, or unsubscribe command could not be added to the message because the message already contained an RFH header. The message requires a reset first, to remove existing data. The specified group status value was not valid. The specified message id length value was not valid. The specified message id pointer was not valid. The specified message id buffer length value was not valid. The specified message id buffer pointer was not valid. The specified message id length pointer was not valid. The specified correlation id length value was too long.
72
AMRC_CLOSE_SESSION_ERR
73
AMRC_READ_OFFSET_ERR
74
AMRC_RFH_ALREADY_EXISTS
75 76 77 78 79 80 81
AMRC_GROUP_STATUS_ERR AMRC_MSG_ID_LEN_ERR AMRC_MSG_ID_PTR_ERR AMRC_MSG_ID_BUFF_LEN_ERR AMRC_MSG_ID_BUFF_PTR_ERR AMRC_MSG_ID_LEN_PTR_ERR AMRC_CORREL_ID_LEN_ERR
A-11
Reason Code Number 82 83
Reason Code Name AMRC_CORREL_ID_PTR_ERR AMRC_CORREL_ID_BUFF_LEN_ERR
Description The specified correlation id pointer was not valid. The specified correlation id buffer length value was not valid. The specified correlation id buffer pointer was not valid. The specified correlation id pointer was not valid. The specified message format string was too long. The specified format pointer was not valid. The specified format buffer pointer was not valid. The specified format length pointer was not valid. The specified format buffer length value was not valid. The specified name buffer pointer was not valid. The specified name length pointer was not valid. The specified name buffer length value was not valid. The specified queue name length value was not valid. The specified queue name pointer was not valid.
84 85 86 87 88 89 90 91 92 93 94 95
AMRC_CORREL_ID_BUFF_PTR_ERR AMRC_CORREL_ID_LEN_PTR_ERR AMRC_FORMAT_LEN_ERR AMRC_FORMAT_PTR_ERR AMRC_FORMAT_BUFF_PTR_ERR AMRC_FORMAT_LEN_PTR_ERR AMRC_FORMAT_BUFF_LEN_ERR AMRC_NAME_BUFF_PTR_ERR AMRC_NAME_LEN_PTR_ERR AMRC_NAME_BUFF_LEN_ERR AMRC_Q_NAME_LEN_ERR AMRC_Q_NAME_PTR_ERR
Reason Code Name AMRC_Q_NAME_BUFF_PTR_ERR AMRC_Q_NAME_LEN_PTR_ERR AMRC_Q_NAME_BUFF_LEN_ERR
Description The specified queue name buffer pointer was not valid. The specified queue name length pointer was not valid. The specified queue name buffer length value was not valid. The specified wait time pointer was not valid. The specified coded character set id pointer was not valid. The specified encoding pointer was not valid. The specified definition type pointer was not valid. The specified coded character value was not valid. The specified data length pointer was not valid. The specified group status pointer was not valid. The specified data offset pointer was not valid. The response sender service handle specified when receiving a request message was not valid. The response receiver service handle specified when sending a request message was not valid.
99 100 101 102 103 104 105 106 107
AMRC_WAIT_TIME_PTR_ERR AMRC_CCSID_PTR_ERR AMRC_ENCODING_PTR_ERR AMRC_DEFN_TYPE_PTR_ERR AMRC_CCSID_ERR AMRC_DATA_LEN_PTR_ERR AMRC_GROUP_STATUS_PTR_ERR AMRC_DATA_OFFSET_PTR_ERR AMRC_RESP_SENDER_HANDLE_ERR
108
AMRC_RESP_RECEIVER_HANDLE_ ERR
Reason Code Name AMRC_NOT_AUTHORIZED
Description The user is not authorized by the underlying transport layer to perform the specified request. The underlying transport layer is not available. The unit of work has been backed out. The specified request failed because an attempt was made to send a message that was not in a group when the existing message group was incomplete. The specified request could not be performed because the service in the underlying transport layer is not enabled for send requests. The specified (sender, receiver, distribution list, publisher, or subscriber) service was already open. Data conversion of the received message was unsuccessful. The message was removed from the underlying message transport layer with the message data unconverted. The specified request could not be performed because the service in the underlying transport layer is not enabled for receive requests.
110 111 112
AMRC_TRANSPORT_NOT_ AVAILABLE AMRC_BACKED_OUT AMRC_INCOMPLETE_GROUP
113
AMRC_SEND_DISABLED
114
AMRC_SERVICE_FULL
115
AMRC_NOT_CONVERTED
116
AMRC_RECEIVE_DISABLED
Reason Code Name AMRC_GROUP_BACKOUT_LIMIT_ ERR
Description The backout count of a received message was found to have exceeded its backout limit. The message was returned to the application. It was not requeued to the backout requeue queue because it represented a single message within a group of more than one. The specified distribution list sender count pointer was not valid. A distribution list open or send was only partially successful and returned multiple different reason codes in its underlying sender services. The publish request was not successful because a response receiver service is required for registration and was not specified. The specified data pointer was not valid. The specified data buffer length value was not valid. The specified data buffer pointer was not valid. The definition type defined for the service point in the repository was inconsistent with the definition type of the underlying message transport queue object when it was opened.
118
AMRC_SENDER_COUNT_PTR_ERR
119
AMRC_MULTIPLE_REASONS
120
AMRC_NO_RESP_SERVICE
121 122 123 124
AMRC_DATA_PTR_ERR AMRC_DATA_BUFF_LEN_ERR AMRC_DATA_BUFF_PTR_ERR AMRC_DEFN_TYPE_ERR
Reason Code Name AMRC_BACKOUT_INVALID
Description The backout request was not valid. On OS/390 under CICS, IMS, or RRS, this can be due to calling the AMI backout functions rather than the transaction managers own functions. The commit request was not valid. On OS/390 under CICS, IMS, or RRS, this can be due to calling the AMI commit functions rather than the transaction managers own functions. The specified data offset value was not valid. A filesystem error occurred during a file transfer call. If this occurs, we recommend that the current unit of work be backed out. This will ensure that messages put to or received from the service are in a consistent state. The AMI was unable to receive the file as the current file disposition is new, and a file with the same name already exists on your system. The first message of the file transfer is returned to the application. If this occurs, we recommend that the current unit of work is backed out. This will ensure that the messages received from the service are in a consistent state.
126
AMRC_COMMIT_INVALID
127 128
AMRC_DATA_OFFSET_ERR AMRC_FILE_SYSTEM_ERR
129
AMRC_FILE_ALREADY_EXISTS
MQSeries API Reason Codes (Continued) A-16 UniVerse BASIC Extensions
Reason Code Name AMRC_REPORT_CODE_PTR_ERR AMRC_MSG_TYPE_PTR_ERR AMRC_FILE_FORMAT_CONVERTED
Description The specified report code pointer was not valid. The specified message type pointer was not valid. The AMI received a file successfully, but needed to convert between different file types. An example is from an OS/390 fixed-length data set to a UNIX file or between OS/390 datasets with different geometries. On a file send or receive operation, the entire file was not processed. We recommend that the current unit of work is backed out. This will ensure that the messages put to or received from the service are in a consistent state. The file supplied on a file send call could not be opened. Check that the file exists and that the application has read access to it. A message was received from the service, but it does not appear to have been sent as part of a (physical mode) file transfer operation. The message is returned to the application. The file name length passed in to a file transfer call was not valid.
133
AMRC_FILE_TRUNCATED
134
AMRC_FILE_NOT_FOUND
135
AMRC_NOT_A_FILE
136
AMRC_FILE_NAME_LEN_ERR
A-17
Reason Code Name AMRC_FILE_NAME_PTR_ERR
Description The file name pointer passed in to a file transfer call was not valid. The format of an MQRFH2 rules and formatting header of a received message was not valid. Warning: OS/390 V2 R9 (or later) is required to enable AMI publish subscribe or message element support under CICS. Ensure that your Language Environment installation is set up to use Unicode character conversion. See the OS/390 C/C++ Programming Guide for a list of the coded character sets supported under OS/390. Failure: The coded character set of name/value elements in the rules and formatting header of a received message, or that specified for passing elements between the application and the AMI, is not supported.
138
AMRC_RFH2_FORMAT_ERR
139
AMRC_CCSID_NOT_SUPPORTED
Reason Code Name AMRC_FILE_MSG_FORMAT_ERR
Description When using physical mode file transfer, only two message formats are allowed: AMFMT_STRING (for text mode transfer), and AMFMT_NONE (for binary mode transfer). When using logical mode file transfer, any message format may be used for messages generated from OS/390 datasets. On other platforms, and for HFS files on OS/390, only AMFMT_STRING and AMFMT_NONE can be used. The message is not a report message. At least one of the type (length and pointer) fields in the specified element structure was not valid. At least one of the type buffer (length and pointer) fields in the specified element structure was not valid. Ensure that the type length, pointer, and type string are valid. An application running under CICS on OS/390 tried to perform a file transfer operation, which is invalid in this environment.
141 142
AMRC_MSG_TYPE_NOT_REPORT AMRC_ELEM_STRUC_TYPE_ERR
143
AMRC_ELEM_STRUC_TYPE_BUFF_ ERR
144
AMRC_FILE_TRANSFER_INVALID
A-19
Reason Code Name AMRC_FILE_NOT_WRITTEN
Description The file used for a receive could not be opened. The first message of the file is returned to the application. If this occurs, we recommend that the current unit of work is backed out. This will ensure that the messages held on the service are in a consistent state. An attempt was made to send a file type that is not supported. Unsupported file types include OS/390 VSAM datasets, and OS/390 partitioned datasets (though an individual member of a PDS may be sent). The value of the buffer length parameter that is specified on a receive message request was negative. A policy handler library file name specified in the repository was not found in the handlers directory. A policy handler library that is specified by the repository attempted to register a function with an invalid function pointer value (for example, NULL). A policy handler library that is specified by the repository attempted to register a function with an invocation point value that was not valid.
146
AMRC_FILE_FORMAT_NOT_ SUPPORTED
147
AMRC_NEGATIVE_RECEIVE_BUFF_ LEN
148
AMRC_LIBRARY_NOT_FOUND
149
AMRC_LIBRARY_FUNCTION_PTR_ ERR
150
AMRC_LIBRARY_INV_POINT_ERR
Reason Code Name AMRC_LIBRARY_DUP_FUNCTION
Description A policy handler library that is specified by the repository attempted to register a function with an invocation point value that is already registered. An error was returned from a policy handler library invocation that occurred while processing the application function call. The policy handler reason code can be obtained by the secondary reason code value returned from a getlastError request for the AMI object concerned. A warning was returned from a policy handler library invocation that occurred while processing the application function call. The policy handler reason code can be obtained by the secondary reason code value returned from a getlastError request for the AMI object concerned. The specified report (or feedback) code value was not valid. The specified accept direct requests value was not valid. The specified accept direct requsts pointer was not valid. The specified accept truncated value was not valid.
152
AMRC_POLICY_HANDLER_ERR
153
AMRC_POLICY_HANDLER_ WARNING
154
AMRC_REPORT_CODE_ERR
201 202 203
AMRC_ACCEPT_DIRECT_ERR AMRC_ACCEPT_DIRECT_PTR_ERR AMRC_ACCEPT_TRUNCATED_ERR
A-21
Reason Code Number 204 205 206 207
Reason Code Name AMRC_ACCEPT_TRUNCATED_PTR_ ERR AMRC_ANON_ERR AMRC_ANON_PTR_ERR AMRC_APPL_GROUP_BUFF_LEN_ERR
Description The specified accept truncated pointer was not valid. The specified anonymous value was not valid. The specified anonymous pointer was not valid. The specified application group buffer length value was not valid. The specified application group buffer pointer was not valid. The specified application group length value was not valid. The specified application group length pointer was not valid. The specified application group pointer was not valid. The specified bind on open value was not valid. The specified bind on open pointer was not valid. The specified channel name buffer length value was not valid. The specified channel name buffer pointer was not valid. The specified channel name length value was not valid. The specified channel name length pointer was not valid.
208 209 210 211 212 213 214
AMRC_APPL_GROUP_BUFF_PTR_ERR AMRC_APPL_GROUP_LEN_ERR AMRC_APPL_GROUP_LEN_PTR_ERR AMRC_APPL_GROUP_PTR_ERR AMRC_BIND_ON_OPEN_ERR AMRC_BIND_ON_OPEN_PTR_ERR AMRC_CHL_NAME_BUFF_LEN_ERR
215 216 217
AMRC_CHL_NAME_BUFF_PTR_ERR AMRC_CHL_NAME_LEN_ERR AMRC_CHL_NAME_LEN_PTR_ERR
Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Reason Code Number 218 219 220 221 222 223 224 225 226 227
Reason Code Name AMRC_CHL_NAME_PTR_ERR AMRC_CLOSE_DELETE_ERR AMRC_CLOSE_DELETE_PTR_ERR AMRC_CONTEXT_ERR AMRC_CONTEXT_PTR_ERR AMRC_CONVERT_ERR AMRC_CONVERT_PTR_ERR AMRC_COUNT_ERR AMRC_COUNT_PTR_ERR AMRC_CUST_PARM_BUFF_LEN_ERR
Description The specified channel name pointer was not valid. The specified close delete value was not valid. The specified close delete pointer was not valid. The specified message context value was not valid. The specified message context pointer was not valid. The specified convert message value was not valid. The specified convert message pointer was not valid. The specified backout or retry count value was not valid. The specified backout or retry count pointer was not valid. The specified custom parameter buffer length value was not valid. The specified customer parameter buffer pointer was not valid. The specified custom parameter length value was not valid. The specified custom parameter length pointer was not valid. The specified custom parameter pointer was not valid.
228
AMRC_CUST_PARM_BUFF_PTR_ERR
229 230 231
AMRC_CUST_PARM_LEN_ERR AMRC_CUST_PARM_LEN_PTR_ERR AMRC_CUST_PARM_PTR_ERR
Reason Code Name AMRC_DLY_PERSISTENCE_ERR AMRC_DLY_PERSISTENCE_PTR_ERR
Description The specified delivery persistence value was not valid. The specified delivery persistence pointer was not valid. The specified distribution list support value was not valid. The specified distribution list support pointer was not valid. The specified message expiry value was not valid. The specified message expiry pointer was not valid. The specified file disposition value was not valid. The specified file disposition pointer was not valid. The specified file record length value was not valid. The specified file record length pointer was not valid. The specified group id group buffer length value was not valid. The specified group id buffer pointer was not valid. The specified group id length value was not valid. The specified group id length pointer was not valid.
234 235 236 237 238 239 240 241 242
AMRC_DST_SUPPORT_ERR AMRC_DST_SUPPORT_PTR_ERR AMRC_EXPIRY_ERR AMRC_EXPIRY_PTR_ERR AMRC_FILE_DISP_ERR AMRC_FILE_DISP_PTR_ERR AMRC_FILE_RCD_LEN_ERR AMRC_FILE_RCD_LEN_PTR_ERR AMRC_GROUP_ID_BUFF_LEN_ERR
243 244 245
AMRC_GROUP_ID_BUFF_PTR_ERR AMRC_GROUP_ID_LEN_ERR AMRC_GROUP_ID_LEN_PTR_ERR
Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Reason Code Number 246 247 248 249 250 251 252 253 254 255 256 257 258
Reason Code Name AMRC_GROUP_ID_PTR_ERR AMRC_HANDLE_POISON_MSG_ERR AMRC_HANDLE_POISON_MSG_PTR_ ERR AMRC_HANDLE_PTR_ERR AMRC_IMPL_OPEN_ERR AMRC_IMPL_OPEN_PTR_ERR AMRC_INFORM_IF_RET_ERR AMRC_INFORM_IF_RET_PTR_ERR AMRC_INTERVAL_ERR AMRC_INTERVAL_PTR_ERR AMRC_LEAVE_OPEN_ERR AMRC_LEAVE_OPEN_PTR_ERR AMRC_LOCAL_ERR
Description The specified group id pointer was not valid. The specified handle poison message value was not valid. The specified handle poison message pointer was not valid. The specified handle pointer was not valid. The specified implicit open value was not valid. The specified implicit open pointer was not valid. The specified inform if retained value was not valid. The specified inform if retained pointer was not valid. The specified retry interval value was not valid. The specified retry interval pointer was not valid. The specified leave open value was not valid. The specified leave open pointer was not valid. The specified publish or subscribe locally value was not valid. The specified publish or subscribe locally pointer was not valid.
259
AMRC_LOCAL_PTR_ERR
Reason Code Name AMRC_MCD_PARM_BUFF_LEN_ERR
Description The specified MCD parameter buffer length value was not valid. The specified MCD parameter buffer pointer was not valid. The specified MCD parameter length value was not valid. The specified MCD parameter length pointer was not valid. The specified MCD parameter pointer was not valid. The specified queue manager name buffer length value was not valid. The specified queue manager name buffer pointer was not valid. The specified queue manager name length value was not valid. The specified queue manager name length pointer was not valid. The specified queue manager name pointer was not valid. The specified message length value was not valid. The specified message length pointer was not valid. The specified message type value was not valid.
261 262 263 264 265
AMRC_MCD_PARM_BUFF_PTR_ERR AMRC_MCD_PARM_LEN_ERR AMRC_MCD_PARM_LEN_PTR_ERR AMRC_MCD_PARM_PTR_ERR AMRC_MGR_NAME_BUFF_LEN_ERR
266
AMRC_MGR_NAME_BUFF_PTR_ERR
267
AMRC_MGR_NAME_LEN_ERR
268
AMRC_MGR_NAME_LEN_PTR_ERR
269 270 271 272
AMRC_MGR_NAME_PTR_ERR AMRC_MSG_LEN_ERR AMRC_MSG_LEN_PTR_ERR AMRC_MSG_TYPE_ERR
Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Reason Code Number 273 274 275 276 277 278 279 280 281 282 283 284 285 286
Reason Code Name AMRC_NEW_CORREL_ID_ERR AMRC_NEW_CORREL_ID_PTR_ERR AMRC_NEW_PUBS_ONLY_ERR AMRC_NEW_PUBS_ONLY_PTR_ERR AMRC_PERSISTENCE_ERR AMRC_PERSISTENCE_PTR_ERR AMRC_PRIORITY_ERR AMRC_PRIORITY_PTR_ERR AMRC_PUB_ON_REQ_ERR AMRC_PUB_ON_REQ_PTR_ERR AMRC_PUB_OTHERS_ONLY_ERR AMRC_PUB_OTHERS_ONLY_PTR_ERR AMRC_READ_ONLY_ERR AMRC_READ_ONLY_PTR_ERR
Description The specified new correlation id value was not valid. The specified new correlation id pointer was not valid. The specified new publications only value was not valid. The specified new publications only pointer was not valid. The specified persistence value was not valid. The specified persistence pointer was not valid. The specified priority value was not valid. The specified priority pointer was not valid. The specified publish on request value was not valid. The specified publish on request pointer was not valid. The specified publish to others only value was not valid. The specified publish to others only pointer was not valid. The specified wait time read only value was not valid. The specified wait time read only pointer was not valid.
A-27
Reason Code Name AMRC_REMOVE_ALL_ERR
Description The specified remove all subscriptions value was not valid. The specified remove all subscriptions pointer was not valid. The specified report option value was not valid. The specified report option pointer was not valid. The specified retain publications value was not valid. The specified retain publications pointer was not valid. The specified segment message value was not valid. The specified segment message pointer was not valid. The specified sequence number value was not valid. The specified sequence number pointer was not valid. The specified name cannot be changed. The specified open shared value was not valid. The specified open shared pointer was not valid.
288
AMRC_REMOVE_ALL_PTR_ERR
289 290 291
AMRC_REPORT_OPTION_ERR AMRC_REPORT_OPTION_PTR_ERR AMRC_RETAIN_ERR
292
AMRC_RETAIN_PTR_ERR
293 294 295 296 297 298 299
AMRC_SEGMENT_ERR AMRC_SEGMENT_PTR_ERR AMRC_SEQ_NO_ERR AMRC_SEQ_NO_PTR_ERR AMRC_SET_NAME_INVALID AMRC_SHARED_ERR AMRC_SHARED_PTR_ERR
Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Reason Code Number 300 301 302 303 304 305 306
Reason Code Name AMRC_SND_TYPE_ERR AMRC_SND_TYPE_PTR_ERR AMRC_SRV_TYPE_ERR AMRC_SRV_TYPE_PTR_ERR AMRC_SPLIT_LOGICAL_ERR AMRC_SPLIT_LOGICAL_PTR_ERR AMRC_SUBS_POINT_BUFF_LEN_ERR
Description The specified sender type value was not valid. The specified sender type pointer was not valid. The specified service type value was not valid. The specified service type pointer was not valid. The specified split logical value was not valid. The specified split logical pointer was not valid. The specified subscription point buffer length value was not valid. The specified subscription point buffer pointer was not valid. The specified subscription point length value was not valid. The specified subscription point length pointer was not valid. The specified subscription point pointer was not valid. The specified suppress registration value was not valid. The specified suppress registration pointer was not valid.
307
AMRC_SUBS_POINT_BUFF_PTR_ERR
308
AMRC_SUBS_POINT_LEN_ERR
309
AMRC_SUBS_POINT_LEN_PTR_ERR
310 311 312
AMRC_SUBS_POINT_PTR_ERR AMRC_SUPPRESS_REG_ERR AMRC_SUPPRESS_REG_PTR_ERR
Reason Code Number 313 314 315
Reason Code Name AMRC_SYNCPOINT_ERR AMRC_SYNCPOINT_PTR_ERR AMRC_TCP_ADDR_BUFF_LEN_ERR
Description The specified sync point value was not valid. The specified sync point pointer was not valid. The specified TCP/IP address buffer length value was not valid. The specified TCP/IP address buffer pointer was not valid. The specified TCP/IP address length value was not valid. The specified TCP/IP address length pointer was not valid. The specified TCP/IP address pointer was not valid. The specified transport type value was not valid. The specified transport type pointer was not valid. The specified trusted value was not valid. The specified trusted pointer was not valid. The specified use correlation id value was not valid. The specified use correlation id pointer was not valid. The specified wait for whole group value was not valid.
316 317 318 319 320 321 322 323 324 325 326
AMRC_TCP_ADDR_BUFF_PTR_ERR AMRC_TCP_ADDR_LEN_ERR AMRC_TCP_ADDR_LEN_PTR_ERR AMRC_TCP_ADDR_PTR_ERR AMRC_TRP_TYPE_ERR AMRC_TRP_TYPE_PTR_ERR AMRC_TRUSTED_ERR AMRC_TRUSTED_PTR_ERR AMRC_USE_CORREL_ID_ERR AMRC_USE_CORREL_ID_PTR_ERR AMRC_WAIT_WHOLE_GROUP_ERR
Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Reason Code Number 327 328
Reason Code Name AMRC_WAIT_WHOLE_GROUP_PTR_ ERR AMRC_CON_INT_PROP_ID_ERR
Description The specified wait for whole group pointer was not valid. The specified connection integer property identifier was not valid. The specified connection string property identifier was not valid. The specified message integer property identifier was not valid. The specified message string property identifier was not valid. The specified policy integer property identifier was not valid. The specified policy string property identifier was not valid. The specified service integer property identifier was not valid. The specified service string property identifier was not valid. The requested operation could not be performed because the specified connection was open. The specified connection handle was not valid.
329
AMRC_CON_STR_PROP_ID_ERR
330
AMRC_MSG_INT_PROP_ID_ERR
331
AMRC_MSG_STR_PROP_ID_ERR
332
AMRC_POLICY_INT_PROP_ID_ERR
333
AMRC_POLICY_STR_PROP_ID_ERR
334
AMRC_SRV_INT_PROP_ID_ERR
335
AMRC_SRV_STR_PROP_ID_ERR
336
AMRC_INVALID_IF_CON_OPEN
337
AMRC_CON_HANDLE_ERR
A-31
Reason Code Name AMRC_INVALID_TRACE_LEVEL AMRC_CONN_NAME_NOT_FOUND
Description A specified trace level was not valid. The connection name obtained from the repository was not found in the local host file. The local host file with the specified name was not found. The local host file name was not valid. The value of the appropriate environment variable should be corrected. The contents of the local host file are not valid. The definition name that was specified when creating a policy was not found in the repository. The policy was created using default values. The definition name that was specified when creating a sender was not found in the repository. The sender was created using default values. The definition name that was specified when creating a receiver was not found in the repository. The receiver was created using default values. The definition name specified for creating a distribution list was not found in the repository. The object was not created.
402 403
AMRC_HOST_FILE_NOT_FOUND AMRC_HOST_FILENAME_ERR
404 405
AMRC_HOST_FILE_ERR AMRC_POLICY_NOT_IN_REPOS
406
AMRC_SENDER_NOT_IN_REPOS
407
AMRC_RECEIVER_NOT_IN_REPOS
408
AMRC_DIST_LIST_NOT_IN_REPOS
Reason Code Name AMRC_PUBLISHER_NOT_IN_REPOS
Description The definition name that was specified when creating a publisher was not found in the specified repository. The publisher was created using default values. The definition name that was specified when creating a subscriber was not found in the repository. The subscriber was created using default values. The name specified for creating an object was not found in the repository and is a reserved name that is not valid in a repository. The specified object was not created. The repository file name was not valid. The value of the appropriate environment variable should be corrected. A warning associated with the underlying repository data was reported.
410
AMRC_SUBSCRIBER_NOT_IN_REPOS
411
AMRC_RESERVED_NAME_IN_REPOS
414
AMRC_REPOS_FILENAME_ERR
415
AMRC_REPOS_WARNING
A-33
Reason Code Name AMRC_REPOS_ERR
Description An error was returned when initializing or accessing the respository. This can occur for any of the following reasons: The repository XML file (for instance, amt.xml) contains data that is not valid. The DTD file (amt.dtd) was not found or contains data that is not valid. The files needed to initialize the repository (located in directories intlFiles and locales) could not be located. Check that the DTD and XML files are valid and correctly located, and that the path settings for the local host and repository files are correct.
418
AMRC_REPOS_NOT_FOUND
The repository file was not found. The value of the appropriate environment variable should be corrected. An error occurred loading the transport library. A module was loaded for use as a repository file cache, but the module does not appear to be a valid repository cache. A module was loaded for use as a host file cache, but the module does not appear to be a valid host cache.
419 420
AMRC_TRANSPORT_LIBRARY_ERR AMRC_HOST_CACHE_ERR
421
AMRC_REPOS_CACHE_ERR
Reason Code Name AMRC_PRIMARY_HANDLE_ERR
Description The primary handle (that is, the first parameter) passed on the API call was not valid. The most probable reason for failure is that the handle passed is a synonym handle, which is not valid as the primary handle on any call to the AMI. Under the IMS environment, the current session has been marked as expired. Delete the current session and create a new one for the duration of this transaction. An AMI dtd file (amt.dtd) was not found with the xml repository file in the same directory. An error was encountered accessing the AMI repository information in the LDAP directory, or communicating with the LDAP server. The LDAP error code can be obtained from the secondary reason code value that is returned from a GetLastError request for the AMI object concerned. A field referenced in AMI Java code cannot be found in the AMI Java native library. This is probably due to an incompatibility between the AMI class files and the AMI Java library. (Not applicable to the C and C++ programming languages).
423
AMRC_SESSION_EXPIRED
424
AMRC_DTD_NOT_FOUND
425
AMRC_LDAP_ERR
500
AMRC_JAVA_FIELD_ERR
Reason Code Name AMRC_JAVA_METHOD_ERR
Description A method referenced in AMI Java code cannot be found in the AMI Java native library. This is probably due to an incompatibility between the AMI class files and the AMI Java library. (Not applicable to the C and C++ programming languages). A class referenced in AMI Java code cannot be found in the AMI Java native library. This is probably due to an incompatibility between the AMI class files and the AMI Java library. (Not applicable to the C and C++ programming languages). An unexpected error occurred when calling the AMI Java native library. This is probably due to an incompatibility between the AMI class files and the AMI Java library. (Not applicable to the C and C++ programming languages). An unexpected error occurred when creating an AMI Java object. This is probably due to an incompatibility between the AMI class files and the AMI Java library. (Not applicable to the C and C++ pogramming languages). The AMI Java code detected a null parameter that is not valid. (Not applicable to the C and C++ programming languages).
502
AMRC_JAVA_CLASS_ERR
503
AMRC_JAVA_JNI_ERR
504
AMRC_JAVA_CREATE_ERR
505
AMRC_JAVA_NULL_PARM_ERR
Appendix
The U2XMAP File
This Appendix describes the DTD for the U2XMAP file.

 <!ELEMENT U2XMAP (OPTIONS?, DATASOURCE*, TABLECLASSMAP+, RelatedTable*) > <!ATTLIST U2XMAP Version CDATA #FIXED "1.0"> <!ELEMENT OPTIONS (EmptyString?, DateFormat?, Cascade?, ExistRecord?, (IgnoreNameSpace | NameSpace*)) <!ELEMENT EmptyString EMPTY> <!ATTLIST EmptyString isNULL (ON|OFF) #REQUIRED> <!ELEMENT DateFormat EMPTY> <!ATTLIST DateFormat Format CDATA #REQUIRED> <!ELEMENT Cascade EMPTY> <!ELEMENT ExistRecord EMPTY> <!ATTLIST ExistRecord Action (Ignore | Replace | Append) #REQUIRED> <!ELEMENT IgnoreNameSpace EMPTY> <!ELEMENT NameSpace EMPTY> <!ATTLIST NameSpace Prefix NMTOKEN #IMPLIED URI CDATA #REQUIRED> <!ELEMENT DATASOURCE EMPTY> <!ATTLIST DATASOURCE Name CDATA #REQUIRED ODBCDataSource CDATA #REQUIRED Username CDATA #REQUIRED Password CDATA #REQUIRED> <!ELEMENT TABLECLASSMAP (GenerateID?, (CloumnMap | TableMap)*, OrderColumn*) <!ATTLIST TABLECLASSMAP MapName CDATA #REQUIRED StartNode CDATA #REQUIRED Action (Ignore | Replace | Append) #IMPLIED DataSource CDATA #IMPLIED
C:\Program Files\Adobe\FrameMaker7.0\UniVerse 10.2\basicext\AppB.fm 9/22/06
TableName CDATA #REQUIRED> <!ELEMENT GenerateID EMPTY> <!ATTLIST GenerateID Column CDATA #REQUIRED Xfield CDATA #IMPLIED SUBR CDATA #IMPLIED> <!ELEMENT ColumnMap EMPTY> <!ATTLIST ColumnMap Node CDATA #REQUIRED Column CDATA #REQUIRED Action (Ignore | Replace | Append) #IMPLIED> <!ELEMENT TableMap EMPTY> <!ATTLIST TableMap Node CDATA #REQUIRED MapName CDATA #IMPLIED> <!ELEMENT OrderColumn EMPTY> <!ATTLIST OrderColumn Column CDATA #REQUIRED Generate (Yes | No) #REQUIRED>
<!ELEMENT RelatedTable (MapParentKey, ForeignKey)> <!ELEMENT MapParentKey EMPTY> <!ATTLIST MapParentKey Table CDATA #REQUIRED Column CDATA #REQUIRED Generate (Yes | No) #REQUIRED> <!ELEMENT MapChildKey EMPTY> <!ATTLIST MAPForeignKey Table CDATA #REQUIRED Column CDATA #REQUIRED>
Mapping Root
The U2XMAP element is the root element type of the mapping file document.
<!ELEMENT U2XMAP (OPTIONS?, TABLECLASSMAP+> <!ATTLIST U2XMAP Version CDATA #FIXED "1.0">
The element has three child elements: OPTIONS TABLECLASSMAP RelatedTable
B-2 UniVerse BASIC Extensions
Options
<!ELEMENT OPTIONS (EmptyString?, DateFormat?, Cascade?, ExistRecord?, (IgnoreNameSpace | NameSpace*))
Options are a container to hold the various options you can set.
Option EmptyString
<!ELEMENT EmptyString EMPTY> <!ATTLIST EmptyString isNULL (ON|OFF) #REQUIRED>
If the attribute isNull in EmptyString is ON, when the value of an optional XML element is omitted, the corresponding database field value is set to NULL, otherwise it is considered missing. Similarly, when a database field value is NULL and the attribute isNULL in EmptyString is ON, the corresponding value of an optional XML element is omitted, otherwise it is set to an empty string.
Option DateFormat
<!ELEMENT DateFormat EMPTY> <!ATTLIST DateFormat Format CDATA #REQUIRED>
Format is a conversion code UniVerse uses to perform the ICONV()/OCONV() function when getting the data from the XML document or creating the XML document. This code can be any conversion code understood by UniVerse. You can also use the value of XMLFormat which converts the data into a standard data format for the XML document, or takes the standard XML data format (yyyy-mmdd).
Option Cascade
<!ELEMENT Cascade EMPTY>
The U2XMAP dataset can define whether to use the cascade mode or not. This option only applies when an XML document is mapped to more than one UniVerse table. By default, the cascade mode is off, which means that the system takes care of the parent-child record relationship according to the ReleatedTable rules described in the U2XMAP file. Setting the cascade mode ON allows a user to control the parent-child record relationship. When the cascade mode is ON, once the current parent table record is established, all child table records that are either read from or written to the child table are associated with the current parent table record. This affords a user the freedom of associating parent and child table records the way he or she sees fit.
B-3
Option ExistRecord
<!ELEMENT ExistReocrd EMPTY> <!ATTLIST ExistRecord Action (Ignore | Replace | Append) #REQUIRED>
Use the ExistRecord option to specify the action when a record ID from the XML document already exists in the UniVerse file. When you specify Ignore the XML.TODB command will not change the record with the same record ID. If you specify Replace XML.TODB replaces the existing record ID. If you specify Append XML.TODB appends the value from the XML document to the multivalued or multi-subvalued filed in the UniVerse file if the record already exists in the database. For example, assume STUDENT (ID=12345) exists in the UniVerse file with COURSES C1, C2, and C3. Further assume that the same STUDENT ID exists in the XML document with COURSES C4 and C5. If ExistRecord is Ignore, the existing student record remains unchanged. In ExistRecord is Replace, XML.TODB replaces the existing record with the record from the XML document, so the COURSES field becomes C4 and C5. If ExistRecord is Append, XML.TODB appends course C4 and C5 to the COURSES field, so the COURSES field contains COURSES C1, C2, C3, C4, and C5. Note: Append is only valid with multivalued fields. If specified with a singlevalued field, it is ignored.
Option Namespace
<!ELEMENT NameSpace EMPTY> <!ATTLIST NameSpace Prefix NMTOKEN #IMPLIED URI CDATA #REQUIRED> <!ELEMENT IgnoreNameSpace EMPTY>
<IgnoreNameSpace> means UniVerse ignores all the Namespace information This option applies when converting the XML document to the UniVerse database. Namespace elements give URIs and their associated prefixes. These are used as follows: In the mapping document, prefixes identify to which namespace an element or attribute belongs. They can be used in the Name attribute of the ElementType and Attribute element types.
When transferring data from an XML document to the UniVerse database, UniVerse uses namespace URIs to identify elements and attributes in that document. The XML document can use different prefixes than are used in the mapping document. When transferring data from the UniVerse database to an XML document, namespace URIs and prefixes are used to prefix element and attribute names in that document. Namespace elements are not required. If they are used, the same URI or prefix cannot be used more than once. Zero-length prefixes ("") are not currently supported. If you do not define a Prefix, UniVerse uses the Default Name space, used only for generating the XML document. In this case, UniVerse puts a default NameSpace in the output document.
Table Class Maps

<!ELEMENT TABLECLASSMAP (GenerateID?, (CloumnMap | TableMap)*, OrderColumn*) <!ATTLIST TABLECLASSMAP MapName CDATA #REQUIRED StartNode CDATA #REQUIRED Action (Ignore | Replace | Append) #IMPLIED DataSource CDATA #IMPLIED TableName CDATA #REQUIRED>
<TABLECLASSMAP> elements instruct the data transfer system to map an XML element to a database file. So, if you have more than one such element, the data transfer system puts records into more than one database file. Basically, the properties in this element map to the column in the database file. You cannot pull the properties in other elements to map to this database table. <MapName> is the given name for this <TABLECLASSMAP>. It can be referenced when you define the relationship of the tables. <StartNode> is the start element in the XML document tree. If this map is under other <TABLECLASSMAP>, this will be a related path. <TableName> is the database file name. <Action> can overwrite the global action for an existing record. You can specify own action for this table only.
B-5
Element <GenerateID>
<!ELEMENT GenerateID EMPTY> <!ATTLIST GenerateID Column CDATA #REQUIRED Xfield CDATA #IMPLIED SUBR CDATA #IMPLIED>
The <GenerateID> elements instruct the data transfer system to create an ID for the record if a unique ID cannot be found. If you specify Xfield, UniVerse uses the value from the field in the dictionary for the file as the ID, adds 1, and writes the record back to the dictionary. If you specify SUBR, UniVerse calls this subroutine to obtain an ID for the current record. The subroutine must be cataloged, and have one parameter defining the return value for the ID. If you do not specify Xfield or SUBR, XML.TODB automatically generates a unique ID for the record.
Element <ColumnMap>
<!ELEMENT ColumnMap EMPTY> <!ATTLIST ColumnMap Node CDATA #REQUIRED Action (Ignore | Replace | Append) #IMPLIED Column CDATA #REQUIRED>
<ColumnMap> elements instruct the data transfer system to transfer the data between a certain XML document node and the database file field. The value of <Node> is a U2 xpath (subset of the 'xpath' with some extension). The value of <Column> is the field name in the database file. <Action> can overwrite the global action for Existed Record". You can specify your own action for this field only.
Element <TableMap>
<!ELEMENT ColumnMap EMPTY> <!ATTLIST TableMap Node CDATA #REQUIRED MapName CDATA #IMPLIED>
<TableMap> elements instruct the data transfer system where to put this subset of data in the XML document. It also instructs the system that this map is the child map of the current map. The value of <Node> is a U2 xpath (subset of the 'xpath' with some extension). The value of <MapName> is the MAP name in this map file.
Element <OrderColumn>
<!ELEMENT OrderColumn EMPTY> <!ATTLIST OrderColumn Column CDATA #REQUIRED Generate (Yes | No) #REQUIRED>
UniVerse uses <OrderColumn> elements to store information about the order in which elements and PCDATA occur in their parent element. Storing order information is optional. If you do not store it, there is no guarantee that the order will be preserved in a round trip from an XML document to the database and back again. The Generate attribute of the OrderColumn element tells the system whether to generate order information or not. The presence or absence of the OrderColumn element tells the system whether to use order information. If you do not generate order information, you must map another column to the order column.
Related Table Maps

<!ELEMENT RelatedTable MapParentKey, MapChildKey> <!ATTLIS RelatedTable MapName CDATA #REQUIRED Generate (Yes | No) #REQUIRED> <!ELEMENT MapParentKey EMPTY> <!ATTLIST Column CDATA #REQUIRED> <!ELEMENT MapChildKey EMPTY> <!ATTLIST Column CDATA #REQUIRED>
<RelatedTable> elements state the relationship between 2 maps or files. In class terms, think of this as a property added to the class being defined that points to the related class. In XML terms, this means that the element type for the related class is a child of the element type for the class being defined. This element tells the data transfer system the relationship of these two tables. The keys are used to join these two tables.
B-7
B C
M N O
V W
Index
Index
A
Additional Reading MQSeries Application Messaging Interface 3-47 MQSeries Application Programming Guide 3-47 MQSeries Clients 3-47 MQSeries Primer 3-47 AIX 3-12 AMCC_FAILED amInitialize 3-20 amReceiveMsg 3-23 amReceiveRequest 3-27 amSendMsg 3-30 amSendRequest 3-32 amSendResponse 3-34 amTerminate 3-36 AMCC_SUCCESS amInitialize 3-20 amReceiveMsg 3-23 amReceiveRequest 3-27 amSendMsg 3-30 amSendRequest 3-32 amSendResponse 3-34 amTerminate 3-36 AMCC_WARNING amInitialize 3-20 amReceiveMsg 3-23 amReceiveRequest 3-27 amSendMsg 3-30 amSendRequest 3-32 amSendResponse 3-34 amTerminate 3-36 amInitialize Function 3-19 amReceiveMsg 3-10, 3-11, 3-23
Function 3-21 amReceiveRequest 3-10, 3-11 Function 3-25 amSendMsg 3-10 amSendRequest 3-9, 3-10, 3-11 Function 3-29, 3-31 amSendResponse 3-10, 3-11 Function 3-33 amTerminate Function 3-35 appName amInitialize 3-19 attribute-centric mapping mode 4-4, 54 attribute-centric mode creating XML documents from multiple files 4-41, 5-41 processing UniVerse SQL statements 4-38, 5-38 attribute-centric XML document creating 4-22, 5-22
C
Client Channel Name 3-16 Client Request/Response Functions 310 Client TCP Server Address 3-16 Configurations 3-14 Configure the AMI policy 3-16 Connection Type 3-16 creating attribute-centric XML document 422, 5-22 attribute-centric XML document from multiple files 4-41, 5-41
C:\Program Files\Adobe\FrameMaker7.0\UniVerse 10.2\basicext\BasicExtIX.fm
C:\Program Files\Adobe\FrameMaker7.0\UniVerse 10.2\basicext\BasicExtIX.fm A B C D E F G H I J K L M N O P Q R S T U V W X Y Z @
element-centric XML document 425, 5-25 element-centric XML document from multiple files 4-47, 5-47 mixed-mode XML document 4-27, 5-27 XML document from multiple files using mapping file 4-56, 5-56 XML document from multiple files with DTD 4-53, 5-53 XML document from multiple files with multivalues 4-49, 5-49 XML document from RetrieVe 4-4, 5-4 XML document with DTD 4-31, 531 XML document with UniVerse SQL 4-36, 5-36 &XML& file 4-4, 4-36, 5-4, 5-36
E
element-centric mapping mode 4-5, 55 element-centric mode creating XML document from multiple files 4-47, 5-47 processing UniVerse SQL statements 4-39, 5-39 element-centric XML document creating 4-25, 5-25 Enabling WebSphere MQ Support in UniData on UNIX AIX 3-13 HP-UX 3-13 Sun Solaris 3-13 encoding mapping file 4-17, 5-17 Examples Request/Response Messaging 3-37 Retrieving a Message 3-37 Sample Request/Response Client 339 Sample Request/Response Server 343 Sending a Message 3-37
D
data amReceiveMsg 3-21 amReceiveRequest 3-25 amSendMsg 3-29 amSendRequest 3-31 amSendResponse 3-33 Datagram Messaging Style 3-10 dataLen amReceiveMsg 3-21 amReceiveRequest 3-25 amSendRequest 3-31 amSendResponse 3-33 Disabling WebSphere MQ Support in UniData on UNIX 3-14 Document Object Model definition 4-3, 5-3 DTD creating XML document from multiple files with 4-53, 5-53 creating XML document with 4-31, 5-31 definition 4-2, 5-2
H
HP-UX 3-12 hSession amInitialize 3-19 amReceiveMsg 3-21 amReceiveRequest 3-25 amSendRequest 3-29, 3-31 amSendResponse 3-33 amTerminate 3-35
conversion code considerations 417, 5-17 creating XML document from multiple files with 4-56, 5-56 encoding 4-17, 5-17 example 4-18, 5-18 format 4-6, 5-6 formatting considerations 4-17, 5-17 mapping mode attribute-centric 4-4, 5-4 element-centric 4-5, 5-5 mixed 4-5, 5-5 maxMsgLen amReceiveMsg 3-21 amReceiveRequest 3-25 Message Objects 3-9 message queue definition 3-5 Messaging Styles 3-10 mixed mapping mode 4-5, 5-5 mixed-mode XML document creating 4-27, 5-27 MQSeries AMI SupportPac Install 3-16 MQSeries Client Install 3-16 multiple tables processing for XML document 4-38, 5-38 multivalued fields creating XML document from multiple files with 4-49, 5-49
P
Platform Availability Installation 3-12 Policies 3-9 policyName amInitialize 3-19 amReceiveMsg 3-21 amReceiveRequest 3-25 amSendMsg 3-29 amSendRequest 3-31 amSendResponse 3-33 amTerminate 3-35
I
IBM Publications Center 3-3
M
mapping file
Index
ii
C:\Program Files\Adobe\FrameMaker7.0\UniVerse 10.2\basicext\BasicExtIX.fm A B C D E F G H I J K L M N O P Q R S T U V W X Y Z @
Q
queue manager definition 3-6
R
rcvMsgName amReceiveMsg 3-22 amReceiveRequest 3-25 amSendResponse 3-33 reasonCode amInitialize 3-19 amReceiveMsg 3-22 amReceiveRequest 3-26 amSendMsg 3-29 amSendRequest 3-31 amSendResponse 3-33 amTerminate 3-35 receiverName amReceiveMsg 3-21 amReceiveRequest 3-25 Request/Response Functions client 3-10 server 3-10 Request/Response Messaging Style 310 Requirements Installation 3-12 responseName amSendRequest 3-31
amSendResponse 3-33 Server Request/Response Functions 310 Services 3-8 Session 3-8 Setting up the Environment for UniData and WebSphere MQ 3-12 Setup a Listener for the Queue Manager on the Remote Machine 3-17 sndMsgName amSendMsg 3-29 amSendRequest 3-31 amSendResponse 3-33 SUN Solaris 3-12
U
U2AMI_ERR_SESSION_IN_USE amInitialize 3-20 UniVerse SQL creating XML document with 4-36, 5-36 xml limitations 4-39, 5-39
W
WebSphere MQ API for UniData and UniVerse 3-3 Windows NT/2000 3-12
X S
SELECT statement creating XML document with 4-36, 5-36 processing multiple tables for XML documents 4-38, 5-38 SELECT statements processing rules for XML documents 4-38, 5-38 selMsgName amReceiveMsg 3-21 senderName amReceiveRequest 3-26 amSendMsg 3-29 amSendRequest 3-31 XML limitations in UniVerse SQL 4-39, 539 XML document creating from RetrieVe 4-4, 5-4 valid 4-3, 5-3 well-formed 4-3, 5-3 XML documents SELECT statement processing rules 4-38, 5-38
Symbols
&XML& file 4-4, 5-4 creating 4-36, 5-36
iii UniVerse BASIC

Basic Ext

Uploaded by

Basic Ext

Uploaded by

C:\Program Files\Adobe\FrameMaker7.0\UniVerse 10.

2\basicext\Front September 22, 2006 4:10 pm

UniVerse BASIC Extensions

Version 10.2 September, 2006

C:\Program Files\Adobe\FrameMaker7.0\UniVerse 10.2\basicext\Front September 22, 2006 4:10 pm

Using the Socket Interface

C:\Program Files\Adobe\FrameMaker7.0\UniVerse 10.2\basicext\BasicExtTOC.fm (bookTOC.template) September 22, 2006 3:24 pm

Using WebSphere MQ with UniVerse

Creating XML Documents

iv UniVerse BASIC Extensions

Receiving XML Documents

The Simple Object Access Protocol

The Document Object Model

vi UniVerse BASIC Extensions

XDOMGetNodeType . . XDOMGetAttribute . . . XDOMGetOwnerDocument XDOMGetUserData . . . XDOMSetNodeValue . . XDOMSetUserData . . . XMLGetError . . . . .

7-36 7-37 7-38 7-39 7-40 7-41 7-42

Data Transfer Between XML Documents and UniVerse Files

The XML/DB Tool

Table of Contents vii

9-36 9-36 9-36 9-37 9-38 9-39 9-41 9-43

viii UniVerse BASIC Extensions

C:\Program Files\Adobe\FrameMaker7.0\UniVerse 10.2\basicext\Preface 9/22/06

Courier Courier Bold

C:\Program Files\Adobe\FrameMaker7.0\UniVerse 10.2\basicext\Preface 9/22/06

UniVerse BASIC Extensions

C:\Program Files\Adobe\FrameMaker7.0\UniVerse 10.2\basicext\Preface 9/22/06

xiv UniVerse BASIC Extensions

C:\Program Files\Adobe\FrameMaker7.0\UniVerse 10.2\basicext\Preface 9/22/06

xvi UniVerse BASIC Extensions

1Administering UniData on Windows NT or Windows 2000 0

Using the Socket Interface

C:\Program Files\Adobe\FrameMaker7.0\UniVerse 10.2\basicext\Ch1.fm 9/22/06

1-2 UniVerse BASIC Extensions

Socket Function Error Return Codes

2 - SCK_ENETDOWN 3 - SCK_EFAULT 4 - SCK_ENOTCONN 5 - SCK_EINTR 6 - SCK_EINPROGRESS

8 - SCK_EMFILE 9 - SCK_ENOBUFS 10 - SCK_ENOTSOCK

C:\Program Files\Adobe\FrameMaker7.0\UniVerse 10.2\basicext\Ch1.fm 9/22/06

Error Code 11 - SCK_EOPNOTSUPP 12 - SCK_EWOULDBLOCK 13 - SCK_ENETRESET

Error Code 22 - SCK_ESYSNOTREADY 23 -SCK_EVER NOTSUPPORTED

Socket Function Error Return Codes (Continued)

C:\Program Files\Adobe\FrameMaker7.0\UniVerse 10.2\basicext\Ch1.fm 9/22/06

1-6 UniVerse BASIC Extensions

Getting a Socket Error Message

The following table describes the return status of each mode.

C:\Program Files\Adobe\FrameMaker7.0\UniVerse 10.2\basicext\Ch1.fm 9/22/06

The following table describes the return status of each mode.

1-8 UniVerse BASIC Extensions

Opening a Secure Socket

C:\Program Files\Adobe\FrameMaker7.0\UniVerse 10.2\basicext\Ch1.fm 9/22/06

The following table describes the return status of each mode.

UniVerse BASIC Extensions

C:\Program Files\Adobe\FrameMaker7.0\UniVerse 10.2\basicext\Ch1.fm 9/22/06

Getting Information From a Socket

UniVerse BASIC Extensions

following table describes the status of each return code.

C:\Program Files\Adobe\FrameMaker7.0\UniVerse 10.2\basicext\Ch1.fm 9/22/06

Reading From a Socket

UniVerse BASIC Extensions

The following table describes the return status of each mode.

The following table describes the status of each return code.

C:\Program Files\Adobe\FrameMaker7.0\UniVerse 10.2\basicext\Ch1.fm 9/22/06

The following table describes the return status of each mode.

UniVerse BASIC Extensions

The following table describes the status of each return code.

C:\Program Files\Adobe\FrameMaker7.0\UniVerse 10.2\basicext\Ch1.fm 9/22/06

Setting the Value for a Socket Option

UniVerse BASIC Extensions

The following table describes the status of each return code.

C:\Program Files\Adobe\FrameMaker7.0\UniVerse 10.2\basicext\Ch1.fm 9/22/06

Getting the Value of a Socket Option

UniVerse BASIC Extensions

C:\Program Files\Adobe\FrameMaker7.0\UniVerse 10.2\basicext\Ch1.fm 9/22/06

The following table describes the status of each return code.

UniVerse BASIC Extensions

Initializing a Server Side Socket Connection

port backlog svr_socket