UniVerse 10.3 New Features · UniVerse 10.3 New Features 3 The above trademarks are property of the specified companies in the United States, other countries, or both. All other products

C:\Program Files\Adobe\FrameMaker8\UniVerse 10.3\10.3rebranded\newfeatures\Front.fmMarch 18, 2010 2:41 pm

Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta

UniVerse

10.3 New Features

UNV-103-NEWF-1

2 UniVerse 10.3 Ne

C:\Program Files\Adobe\FrameMaker8\UniVerse 10.3\10.3rebranded\newfeatures\Front.fmMarch 18, 2010 2:41 pm

Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta

Notices

EditionPublication date: February 2009Book number: UNV-103-NEWF-1Product version: UniVerse 10.3

Copyright© Rocket Software, Inc. 1985-2009. All Rights Reserved.

TrademarksThe following trademarks appear in this publication:

Trademark Trademark Owner

Rocket Software™ Rocket Software, Inc.

Dynamic Connect® Rocket Software, Inc.

RedBack® Rocket Software, Inc.

SystemBuilder™ Rocket Software, Inc.

UniData® Rocket Software, Inc.

UniVerse™ Rocket Software, Inc.

U2™ Rocket Software, Inc.

U2.NET™ Rocket Software, Inc.

U2 Web Development Environment™ Rocket Software, Inc.

wIntegrate® Rocket Software, Inc.

Microsoft® .NET Microsoft Corporation

Microsoft® Office Excel®, Outlook®, Word Microsoft Corporation

Windows® Microsoft Corporation

Windows® 7 Microsoft Corporation

Windows Vista® Microsoft Corporation

Java™ and all Java-based trademarks and logos Sun Microsystems, Inc.

UNIX® X/Open Company Limited

w Features

The above trademarks are property of the specified companies in the United States, other countries, or both. All other products or services mentioned in this document may be covered by the trademarks, service marks, or product names as designated by the companies who own or market them.

License agreementThis software and the associated documentation are proprietary and confidential to Rocket Software, Inc., are furnished under license, and may be used and copied only in accordance with the terms of such license and with the inclusion of the copyright notice. This software and any copies thereof may not be provided or otherwise made available to any other person. No title to or ownership of the software and associated documentation is hereby transferred. Any unauthorized use or reproduction of this software or documentation may be subject to civil or criminal liability. The information in the software and documentation is subject to change and should not be construed as a commitment by Rocket Software, Inc.

Restricted rights notice for license to the U.S. Government: Use, reproduction, or disclosure is subject to restrictions as stated in the “Rights in Technical Data-General” clause (alternate III), in FAR section 52.222-14. All title and ownership in this computer software remain with Rocket Software, Inc.

NoteThis product may contain encryption technology. Many countries prohibit or restrict the use, import, or export of encryption technologies, and current use, import, and export regulations should be followed when exporting this product.

Please be aware: Any images or indications reflecting ownership or branding of the product(s) documented herein may or may not reflect the current legal ownership of the intellectual property rights associated with such product(s). All right and title to the product(s) documented herein belong solely to Rocket Software, Inc. and its subsidiaries, notwithstanding any notices (including screen captures) or any other indications to the contrary.

Contact informationRocket Software275 Grove Street Suite 3-410Newton, MA 02466-2272 USA Tel: (617) 614-4321 Fax: (617) 630-7100Web Site: www.rocketsoftware.com

UniVerse 10.3 New Features 3

http://www.rocketsoftware.com

http://www.rocketsoftware.com

Table of Contents

:\ProgMarch

Table of Contents

Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta

Chapter 1 Automatic Data EncryptionEncrypted File Types . . . . . . . . . . . . . . . . 1-3Encryption With UniVerse Replication . . . . . . . . . . . 1-3

Key Store . . . . . . . . . . . . . . . . . . . . . 1-4How Encryption Works . . . . . . . . . . . . . . . . . 1-5Defining a Master Key . . . . . . . . . . . . . . . . . 1-7

Upgrading to UniVerse 10.3 from UniVerse 10.2. . . . . . . . 1-8Changing a Master Key After Data is Encrypted . . . . . . . . 1-9

UniVerse Encryption Algorithms . . . . . . . . . . . . . . 1-12Encryption Commands . . . . . . . . . . . . . . . . . 1-13

CREATE.ENCRYPTION.KEY . . . . . . . . . . . . . 1-13DELETE.ENCRYPTION.KEY . . . . . . . . . . . . . 1-14LIST.ENCRYPTION.KEY . . . . . . . . . . . . . . 1-14GRANT.ENCRYPTION.KEY . . . . . . . . . . . . . 1-15REVOKE.ENCRYPTION.KEY . . . . . . . . . . . . . 1-16ENCRYPT.FILE . . . . . . . . . . . . . . . . . . 1-17DECRYPT.FILE . . . . . . . . . . . . . . . . . . 1-19LIST.ENCRYPTION.FILE . . . . . . . . . . . . . . 1-20ACTIVATE.ENCRYPTION.KEY . . . . . . . . . . . . 1-21DEACTIVATE.ENCRYPTION.KEY . . . . . . . . . . . 1-21DISABLE.DECRYPTION . . . . . . . . . . . . . . 1-22ENABLE.DECRYPTION . . . . . . . . . . . . . . . 1-23

UniVerse BASIC Encryption Commands. . . . . . . . . . . . 1-24ACTIVATEKEY . . . . . . . . . . . . . . . . . . 1-24DEACTIVATEKEY. . . . . . . . . . . . . . . . . 1-25DISABLEDEC . . . . . . . . . . . . . . . . . . 1-26ENABLEDEC . . . . . . . . . . . . . . . . . . 1-28STATUS Function Changes . . . . . . . . . . . . . . 1-29

The encman Utility . . . . . . . . . . . . . . . . . . 1-31Viewing Audit Trail Information . . . . . . . . . . . . . 1-31

ram Files\Adobe\FrameMaker8\UniVerse 10.3\10.3rebranded\newfeatures\newfeaturesTOC.fm (bookTOC.template)18 2010 1:50 pm

Generating a Key Store . . . . . . . . . . . . . . . . 1-32Removing a Key Store . . . . . . . . . . . . . . . . 1-33Importing and Exporting Metadata . . . . . . . . . . . . 1-33Resynching Tags . . . . . . . . . . . . . . . . . . 1-35

Using UniAdmin for Encryption . . . . . . . . . . . . . . 1-38Encryption Wallet Management . . . . . . . . . . . . . 1-43

Chapter 2 XML EncodingXML for IBM UniVerse . . . . . . . . . . . . . . . . . 2-3

Document Type Definitions . . . . . . . . . . . . . . 2-4XML Schema . . . . . . . . . . . . . . . . . . . 2-4The Document Object Model (DOM) . . . . . . . . . . . 2-4Well-Formed and Valid XML Documents . . . . . . . . . . 2-5

Creating an XML Document from RetrieVe . . . . . . . . . . . 2-6Create the &XML& File . . . . . . . . . . . . . . . 2-6Mapping Modes . . . . . . . . . . . . . . . . . . 2-6XML Configuration File . . . . . . . . . . . . . . . 2-14xmlconfig Parameters . . . . . . . . . . . . . . . . 2-15The Mapping File . . . . . . . . . . . . . . . . . 2-23Distinguishing Elements . . . . . . . . . . . . . . . 2-25Root Element Attributes . . . . . . . . . . . . . . . 2-25Association Elements . . . . . . . . . . . . . . . . 2-32Mapping File Example . . . . . . . . . . . . . . . . 2-33How Data is Mapped . . . . . . . . . . . . . . . . 2-37Mapping Example . . . . . . . . . . . . . . . . . 2-39

TCL Commands for XML . . . . . . . . . . . . . . . . 2-41Session-level TCL Commands . . . . . . . . . . . . . 2-41XMLSETOPTIONS . . . . . . . . . . . . . . . . . 2-41XMLGETOPTIONS. . . . . . . . . . . . . . . . . 2-43XMLGETOPTIONVALUE . . . . . . . . . . . . . . 2-44Existing TCL Command Affected by XMLSETOPTIONS Command or

XMLSetOptions() API . . . . . . . . . . . . . 2-45Creating an XML Document Using RetrieVe . . . . . . . . . . 2-47

Examples . . . . . . . . . . . . . . . . . . . . 2-48Creating an XML Document with UniVerse SQL . . . . . . . . . 2-57

Processing Rules for UniVerse SQL SELECT Statements . . . . . 2-58XML Limitations in UniVerse SQL . . . . . . . . . . . . 2-59Examples . . . . . . . . . . . . . . . . . . . . 2-60

Creating an XML Document Through UniVerse Basic . . . . . . . 2-69Using the XMLExecute() Function . . . . . . . . . . . . 2-70

Table of Contents v

vi UniV

XMLSetOptions . . . . . . . . . . . . . . . . . 2-73XMLGetOptions . . . . . . . . . . . . . . . . . 2-75XMLGetOptionValue . . . . . . . . . . . . . . . . 2-76Existing APIs Affected by XML Options . . . . . . . . . . 2-91

UniVerse Basic Example . . . . . . . . . . . . . . . . 2-119

Chapter 3 IBM U2 Web Services Developer DeploymentExporting Web Services . . . . . . . . . . . . . . . 3-3Deploying the SOAP Server . . . . . . . . . . . . . . 3-5Define Security between the Client and the SOAP Server . . . . 3-10Set Connection Properties . . . . . . . . . . . . . . 3-12Define UniVerse Database Connection Security. . . . . . . . 3-15

Running and Stopping the SOAP Server . . . . . . . . . . . 3-18Monitoring a Remote SOAP Server . . . . . . . . . . . . . 3-19

Chapter 4 Pluggable Authentication Module (PAM)/LDAPPluggable Authentication Module (PAM) . . . . . . . . . . . 4-3

How UniVerse Authentication Currently Works. . . . . . . . 4-3PAM Support . . . . . . . . . . . . . . . . . . 4-3

Chapter 5 UniObjects For .NET Compact FrameworkAbout UniObjects for .NET Compact Framework . . . . . . . . 5-4About the .NET Compact Framework . . . . . . . . . . . . 5-5

What Is the .NET Compact Framework? . . . . . . . . . . 5-5Features of UniObjects for .NET Compact Framework . . . . . . . 5-8

Limitations of UniObjects for .NET Compact Framework . . . . 5-8Setting Up the Development Environment in UniObjects for .NET Compact

Framework . . . . . . . . . . . . . . . . . . . 5-9Software Requirements . . . . . . . . . . . . . . . 5-9Hardware Requirements . . . . . . . . . . . . . . . 5-10Mobile CE Hardware Requirements . . . . . . . . . . . 5-10Installing UniObjects for .NET Compact Framework . . . . . . 5-11

Creating a UniObjects for .NET Compact Framework Application . . . 5-12Building the Application . . . . . . . . . . . . . . . 5-17

Chapter 6 Using SSL with UniObjects for .NETSoftware Requirements . . . . . . . . . . . . . . . . . 6-5Configuring the Database Server for SSL . . . . . . . . . . . 6-6UniObjects for .NET Secure Methods . . . . . . . . . . . . 6-8Installing a Certificate into a Windows Certificate Store . . . . . . 6-11

erse 10.3 New Features

Chapter 7 Basic Developer ToolkitThe U2 Resource View . . . . . . . . . . . . . . . . . 7-4

Filters . . . . . . . . . . . . . . . . . . . . . 7-4Comparing Source Code . . . . . . . . . . . . . . . 7-9Setting UniVerse BASIC Program Options. . . . . . . . . . 7-14

The Basic Program Editor . . . . . . . . . . . . . . . . 7-15Syntax Highlighting . . . . . . . . . . . . . . . . . 7-15Code Assist . . . . . . . . . . . . . . . . . . . 7-17Collapsing Blocks of Text . . . . . . . . . . . . . . . 7-23The Outline View . . . . . . . . . . . . . . . . . 7-24Code Templates . . . . . . . . . . . . . . . . . . 7-25Refactoring . . . . . . . . . . . . . . . . . . . 7-27Dynamic Array Editor . . . . . . . . . . . . . . . . 7-30XML Editor . . . . . . . . . . . . . . . . . . . 7-30

Table of Contents vii

:\ProgMarch

1Administering UniData on Windows NT or Windows 20000

1Chapter

ram Fi18 201

Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta

Automatic Data Encryption

Encrypted File Types . . . . . . . . . . . . . . . . 1-4 Encryption With UniVerse Replication . . . . . . . . . . 1-4Key Store . . . . . . . . . . . . . . . . . . . . . 1-5How Encryption Works. . . . . . . . . . . . . . . . . 1-6Defining a Master Key . . . . . . . . . . . . . . . . . 1-8 Upgrading to UniVerse 10.3 from UniVerse 10.2 . . . . . . . 1-9 Changing a Master Key After Data is Encrypted . . . . . . . 1-10UniVerse Encryption Algorithms. . . . . . . . . . . . . . 1-14Encryption Commands . . . . . . . . . . . . . . . . . 1-15 CREATE.ENCRYPTION.KEY . . . . . . . . . . . . . 1-15 DELETE.ENCRYPTION.KEY . . . . . . . . . . . . . 1-16 LIST.ENCRYPTION.KEY . . . . . . . . . . . . . . 1-16 GRANT.ENCRYPTION.KEY . . . . . . . . . . . . . 1-17 REVOKE.ENCRYPTION.KEY . . . . . . . . . . . . 1-18 ENCRYPT.FILE . . . . . . . . . . . . . . . . . 1-19 DECRYPT.FILE . . . . . . . . . . . . . . . . . 1-21 LIST.ENCRYPTION.FILE . . . . . . . . . . . . . . 1-22 ACTIVATE.ENCRYPTION.KEY . . . . . . . . . . . . 1-23 DEACTIVATE.ENCRYPTION.KEY . . . . . . . . . . . 1-23 DISABLE.DECRYPTION . . . . . . . . . . . . . . 1-24 ENABLE.DECRYPTION . . . . . . . . . . . . . . 1-25UniVerse BASIC Encryption Commands . . . . . . . . . . . 1-26 ACTIVATEKEY . . . . . . . . . . . . . . . . . 1-26 DEACTIVATEKEY . . . . . . . . . . . . . . . . 1-27 DISABLEDEC . . . . . . . . . . . . . . . . . . 1-28 ENABLEDEC . . . . . . . . . . . . . . . . . . 1-30 STATUS Function Changes . . . . . . . . . . . . . . 1-31

les\Adobe\FrameMaker8\UniVerse 10.3\10.3rebranded\newfeatures\Ch1TOC.fm0 2:50 pm Administering UniData on Windows NT or Windows 2000

The encman Utility. . . . . . . . . . . . . . . . . . . 1-33 Viewing Audit Trail Information . . . . . . . . . . . . . 1-33 Generating a Key Store . . . . . . . . . . . . . . . . 1-34 Removing a Key Store . . . . . . . . . . . . . . . . 1-35 Importing and Exporting Metadata . . . . . . . . . . . . 1-35 Resynching Tags . . . . . . . . . . . . . . . . . . 1-37Using UniAdmin for Encryption . . . . . . . . . . . . . . 1-40 Encryption Wallet Management . . . . . . . . . . . . . 1-45

Administering UniData on Windows NT or Windows 2000 1-2

C:\Program Files\Adobe\FrameMaker8\UniVerse 10.3\10.3rebranded\newfeatures\Ch1.fm3/18/10

Automatic data encryption enables you to encrypt specified fields or entire records. UniVerse automatically encrypts and decrypts the data when accessed by UniVerse or UniVerse BASIC commands. This enhancement includes the following features:

Defining which fields in the UniVerse file to encryptAutomatically encrypt the data you specify when writing the record to the UniVerse fileAutomatically decrypt the data you specify when reading the record from the fileKey management supportAudit trail for operations on keys and encrypted filesSupport of Federal Information Processing Standards (FIPS) encryption algorithms, which include popular encryption algorithms DES and AES.

Note: When using automatic data encryption, performance may degrade due to encryption operations, and more disk space may be required.

Encrypted File TypesAt this release, UniVerse only encrypts hashed files. UniVerse does not encrypt directory files, system log files, dictionary files, or system temporary files. However, UniVerse does encrypt the transaction log file, which contains encrypted data for files that are encrypted.

Note: You cannot encrypt the @ID of a record or an indexed field.

Encryption With UniVerse ReplicationIf you are using UniVerse Replication, care must be taken when adding automatic data encryption. If a file that is encrypted is also being replicated, UniVerse transfers encrypted data to the subscribing system. Encryption does not occur on the subscribing system. IBM highly recommends that the encryption configuration be the same on both the publishing and subscribing systems, including the master key, encryption key and password, encryption file definitions, and the algorithms you specify for encryption. If the configurations are not identical, the replicated data will not be synchronized with the source data, and will not be usable when failover is required.

1-3 UniVerse 10.3 New Features

C:\Program Files\Adobe\FrameMaker8\UniVerse

Key StoreThe most important part of an encrypted system is key management. To ensure a fully secure system, UniVerse maintains a key store, with an interface to create keys and reference keys. Keys can be protected through a user-name based access control, and also protected by a password.

The UniVerse key store is protected by a master key. This master key is used in deriving all keys. After you install UniVerse, you should define a master key, either providing one of your own, using a UniVerse-generated random key, or using the UniVerse default.

UniVerse loads the master key into memory each time UniVerse starts.

1-4


How Encryption WorksThis section gives an overview of how encryption works on a UniVerse database:

After installing UniVerse, you define a master key. You can define your own master key, or use a UniVerse-generated master key, or use a UniVerse default. IBM recom-mends that you define your own master key or use a UniVerse-generated master key. UniVerse uses the master key in all operations related to Automatic Data Encryption.

When you create a new encryption key, you can choose to protect the key with a password, or rely on the operating system-level user name to control access to the key. You can grant access to the encryption key to other users or groups based on the OS-level account name.

When you create an encrypted file, you must associate a key and an encryption algorithm for each object to encrypt. You can encrypt an entire record or a just a field or fields in the record. UniVerse checks if the user has access permission to the key based on the OS-level user or group ID, then asks for the password if the key is password protected.

During the UniVerse read or write operation, either from UniVerse BASIC, RetrieVe, or UniVerse SQL, UniVerse locates the key ID associated with an encrypted field and checks if the key is active. The key is considered active if the user has permission to the key, the key is not password protected, or the key is password protected and the correct password has been provided through the ACTIVATE.ENCRYPTION.KEY command or the UniVerse BASIC ACTIVATEKEY statement.

If the operation you specify is a read operation and the key is not active, UniVerse returns an error in the UniVerse BASIC STATUS command and returns no data. However, if you disable encryption through the DISABLE.DECRYPTION command, UniVerse does not attempt to decrypt the data and returns encrypted data.

If the operation you specify is a write operation and the key is not active, the encrypted field keeps the original cipher text value, and no new encryption occurs. If the data in the encrypted field is in clear text, the write operation fails.

If you provide your own master key, the encrypted data can only be decrypted on the installed system. If you moved the encrypted data to another system, you must set up the same master key, and the same encryption key(s) with the same password, before you can read the encrypted data.



If you choose a site-specific master key (one you define or one that UniVerse generates), the encrypted data can only be decrypted on the installed system.

If you choose to use the UniVerse default master key, or if you move the encrypted data and the key store to another UniVerse system that has the same user account setup, you can decrypt the data as long as the keys are not password protected, or the password is provided.

The following table shows the combination of the master key and the key password and their impact on security level and file portability.

Master Key and Key Password Impact

System Master Key / File Encryption Key No Password With Password

Default Minimum Protection. Data can be accessed on another UniVerse system with default master key and encryption key.

Strong Protection. Data can be accessed on another UniVerse system with the default master key and the same encryption key with the same password.

System-Specific (user-defined or UniVerse-generated)

Strong Protection. Data can be accessed on another UniVerse system with the same user-defined master key and encryption key, but cannot protect data if the entire machine is stolen.

Maximum Protection. Data can be accessed on another UniVerse system with the same user-defined master key and the same encryption key and password if the system is set up.

1-6


Defining a Master KeyUniVerse Data Encryption requires that you set a master key before it runs. Use the uvregen command to define a new master key. You must specify -m to set up a new master key, as shown in the following example:

C:\IBM\UV>\ibm\uv\bin\uvregen -m abc123UniVerse master key has been set to the new master key specified.

There are three types of master keys:

<Master Key String> – User-defined master keySYSGEN – UniVerse-generated site-specific master keySYSTEM – UniVerse default master key

If the master key was previously defined, the uvregen utility will prompt for a new master key, or prompt for the current master key for verification. At the prompt, enter either the Master Key string, SYSGEN, or SYSTEM.

If you specify SYSTEM for the master key, UniVerse changes the master key to the system default. In order to revert to the system default, you must provide the current master key.

Use @/full_path to indicate that the master key is stored in a file, as shown in the fol-lowing example:

@/mysecure/mymaster

If you specify SYSGEN, use the -o option to specify a file name to store the generated master key. If you do not specify -o, UniVerse stores the key in the mygenkey file in the directory where you executed the command.

IBM recommends that the key file is strongly protected, or removed from the system after the installation is complete and stored in a safe place.

The maximum length of a master key is 64 characters. The master key should be long and difficult to guess.



Upgrading to UniVerse 10.3 from UniVerse 10.2You must convert any data you encrypted in UniVerse 10.2, including the key store, in UniVerse 10.3. This involves converting the key store, the metadata files, and the data files.

If you install UniVerse 10.3 in the same UniVerse 10.2 home directory, the UniVerse installation process tries to convert the key store and metadata files automatically. You only need to convert your data files with the convencfile utility. However, on some operating systems such as AIX, Solaris, and HP, the automatic procedure will not succeed. A message indicating that the UniVerse license is invalid appears. If you see this message, or if you install UniVerse 10.3 in a different home directory than UniVerse 10.2, execute the following steps to convert your system:

1. Transfer the Master KeyOn operating systems other than Solaris, HP, or AIX, issue the following command:uvregen -T <old_uvhome>,<new_uvhome>On Solaris, HP, or AIX operating systems, manually set the master key to the same value as your UniVerse 10.2 system, using the following command:uvregen -m <master_key>

2. Set up the Key StoreCopy the &KEYSTORE&, &ENCINFO&, and D_&ENCINFO& files from the old $UVHOME directory to the new $UVHOME directory. In the new $UVHOME directory, create a new dictionary for the &KEY-STORE& file using the following command:loadfile src.u/d_keystore.u “D_&KEYSTORE&”

3. Convert the Key StoreConvert the 10.2 key store to the 10.3 key store using the following command:convencfile -keystore

4. Retag Key StoreRetag the key store using the following command:encman -retag -m <master_key>

1-8


5. Verify the ConversionVerify that the conversion was successful by logging on to your UniVerse account and executing the following command:> LIST.ENCRYPTION.KEYAll the encryption keys created in the 10.2 release should appear.

6. Convert FilesExecute the convencfile command on individual files on the entire account. The following example illustrates running the command on an individual file:convencfile -file <filename>The next example illustrates running the command an entire account:convencfile -file <account_directory>

Changing a Master Key After Data is EncryptedOnce a master key has been used in file encryption, we recommend that you do not change it. All aspects of UniVerse data encryption involves the master key, and changing it makes all previously encrypted data, existing keys, and audit records inaccessible.

If you decide to change the master key, you must first decrypt all encrypted data, save a text copy of your existing audit records, and make sure you can re-create existing encryption keys. If you do not follow these steps, your data will not be accessible after you change the master key. To help this situation and to recover your key store, you can use the export and import options of the encman utility to back up your key store and reload it. For information about the encman utility, see “The encman Utility” on page 31.



Using Encryption WalletsYou can create an encryption key wallet, which contains encryption keys and passwords. Instead of activating encryption keys individually, you can supply a wallet and its corresponding password to UniVerse to activate all the encryption keys contained in the wallet. UniVerse stores the wallet in the key store. Wallets are specif-ically intended for clients to remotely access and group encryption keys.

Client applications can use the encryption key wallet to activate keys for the entire session. ACTIVATE_WALLET() and DEACTIVATE_WALLET() are global subroutines to activate and deactivate encryption keys contained in the wallet. Each of these subroutines have the following parameters, which must be supplied in the following order:

1. Wallet_id – The ID of the encryption key wallet2. Wallet_password – The password for the encryption key wallet3. Status – 0 for success, other codes indicate failure4. Error_message – In case of failure, a detailed error message

The following example illustrates calling the ACTIVATE_WALLET () subroutine:

CALL *ACTIVATE_WALLET(wallet_ID, wallet_password, wallet_status, wallet_err)

The next example illustrates calling the DEACTIVATE_WALLET() subroutine:

CALL *DEACTIVATE_WALLET(wallet_ID, wallet_password, wallet_status, wallet_err)

For clients that do not use SQL to access the database, you can call these procedures directly from a session object.

If you are using the IBM JDBC Driver for UniVerse, you can access these procedures by executing a CALL statement from a connection object.

If you are using UniObjects for Java, you can access these methods through the sub-routine method of a session object.

For clients that use SQL to access the database, such as UniVerse ODBC and UniOLEDB, you can add WALLETID and WALLETPASS to the uci.config file. Adding these parameters enables UniVerse to perform encryption key activation automatically.

1-10


Wallet TCL CommandsThe following TCL commands have been added for encryption key wallets:

CREATE.ENCRYPTION.WALLET <wallet_id> <wallet_password>DELETE.ENCRYPTION.WALLET [FORCE] <wallet_id> <wallet_password>WALLET.ADD.KEY <wallet_id> <wallet_password> <key_id> <key_password>WALLET.REMOVE.KEY [FORCE] <wallet_id> <wallet_password> <key_id> [key_password]LIST.ENCRYPTION.WALLET

Note: Keys that are entered in a wallet must have a password.

Use the GRANT.ENCRYPTION.KEY command to grant access to an encryption key wallet:

GRANT.ENCRYPTION.KEY <wallet_id> <wallet_password> <grantees>

Use the REVOKE.ENCRYPTION.KEY command to revoke access from a wallet:

REVOKE.ENCRYPTION.KEY <wallet_id> <wallet_password> <grantees>

Use the ACTIVATE.ENCRYPTION.KEY command to activate all encryption keys contained in the wallet:

ACTIVATE.ENCRYPTION.KEY <wallet_id> <wallet_password>

Use the DEACTIVATE.ENCRYPTION.KEY command to deactivate all encryption keys contained in a wallet:

DEACTIVATE.ENCRYPTION.KEY <wallet_id> <wallet_password>

The UniVerse BASIC ACTIVATEKEY and DEACTIVATEKEY statements also accept <wallet_id> and <wallet_password>.



UniVerse Encryption AlgorithmsUniVerse supports the following encryption algorithms:

AES (AES128, AES192, AES256)DES (DES, DES3)RC2RC4

AES and DES are Federal Information Processing Standards (FIPS) compliant encryption algorithms. Within each group, with the exception of RC4, there are multiple chaining modes (CBC, ECB, OFB, and CFB).

When you encrypt a file, you must specify a specific algorithm to use in encryption. The following table describes valid algorithms for UniVerse decryption:

UniVerse Encryption Algorithms

Type of Encryption Desired Algorithm to Specify

56-bit key DES encryption des, des-cbc, des-ebc, des-cfb, or des-ofb

112-bit key ede DES encryption des_ede, des-ede-cbc, des-ede, des-ede-cfb, or des-ede-ofb

168-bit key ede DES encryption des3, des_ede3, des_ede3-cbc, des_ede3-cfb, or des_ede3-ofb

128-bit key R2 encryption rc2, rc2-cbc, rc2-ecb, rc2-cfb, or rc2-ofb

128-bit key RC4 encryption rc4

128-bit key AES encryption aes128, aes-128-cbc, aes-128-cfb, or aes-128-ofb

192-bit key AES encryption aes192, aes-192-cbc, aes-192-cfb, aes-192-ofb

256-bit key AES encryption aes256, aes-256-cbs, aes-256-ecb, aes-256-cfb, or aes-256-ofb

Note: The algorithm specification is case-insensitive.

1-12


Encryption CommandsThis section lists commands you can use for encrypting and decrypting your data.

CREATE.ENCRYPTION.KEYUse the CREATE.ENCRYPTION.KEY command to create an encryption key in the UniVerse key store. We recommend that you create a password for the key.

Syntax

CREATE.ENCRYPTION.KEY key.id [password]

Parameters

The following table describes each parameter of the syntax.

CREATE.ENCRYPTION.KEY Parameters

Parameter Description

key.id The encryption key ID.

password The password for key.id.

Note: We suggest that the password you create is a phrase that is hard to guess, but easy to remember, using a combination of ASCII characters and digits. If a passwords contains a space (“ “), you must use quotation marks to enclose the password.

The following example illustrates creating an encryption key using the CREATE.ENCRYPTION.KEY command:

>CREATE.ENCRYPTION.KEY sample myuniverseCreate encryption key sample successful.>



DELETE.ENCRYPTION.KEYUse the DELETE.ENCRYPTION.KEY command to delete a key from a key store. You must be the owner of the file or logged on as root or Administrator to delete an encryption key, and you must provide the correct password. If the key is referenced by any encrypted field or file, deleting the key will fail, unless you specify FORCE.

Syntax

DELETE.ENCRYPTION.KEY [FORCE] key.id [password]

Parameters


DELETE.ENCRYPTION.KEY Parameters


FORCE Forces the encryption key to be deleted, even if it is referenced by an encrypted record or field.

key.id The encryption key to delete.

password The password for the encryption key to delete.

ExampleThe following example illustrates deleting an encryption key using the DELETE.ENCRYPTION.KEY command:

>DELETE.ENCRYPTION.KEY sample myuniverseDo you really want to remove this encryption key? (Y/N)?YRemove encryption key sample successful.>

LIST.ENCRYPTION.KEYUse the LIST.ENCRYPTION.KEY command to list the existing keys in the key store. You can also list records in the key store using UniVerse RetrieVe commands, such as LIST, LIST.ITEM, SORT, SORT.ITEM, and so forth.

1-14


Note: The name of the key store file is &KEYSTORE&. Although you can view records from this file using UniVerse RetrieVe commands, other UniVerse commands, such as DELETE.FILE and CLEAR.FILE will fail. The ED command will only display encrypted data. Any attempt to write to the key store will fail, including a UniVerse BASIC WRITE operation or an ECL COPY.

GRANT.ENCRYPTION.KEYUse the GRANT.ENCRYPTION.KEY command to grant other users access to the encryption key. When a key is created, only the owner of the key has access. The owner of the key can grant access to other users.

Syntax

GRANT.ENCRYPTION.KEY key.id [password] {PUBLIC | grantee {,grantee...}}

Parameters


GRANT.ENCRYPTION.KEY Parameters


key.id The encryption key.

password The password for the encryption key.

PUBLIC Grants access to the encryption key to all users on the system.

grantee Grants access to the encryption key to the grantee you specify. grantee can be a user name, or a group name. If you specify a group name, prefix the name with an asterisk (“*”). On Windows platforms, you can qualify a group name with a domain name, such as mydomain\users. When you specify a group name, UniVerse grants access to all users belonging to the group. Grantees cannot grant access to the encryption key to other users.



Account-based access control and password protection are two ways to protect encryption keys, independent of each other. You must grant access to an encryption key even if it does not have password protection if you want other users to use the key. Conversely, even if you have the correct password for the key, you cannot access it without being granted access.

Example

The following example illustrates granting PUBLIC access to the “sample” encryption key:

>GRANT.ENCRYPTION.KEY sample myuniverse PUBLICGRANT.ENCRYPTION.KEY to PUBLIC successful.>

REVOKE.ENCRYPTION.KEYUse the REVOKE.ENCRYPTION.KEY command to revoke access to the encryption key from other users. When a key is created, only the owner of the key has access. The owner of the key can revoke access from other users.

Syntax

REVOKE.ENCRYPTION.KEY key.id [password] {PUBLIC | grantee {,grantee...}}

ParametersThe following table describes each parameter of the syntax.


key.id The encryption key for which you are revoking access from another user.

REVOKE.ENCRYPTION.KEY Parameters

1-16


Example

The following example illustrates revoking encryption privileges from PUBLIC for the “sample” encryption key:

>REVOKE.ENCRYPTION.KEY sample myuniverse PUBLICREVOKE.ENCRYPTION.KEY for PUBLIC successful.>>grant.encryption.key SAMPLE MYUNIVERSE public

ENCRYPT.FILEUse the ENCRYPT.FILE command to create a file in which each record is encrypted.

Note: You cannot use ENCRYPT.FILE with the WHOLERECORD command on files containing indexes. You cannot encrypt an index file, or an indexed field.

SyntaxENCRYPT.FILE filename ... {WHOLERECORD | fieldname},alg,key[,pass] [fieldname,alg,key[,pass]]...

password The password for the encryption key for which you are revoking access from another user.

PUBLIC Revokes PUBLIC access to the encryption key from all users on the system.

grantee Revokes access to the encryption key from the grantee you specify. grantee can be a user name, or a group name. If you specify a group name, prefix the name with an asterisk (“*”). On Windows platforms, you can qualify a group name with a domain name, such as mydomain\users. When you specify a group name, UniVerse revokes access from all users belonging to the group. Grantees cannot revoke access to the encryption key from other users.


REVOKE.ENCRYPTION.KEY Parameters (Continued)



Parameters

ENCRYPT.FILE accepts all parameters of the RESIZE command. If the file you are encrypting is empty, you do not need to specify any of the RESIZE parameters. If the file you are encrypting is not empty, and you know that the file needs resizing because encrypting the file will increase the record size, you should specify the RESIZE parameters.


ENCRYPT.FILE Parameters


filename The name of the file to be encrypted.

WHOLERECORD Specifies to fully encrypt every record in the file.

fieldname,alg,key,pass Specifies the field name to encrypt, and the algorithm, key, and password to use. You can use a different algorithm and key for each field. If you do not specify a password, but created the key using password protection, UniVerse prompts for the password. If several fields use the same password, you only have to specify it once, at the first field that uses that key.

fieldname The name of the field to encrypt.

alg The algorithm to use for encryption. See “UniVerse Encryption Algorithms” on page 12 for a list of valid values.

key The key ID to use for the field encryption.

pass The password corresponding to the key.

Encrypting a file requires exclusive access to the file, and is very time consuming. During the encryption process, UniVerse creates a temporary file and writes the newly encrypted data to that file. If any errors occur during the encryption process, the command aborts and the original file is left intact.

Warning: The ENCRYPT.FILE command can run for a very long time if you are encrypting a file that already contains a large amount of data. All parameters for ENCRYPT.FILE, including the password for each encryption key, can potentially be seen by other users. Therefore, we recommend that you do not specify passwords on the command line but enter them when prompted by ENCRYPT.FILE.

1-18


Example

The following example illustrates encrypting the CUSTOMER file using the WHOLERECORD option:

>ENCRYPT.FILE CUSTOMER.F WHOLERECORD,aes128,sample,myuniverseENCRYPT.FILE successful.

DECRYPT.FILEThe DECRYPT.FILE command decrypts data in in a file or in the fields you specify.

Syntax

DECRYPT.FILE filename ... {WHOLERECORD | fieldname},key[,pass] [fieldname,key[,pass]]...>

DECRYPT.FILE accepts all RESIZE command parameters. If the file you are decrypting is empty, you do not need to specify any of the RESIZE parameters. If the file you are decrypting is not empty, and you know that the file needs resizing because decrypting the file will decrease the record size, you should specify the RESIZE parameters.


DECRYPT.FILE Parameters


filename The name of the file to decrypt.

WHOLERECORD Specifies to fully decrypt every record in the file.

fieldname,key,pass Specifies the field name to decrypt, and the key, and password to use. If you do not specify a password, but created the key using password protection, UniVerse prompts for the password. If several fields use the same password, you only have to specify it once, at the first field that uses that key.

fieldname The name of the field to decrypt.

key The key ID to use for the field decryption.

pass The password corresponding to the key.



If the encrypted file was created using the WHOLERECORD keyword, you should specify WHOLERECORD when decrypting the file. If the file was not encrypted using the WHOLERECORD keyword, do not specify WHOLERECORD when decrypting the file.

Warning: The DECRYPT.FILE command can run for a very long time if you are decrypting a file that already contains a large amount of data. All parameters for DECRYPT.FILE, including the password for each encryption key, can potentially be seen by other users. Therefore, we recommend that you do not specify passwords on the command line but enter them when prompted by DECRYPT.FILE.

Example

The following examplE illustrates decrypting a file that was originally encrypted with the WHOLERECORD option.

>DECRYPT.FILE CUSTOMER.F WHOLERECORD,sample,myuniverseDECRYPT.FILE successful.

LIST.ENCRYPTION.FILEUse the LIST.ENCRYPTION.FILE command to display encryption configuration data, such as the fields that are encrypted, the algorithms used, and so forth. This command also displays the fields for which decryption is currently disabled.

Syntax

LIST.ENCRYPTION.FILE filename

ExampleThe following example illustrates the output from the LIST.ENCRYPTION.FILE command:

>LIST.ENCRYPTION.FILE CUSTOMER.FWhole-record encryption, algorithm aes128, key sample.

1-20


ACTIVATE.ENCRYPTION.KEYUse the ACTIVATE.ENRYPTION.KEY command to activate a key or a wallet. It is necessary to activate a key if it is protected by a password.

Syntax

ACTIVATE.ENCRYTPION.KEY key.id password

Parameters


ACTIVATE.ENCRYPTION.KEY Parameters


key.id The key ID or wallet ID to activate. If you provide a Wallet ID, UniData activates all keys in the wallet.

password The password corresponding to key.id.

Note: You can activate only keys with password protection using this command. Keys that do not have password protection are automatically activated.

DEACTIVATE.ENCRYPTION.KEYUse the DEACTIVATE.ENCRYPTION.KEY command to deactivate a key or a wallet. This command is useful to deactivate keys to make your system more secure.

Syntax

DEACTIVATE.ENCRYPTION.KEY key.id password



Parameters


DEACTIVATE.ENCRYPTION.KEY Parameters


key.id The key ID or wallet ID to deactivate. If you provide a wallet ID, UniVerse deactivates all keys in the wallet.


Note: You can deactivate only keys with password protection with this command. Keys that do not have password protection are automatically activated and cannot be deactivated.

DISABLE.DECRYPTIONUse the DISABLE.DECRYPTION command to turn off decryption on a field or fields you specify.

Syntax

DISABLE.DECRYPTION filename <field_list>

Parameters


DISABLE.DECRYPTION Parameters


filename The name of the file on which you want to disable decryption.

field_list A comma-separated list of fields for which you want to disable decryption. Do not enter spaces between the field names.

1-22


Example

The following example illustrates disabling decryption on two fields in the CUSTOMER.F file:

>DISABLE.DECRYPTION CUSTOMER.F NAME,ZIPDisable decryption on field NAME successful.Disable decryption on field ZIP successful.>

ENABLE.DECRYPTIONUse the ENABLE.DECRYPTION command to activate decryption on specific fields in a file on which the decryption was previously turned off by the DISABLE.DECRYPTION command.

Syntax

ENABLE.DECRYPTION filename <field_list>

Parameters

The following table describes each parameter of the syntax..

ENABLE.DECRYPTION Parameters


filename The name of the file on which you want to enable decryption.

de A comma-separated list of fields for which you want to enable decryption. Do not enter spaces between the field names.

Example

The following example illustrates enabling decryption of two fields in the CUSTOMER.F file:

>ENABLE.DECRYPTION CUSTOMER.F NAME,ZIPEnable decryption on field NAME successful.Enable decryption on field ZIP successful.>



UniVerse BASIC Encryption CommandsThis section describes the UniVerse BASIC commands for use with encryption and decryption.

ACTIVATEKEYUse the ACTIVATEKEY command to activate a key. It is necessary to activate a key if you want to supply a password for key protection.

Syntax

ACTIVATEKEY <key.id>, <password> [ON <hostname>] [ON ERROR <statements>]

Parameters


ACTIVATEKEY Parameters


key.id The key ID or wallet ID to activate. If you provide a Wallet ID, UniVerse activates all keys in the wallet.


ON hostname The name of the remote host on which you want to activate the encryption key.

ON ERROR statements

If you specify ON ERROR statements and an error occurs, UniVerse executes the statements following the ON ERROR clause. Otherwise, UniVerse executes the next statement.

Note: You can activate only keys with password protection with this command. Keys that do not have password protection are automatically activated.

1-24


DEACTIVATEKEYUse the DEACTIVATEKEY command to deactivate a key or a wallet. This command is useful to deactivate keys to make your system more secure.

Syntax

DEACTIVATEKEY <key.id>, <password> [ON <hostname>] [ON ERROR <statements>]

Parameters


DEACTIVATEKEY Parameters


key.id The key ID or wallet ID to deactivate. If you provide a wallet ID, UniVerse deactivates all keys in the wallet.


ON hostname The name of the remote host on which you want to deactivate the encryption key.

ON ERROR statements


Note: You can deactivate only keys with password protection with this command. Keys that do not have password protection are automatically activated and cannot be deactivated.



Status CodesThe ACTIVATEKEY and DEACTIVATEKEY statements return the following STATUS codes regarding key and wallet operations:

ACTIVATEKEY and DEACTIVATEKEY Status Codes

STATUS Code Description

0 Operation successful.

1 Key is already activated or deactivated. This applies to a single key, not a wallet operation.

2 Operation failed. This applies to a single key, not a wallet operation.

3 Invalid key or wallet ID or password.

4 No access to wallet.

5 Invalid key ID or password in a wallet.

6 No access to one of the keys in the wallet.

9 Other error.

ExampleThe following example illustrates deactivating an encryption key:

DEACTIVATEKEY “sample”,”myuniverse” ON ERROR PRINT “Unable to deactivate key”

DISABLEDECUse the DISABLEDEC command to turn off decryption on a file or fields you specify.

Syntax

DISABLEDEC <filename> [, <multilevel-filename>], {ALL |<field_list>} [ON ERROR <statements>]

1-26


Parameters


DISABLEDEC Parameters


filename The name of the file on which you want to disable decryption.

ALL If you specify ALL, UniVerse will disable decryption on all encrypted fields of this file.

field_list A comma-separated list of fields for which you want to disable decryption. Do not enter spaces between the field names.

ON ERROR statements


STATUS Codes

DISABLEDEC has the following STATUS codes:

DISABLEDEC STATUS Codes


0 No error, operation successful.

1 Decryption is already disabled.

2 General operation failure, such as an open file error.

3 File is not an encrypted file.

4 Attempting operation on a WHOLERECORD encrypted file.

5 Field(s) is not an encrypted field.

6 Cannot locate information to disable decryption.

7 Field is not a valid field in this file.



Example

The following example illustrates disabling decryption on two fields in a file using a quoted string:

DISABLEDEC “CUSTOMER.F”,”NAME,PHONE” ON ERROR PRINT “Unable to disable decryption”

The next example illustrates disabling decryption on two fields using variables:

CUST=”CUSTOMER.F”FIELDS=”NAME,PHONE”DISABLEDEC CUST,FIELDS ON ERROR PRINT “Unable to disable decryption”

ENABLEDECUse the ENABLEDEC command to activate decryption on a file or fields you specify.

Syntax

ENABLEDEC <filename> [, <multilevel-filename>], {ALL | <field_list>} [ON ERROR <statements>

Parameters


ENABLEDEC Parameters


filename The name of the file on which you want to enable decryption.

ALL If you specify ALL, UniVerse enables decryption on all encrypted fields of this file.

field_list A comma-separated list of fields for which you want to enable decryption. Do not enter spaces between the field names.

ON ERROR statements


1-28


STATUS Codes

ENABLEDEC has the following STATUS codes:

ENABLEDEC Status Codes


0 No error, operation successful.

1 Decryption is already enabled.

2 General operation failure, such as an open file error.

3 File is not an encrypted file.

4 Attempting operation on WHOLERECORD encrypted file.

5 Field(s) is not an encrypted field.

6 Cannot locate information to enable decryption.

7 Field is not a valid field in this file.

Example

The following example illustrates enabling decryption on two fields in a file using a quoted string:

ENABLEDEC “CUSTOMER.F”,”NAME,PHONE” ON ERROR PRINT “Unable to enable decryption”

The next example illustrates enabling decryption on two fields using variables:

CUST=”CUSTOMER.F”FIELDS=NAME,PHONE”ENABLEDEC CUST,FIELDS ON ERROR PRINT “Unable to enable decryption”

STATUS Function ChangesThe following changes have been made to the UniVerse BASIC STATUS function:

For UniVerse BASIC READ statements, STATUS() returns 5 to indicate that an encryption error occurred during the READ operation.



For UniVerse BASIC WRITE statements, STATUS() returns -9 to indicate that an encryption error occurred during the WRITE operation.When an encryption error occurs, a READ/WRITE statement will execute statements following the ELSE clause, if an ELSE clause is specified.

FILEINFO() FunctionTwo new values have added to the FILEINFO() function to obtain encryption information:

Code Value 22 – If the file is encrypted, UniVerse returns a dynamic array containing the following multivalued data:

For a file encrypted with the WHOLERECORD option:-1@SM@<key-id>@SM<algorithm>For a file encrypted at the field level, returns the following for each field:-1@SM@<key-id>@SM<algorithm>@SM@<field_name>If the file is not encrypted, UniVerse returns an empty string.

1-30


The encman UtilityThe encman utility enables you to manage data encryption. You can either view audit trail information or create a key store through this utility.

You must be logged in as root or Administrator to run this command.

Viewing Audit Trail InformationUse the encman -audit command to view audit trail information.

Syntax

encman [ [-audit] [-b date] [-a date] [-u username] [-o operation] [-f] [-use filename][-backup <filename>]



-b date Displays audit trail data before the date you specify. Enter the date in the mm/dd/yyyy format.

-a date Displays audit trail data after the date you specify. Enter the date in the mm/dd/yyyy format.

-u username Displays audit trail data for the user name you specify. You can specify multiple users, for example, -u user1 -u user2.

encman -audit Parameters



Generating a Key StoreTo generate a key store, use the -genkeystore option.

-o operation Displays audit trail data for the operation you specify. You can specify multiple operations. Valid operations are:

CREATE – Creates encryption key

DELETE – Deletes encryption key

GRANT – Grants key access

REVOKE – Revokes key access

ACTIVATE – Activates encryption key

DEACTIVT – Deactivates encryption key

ENABLE – Enables encryption key

DISABLE – Disables encryption key

ENCRYPT – Encrypts a file

DECRYPT – Decrypts a file

RMKEYSTR – Removes Key Store

FLHDCHG – Encryption flag change in file header

CREATWLT – Creates a wallet

DELETWLT – Deletes a wallet

WLTADKEY – Add a key to a wallet

WLTRMKEY – Remove a key from a wallet

PRCKEYST – Key store import or export

-f Displays only failed operations.

-use <file> Displays data in the <file> you specify, rather than the current audit file.

-backup <file> Saves the current audit trail contents to the filename you specify. UniVerse clears the audit trail file after completing the backup.


encman -audit Parameters (Continued)

1-32


Syntax

encman [ [-genkeystore] [-n] ]


encman -genkeystore Parameters


-n Specifies to not create the &ENCINFO& file.

Removing a Key StoreTo remove a key store, use the -delkeystore option.

Syntax

encman [ [-delkeystore] [-f] [-a]]

The following table describes the parameter of the syntax:

encman -delkeystore Parameter


-f Deletes the key store without prompting for confirmation.Note: Using this operation is dangerous. If you have encrypted files, data cannot be retrieved unless you recreate the key store and keys used by these files.

-a Remove the key store and the &ENCINFO& file.

Importing and Exporting MetadataTo assist with disaster recovery or system migration, use the export and import options. These options also back up and restore the &ENCINFO& file.



Note: The import operation will fail if the target system has a different master key than the original system. This is because you cannot access data files encrypted with keys contained in the old key store, even if you restore the key store and metadata store, unless the master key on the target system is the same as that on the source system. You must set up the same system master key on the target system prior to importing the key store.

To export encryption metadata to a file, use the export option. The import operation re-creates the key store on the running system. The running system can be the same system where you performed the export operation, or a different system.

encman -export <master key> [<password>] <filename>

<master key> must match the current system <master key> or the export operation will fail.

<password> is optional. If you specify a password, when you import the metadata to the new system, you must specify this password on the new system. If you do not specify <password>, the encman utility uses the <master key> to encrypt the data and populate the file.

If the <master key> begins with “@”, UniVerse treats the rest of the string as the name of the file that contains the master key. If the current system master key is the system default, specify ‘SYSTEM” on the command line. If <master key> or <password> contain spaces or other nonalphanumeric characters, you must place <master key> or <password> in quotation marks.

To import metadata to a file, use the import option:

encman -import <master key> [<password>] {chown <owner>,<newowner> {<owner>,<newowner>} | -chpath <path>,<new path> {<path>,<new path>}} <filename>

You must provide the <master key> from the old system to execute the import option, which was provided when executing the export operation. If you specified <password> when exporting the data, you must provide that password when executing the import option.

The -chown option allows you to change all references of <owner> to <new owner>, including the key creator and grantees in a key record.

1-34


The -chpath option allows you to change the file path in the key reference attribute of a key record to a new path. You must specify the full path. UniVerse changes all instances of <path> to <new path>. For example, if FILEA has the following path:

/home/disk1/acct1/FILEA

and you execute the following -chpath option:

... -chpath /home/disk1/acct1,/usr/disk1,acct1

FILEA will have the following path:

/usr/disk1/acct1/FILEA

Resynching TagsThe &ENCINFO& and &KEYSTORE& files each contain system-specific tags. These tags stop the files from being accessed if they are stolen and placed on another system.

In the case of a system migration or disaster recovery, use the -retag option of the encman utility to retag the key store and the metadata store. You can specify the master key as shown in the following example:

encman -retag -m <master_key>

The master key you specify must match the master key currently effective on the system. If you do not specify the master key, UniVerse prompts for it.

Inputting the master key does not echo to the screen. If the master key you specify begins with the “@” symbol, UniVerse uses the text following “@” as a key file for the encman utility to search for the actual key.

You should use “SYSTEM” for the system default master key.

UniVerse writes audit records indicating the success or failure of the retagging process to the audit file.



Installation ProcessThis section describes the installation process for Automatic Data Encryption.

New InstallationsUniVerse does not automatically install a master key. There are three types of master keys:

<Master Key String> – User-defined master keySYSGEN – UniVerse-generated site-specific master keySYSTEM – UniVerse default master key

For information about defining a master key, see “Defining a Master Key” on page 7.

Upgrade InstallationOnce you have set up the master key and performed data encryption, it is essential to keep the master key unchanged. The installation process transfers the original master key to the upgraded version by using the -t option with the uvregen command.

The installation script automatically calls the uvregen command to check if an existing master key should be migrated. It searches the current directory to see if a .uvconfig exists. If one exists, uvregen checks if there is an existing master key it can migrate. If any of the following conditions exist, UniVerse does not migrate the master key:

The source .uvconfig file if from UniVerse 10.2 or earlierThe source .uvconfig file is not authorizedThe source .uvconfig file or target .uvconfig file is for the UniVerse Personal EditionThe master key is not set up in the current .uvconfig file.The source or target il is not able to be used on the hardware

If for any reason the installation script fails to transfer the master key, you can transfer it manually using the -t option with the uvregen command:

\ibm\uv\bin\uvregen -t test1,test2

1-36


UniVerse stores the master key in the .uvconfig file. You specify the source directory where the old .uvconfig file resides (usually $UVHOME/bin), and the target direc-tory where the new .uvconfig file resides (usually $UVHOME/bin). The uvregen command then transfers the current master key into the new .uvconfig file.



Using UniAdmin for EncryptionYou can use UniAdmin to manage data encryption on your system.

From the UniAdmin main window, select Data Encrypt Configure. The UniVerse Data Encrypt Configure dialog box appears, as shown in the following example:

1-38


Adding an Encryption KeyTo create and encryption key, click Add. The New Encryption Key dialog box appears, as shown in the following example:

Enter the name of the encryption key in the Key Name box. Although not required, you can enter a password for the new key in the Password box. Reenter the password in the Confirm Password box.

After you create the encryption key, it appears in the Encryption Keys area of the Data Encrypt Configure dialog box.

Deleting an Encryption KeyTo delete an encryption key, from the Data Encrypt Configure dialog box, click the encryption key you want to delete, then click Delete. The following dialog box appears:

If you want to delete the encryption key, click Yes. If not, click No.



Viewing Encryption Key DetailsTo view details about an encryption key, click the encryption key for which you want to view details from the Data Encrypt Configure dialog box, then click Detail. The Encryption Key Details dialog box appears, as shown in the following example:

The Encryption Key Details dialog box displays the following information about an encryption key:

Key Name –The name of the encryption key.Creator – The user ID of the user who created the key.Date – The date the encryption key was created.Time – The time the encryption key was created.Grantees – The users or groups who have access to the encryption key.References – The files and fields for which the encryption key is being used.

If the key is password protected, you must enter the password in the Key Password box at the bottom of Encryption Key Management dialog box.

1-40


Granting PrivilegesTo grant privileges to the encryption key to a user or group, click Grant. The Grant Encryption Key dialog box appears, as shown in the following example:

To grant public privileges, click the PUBLIC check box.

To grant privileges to individual users, enter the user ID in the Enter Users box. Separate user IDs with a comma. You can also select a user from the Users box.

To grant privileges to groups, enter the group ID in the Enter Groups check box. Separate each group ID with a comma. You can also select a group from the Group box.

If you are granting access to keys on a Windows system, the Users/Groups show local users and groups.



To show global users, select the Show Global Users check box. Click the user ID of each user for which you want to grant privileges. Alternatively, select the Show Global Groups check box and click the group ID for which you want to grant privi-leges, then click Grant. To select multiple users or groups, hold the CTRL key down while selecting the users or groups.

Note: You can only grant privileges to Public on Windows platforms.

Revoking PrivilegesTo revoke privileges from an encryption key from a user or group, click Revoke. The Revoke Encryption Privilege dialog box appears, as shown in the following example:

To revoke privileges from PUBLIC users, click the PUBLIC check box.

To revoke privileges from individual users or groups, click the user ID of each user for which you want to revoke privileges, or click the group ID for which you want to revoke privileges, then click Revoke. To select multiple users or groups, hold the CTRL key down while selecting the users or groups.

1-42


Encryption Wallet ManagementTo manage encryption wallets, click the Encryption Wallet Management tab. A window similar to the following example appears:



Adding an Encryption Wallet

To add an encryption wallet, click Add. The New Encryption Wallet dialog box appears, as shown in the following example:

Enter the name for the wallet in the Wallet Name box. Enter a password for the wallet in the Password box. Reenter the password in the Confirm Password box, then click OK.

Deleting an Encryption Wallet

To delete an encryption wallet, from the Encryption Wallet Management dialog box, click the encryption wallet you want to delete, then click Delete. The following dialog box appears:

1-44


Viewing Encryption Wallet Details

To view details about and encryption wallet, click the encryption wallet for which you want to view details from the Data Encrypt Configure dialog box, then click Detail. The Encryption Wallet Details dialog box appears, as shown in the following example:

The Encryption Wallet Details dialog box displays the following information about an encryption key:

Wallet Name – The name of the encryption key.Creator – The user ID of the user who created the key.Date – The date the encryption wallet was created.Time – The time the encryption wallet was created.Grantees – The users or groups who have access to the encryption wallet.Keys – The keys included in the encryption wallet.



If the key is password protected, you must enter the password in the Key Password box at the bottom of the Encryption Key Management dialog box.

Adding a Key to the Encryption Wallet

To add a key to the encryption wallet, click Add. The Add Encryption Key Into Wallet dialog box appears, as shown in the following example:

Enter the password for the encryption wallet in the Wallet Password box.

Select the key to include in the wallet in the Key box.

Enter the password for the key in the Key Password box.

Click OK to save the encryption key in the wallet, or click Cancel to exit without saving changes.

1-46


Deleting a Key From an Encryption Wallet

To delete a key from an encryption wallet, from the Encryption Wallet Management dialog box, click the encryption wallet where the key you want to delete resides, then click Detail. Select the key you want to delete from the wallet, then click Delete. The following dialog box appears:

If you select the Forcefully delete the selected key check box, a root or uvadmin user can delete an encryption key from an encryption wallet without knowing the key password.



Granting Privileges to Encryption Wallet

To grant privileges to the encryption wallet to a user or group, click Grant. The Grant Encryption Wallet dialog box appears, as sown in the following example.

To grant Public privileges, click the PUBLIC check box.

To grant privileges to individual users, enter the user ID in the Enter Users box. Separate user IDs with a comma. You can also select a user from the User box.

To grant privileges to groups, enter the group ID in the Enter Groups check box. Separate each group ID with a comma. You can also select a group from the Group box.

If you are granting access to keys on a Windows system, the Users/Groups area shows local user and groups.

1-48


To show system users, select the Show Global Users check box. Click the user ID of each user for which you want to grant privileges. Alternatively, select the Show Global Groups check box and click the group ID for which you want to grant privi-leges, then click Grant. To select multiple users or groups, hold the CTRL key down while selecting the users or groups.

Revoking Encryption Wallet Privileges

To revoke privileges from an encryption wallet from a user or group, click Revoke. The Revoke Encryption Wallet dialog box appears, as shown in the following example:

Waiting for issue 38622 to get fixed for screen shot

To revoke privileges from Public users, click the Public check box.

To revoke privileges from individual users, click the user ID of each user for which you want to revoke privileges, or click the group ID for which you want to revoke privileges, then click Revoke. To select multiple users or groups, hold the CTRL key down while selecting the users or groups.



Encrypting a FileTo encrypt a file or fields in a file, check the Encrypt File tab. A window similar to the following example appears:

In the Accounts area of the screen, click the account where you want to encrypt files. With the right mouse button, click the file in which you want to encrypt files.

1-50


The Encrypt File dialog box appears, as shown in the following example:

Encrypting an Entire Record

Define the following information to encrypt an entire record:

Data File – The full path to the data file where you want to encrypt data.Dict File – The full path to the dictionary file where you want to encrypt data.Parameters – The RESIZE parameters to use when encrypting the file. For a list of valid parameters, see RESIZE in the UniVerse User Reference. Leave this box empty if you do not want to resize the file.



Whole record – If you want to encrypt each field in the record, click the Whole record check box. Encrypt Info – Define the following information in the Encrypt Info area if you are encrypting and entire record:

Algorithm – Enter the algorithm to use for encrypting the record. For a list of valid algorithms, see “UniVerse Encryption Algorithms” on page 12.Key – Select the encryption key you want to use when encrypting the data from the Key list.Password – Enter the password corresponding to the encryption key, if one exists.

Click Apply. UniVerse encrypts every field for every record in the file.

Encrypting Specific Fields In a Record

Define the following information to encrypt specific fields in a record:

Data File – The full path to the data file where you want to encrypt data.Dict File – The full path to the dictionary file where you want to encrypt data.Parameters – The RESIZE parameters to use when encrypting the file. For a list of valid parameters, see RESIZE in the UniVerse User Reference. Leave this box empty if you do not want to resize the file.

1-52


Fields Encryption Info – Click the name of the field you want to encrypt, then click Set. The Field Encrypt Info dialog box appears, as shown in the following example:

Algorithm – Select the algorithm to use when encrypting the field. For a list of valid algorithms, see “UniVerse Encryption Algorithms” on page 12.Key – Select the key to use when encrypting the file.Password – Enter the password corresponding to the key.

When you have defined all the fields you want to encrypt, click Encrypt.



Decrypting a FileTo decrypt a file or fields in a file, check the Encrypt Files tab. A window similar to the following example appears:

In the Accounts area of the screen, click the account where you want to decrypt files. With the right mouse button, click the file in which you want to decrypt fields.

1-54


The Decrypt File dialog box appears, as shown in the following example:

Decrypting an Entire RecordDefine the following information to decrypt an entire record:

Data File – The full path to the data file where you want to decrypt data.Dict File – The full path to the dictionary file where you want to decrypt data.Parameters – The RESIZE parameters to use when decrypting the file. For a list of valid parameters, see the UniVerse User Reference. Leave this box empty if you do not want to resize the file.



Whole Record – If you want to decrypt each field in the record, click the Whole record check box. Encrypt Info – Define the following information in the Encrypt Info area if you are encrypting an entire record:

Key – Select the encryption key you want to use when decrypting the data from the Key list.Password – Enter the password corresponding to the encryption key, if one exists.

Click Apply. UniVerse decrypts every field for every record in the file.

Decrypting Specific Fields in a Record

Define the following information to decrypt specific fields in a record:

Data File – The full path to the data file where you want to decrypt data.Dict File – The full path to the dictionary file where you want to decrypt data.Parameters – The RESIZE parameters to use when decrypting the file. For a list of valid parameters, see the UniVerse User Reference. Leave this box empty if you do not want to resize the file.Fields Encryption Info – Click the name of the field you want to decrypt, then click Set. The Field Encrypt Info dialog box appears, as shown in the following example:

Key – Select the key to use when decrypting the file.Password – Enter the password corresponding to the key.

When you have defined all the fields you want to decrypt, click Decrypt.

1-56


Listing Encryption InformationTo list encryption information for a file, click the Encrypt Files tab. A window similar to the following example appears:

In the Accounts area of the screen, click the account where you want to view encryption information. With the right mouse button, click the file for which you want to view encryption information, then click List Encrypt Info.

Each field that has been encrypted is listed in the Encrypted Fields area of the dialog box. If the entire record is encrypted, Whole record appears under the Field column.



Viewing Audit InformationTo view audit information, from the UniVerse Data Encrypt Configure dialog box, click Audit Trail Data. A dialog box similar to the following example appears:

The Audit Trail Data dialog box offers the following options:

Backup Audit Data To – If you want to back up the current audit file, enter the patch to the file where you want to back up the file, or click Browse to select the file. After backing up the file, the current audit file is cleared.Use Audit File – If you want to display audit data located in a file different from the current audit file, enter the full patch to the file you want to display, or click Browse to select the file.After Date – UniAdmin will display the audit information after the date you specify. Enter the date in the mm/dd/yyyy format.

1-58


Before Date – UniAdmin will display the audit information before the date you specify. Enter the date in the mm/dd/yyyy format.Users – UniAdmin will display audit trail data for the users you specify. Click Choose User. A dialog box similar to the following example appears:

To select multiple users, hold the CTRL key down while selecting the desired users.



Operations – UniAdmin will display audit trail information or the operation you specify. Click Choose Operations. The following dialog box appears:

To select multiple operations, hold the CTRL key down while selecting the desired operation. Valid operations are:

CREATE – Create encryption keyDELETE – Delete encryption keyGRANT – Grant key accessREVOKE – Revoke key accessACTIVATE – Activate encryption keyDEACTIVT – Deactivate encryption keyENABLE – Enable encryption keyDISABLE – Disable encryption keyENCRYPT – Encrypt a fileDECRYPT – Decrypt a fileRMKEYSTR – Delete a key storeFLHDCHG – Change encryption flag in file headerCREATEWLT – Create a wallet

1-60


DELETWLT – Delete a walletWLTADKEY – Add a key to a walletWLTRMKEY – Remove a key from a walletPRCKEYST – Key store import or export

If you only want to display audit trail data for failed operations, select the Failed operations only check box.

Click Get Audit Data. UniAdmin displays the audit trail data for the criteria you specified, as shown in the following example:


:\ProgMarch


2Chapter

ram Fi18 201


XML Encoding

XML for IBM UniVerse . . . . . . . . . . . . . . . . 2-2 Document Type Definitions . . . . . . . . . . . . . . 2-3 XML Schema . . . . . . . . . . . . . . . . . . 2-3 The Document Object Model (DOM) . . . . . . . . . . . 2-3 Well-Formed and Valid XML Documents . . . . . . . . . 2-4Creating an XML Document from RetrieVe . . . . . . . . . . 2-5 Create the &XML& File . . . . . . . . . . . . . . . 2-5 Mapping Modes . . . . . . . . . . . . . . . . . 2-5 XML Configuration File . . . . . . . . . . . . . . . 2-13 xmlconfig Parameters . . . . . . . . . . . . . . . . 2-15 The Mapping File . . . . . . . . . . . . . . . . . 2-24 Distinguishing Elements . . . . . . . . . . . . . . . 2-27 Root Element Attributes . . . . . . . . . . . . . . . 2-27 Association Elements . . . . . . . . . . . . . . . . 2-34 Mapping File Example . . . . . . . . . . . . . . . 2-35 How Data is Mapped . . . . . . . . . . . . . . . . 2-39 Mapping Example . . . . . . . . . . . . . . . . . 2-41TCL Commands for XML . . . . . . . . . . . . . . . . 2-43 Session-level TCL Commands . . . . . . . . . . . . . 2-43 XMLSETOPTIONS . . . . . . . . . . . . . . . . 2-43 XMLGETOPTIONS . . . . . . . . . . . . . . . . 2-45 XMLGETOPTIONVALUE . . . . . . . . . . . . . . 2-46 Existing TCL Command Affected by XMLSETOPTIONS

Command or XMLSetOptions() API . . . . . . . . . . . 2-47Creating an XML Document Using RetrieVe . . . . . . . . . . 2-49 Examples . . . . . . . . . . . . . . . . . . . . 2-50Creating an XML Document with UniVerse SQL . . . . . . . . 2-59

les\Adobe\FrameMaker8\UniVerse 10.3\10.3rebranded\newfeatures\Ch2TOC.fm0 1:51 pm UniVerse 10 3 New Features

2-2 Un

gMarch 18, 2010 1:51 pm UniVerse 10.3 New Features

Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta

Processing Rules for UniVerse SQL SELECT Statements. . . . . 2-60 XML Limitations in UniVerse SQL . . . . . . . . . . . 2-62 Examples . . . . . . . . . . . . . . . . . . . . 2-62Creating an XML Document Through UniVerse Basic . . . . . . . 2-71 Using the XMLExecute() Function . . . . . . . . . . . . 2-72 XMLSetOptions. . . . . . . . . . . . . . . . . . 2-75 XMLGetOptions . . . . . . . . . . . . . . . . . 2-77 XMLGetOptionValue . . . . . . . . . . . . . . . . 2-78 Existing APIs Affected by XML Options . . . . . . . . . . 2-93UniVerse Basic Example . . . . . . . . . . . . . . . . 2-121

iVerse 10.2 New Features


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 Exnsible Markup Language (XML) is the universal format for struc-tured documents and data on the Web.

XML documents are text documents, intended to be processed by an application, such as a web browser.

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 Web site at http://www.w3.org/TR/REC-xml.

UniVerse enables you to receive and create XML documents, and process them through UniVerse Basic, UniVerse SQL, or RetrieVe. In order to work with the XML documents in UniVerse, you will need to know some key terms:

Document Type DefinitionsXML SchemaDocument Object ModelWell-Formed and Valid Documents

2-3


Document Type DefinitionsYou 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. 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, and you can create DTDs in an XML document.

XML SchemaThe structure of the XML document can also be defined using XML Schema, which is an XML-based alternative to the DTD. An XML Schema defines a class of XML documents, including the structure, content and meaning of the XML document. XML Schema is useful because it is written in XML and is extensible to future additions. You can create schema with XML, and you can use schema to validate XML. The XML Schema language can also be referred to as XML Schema Definition (XSD).

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 DocumentsAn 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 or schema. Not all XML documents must be valid.

For optimum exchange of data, you should try to ensure that your XML documents are valid.

2-5


Creating an XML Document from RetrieVeYou can create an XML document from UniVerse files through RetrieVe. To create an XML document through RetrieVe, complete the following steps:

1. If you are the originator of the DTD or XML Schema, use RetrieVe to create the DTD or XML Schema. If you are not the originator of the DTD or XML Schema, analyze the DTD or XML Schema associated with the application to which you are sending the XML file. Determine which of your dictionary attributes correspond to the DTD or XML Schema elements. You can also refer to Mapping to an External Schema at the end of this section.

2. Create an XML mapping file, if necessary. The mapping file will enable users to create many different forms of XML.

3. List the appropriate fields using the LIST command.4. Add the TOXML command to generate the XML document.

Create the &XML& FileUniVerse stores XML mapping files in the &XML& directory file. This directory is automatically created with new accounts. If you have an older account, you can create this file for PICK flavor accounts using the following command:

CREATE.FILE &XML& 3,1,18 1,1,19 To create the &XML& account in other flavor accounts, use the following command:

CREATE.FILE &XML& 19

Mapping ModesUniVerse supports three modes for mapping data to XML files. These modes are:

Attribute-centricElement-centricMixed



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, if there is no association, is fieldname_MV or _MS.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& directory.

The following example shows data created in attribute mode:

>LIST STUDENT.F LNAME CGA TOXML SAMPLE 1

<?xml version="1.0" encoding="UTF-8"?><ROOT><STUDENT.F _ID = "424325656" LNAME = "Martin"> <CGA_MV SEMESTER = "SP94" COURSE_HOURS = "3" TEACHER = "Masters" COURSE_HOURS = "3" TEACHER = "Fisher"> <CGA_MS COURSE_GRD = "C" COURSE_NBR = "PY100" COURSE_NAME = "Introduction to Psychology"/> <CGA_MS COURSE_GRD = "C" COURSE_NBR = "PE100" COURSE_NAME = "Golf - I"/> </CGA_MV></STUDENT.F></ROOT>>

Element-centric Mode

In the element-centric mode, as in the attribute-centric mode, each record becomes an XML element. The following rules apply:

2-7


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 sub-element, each multivalued field belonging to the association becomes a sub-element that may contain multi-subvalued sub-elements. There are two ways to display empty values in multivalued fields belonging to an associ-ation. For detailed information, see Displaying Empty Values in Multivalued Fields in An Association.By default, UniVerse converts text marks to an empty space.

Specify that you want to use element-centric mapping by using the ELEMENTS keyword in the RetrieVe statement. You can also define treated-as = “ELEMENT” in the U2XMLOUT.map file, so that all XML will be created in element mode.

The following example shows data created in element mode:

>LIST STUDENT.F LNAME CGA TOXML ELEMENTS SAMPLE 1

<?xml version="1.0" encoding="UTF-8"?><ROOT><STUDENT.F> <_ID>424325656</_ID> <LNAME>Martin</LNAME> <CGA_MV> <SEMESTER>SP94</SEMESTER> <COURSE_HOURS>3</COURSE_HOURS> <TEACHER>Masters</TEACHER> <CGA_MS> <COURSE_GRD>C</COURSE_GRD> <COURSE_NBR>PY100</COURSE_NBR> <COURSE_NAME>Introduction to Psychology</COURSE_NAME> </CGA_MS> <COURSE_HOURS>3</COURSE_HOURS> <TEACHER>Fisher</TEACHER> <CGA_MS> <COURSE_GRD>C</COURSE_GRD> <COURSE_NBR>PE100</COURSE_NBR> <COURSE_NAME>Golf - I</COURSE_NAME> </CGA_MS> </CGA_MV></STUDENT.F></ROOT>>



Displaying Empty Values in Multivalued Fields in An Association

UniVerse displays empty values in multivalued fields belonging to an association depending on the setting of the Matchelement field in the U2XMLOUT.map file.

Emptyattribute

This attribute determines how to display the empty attributes for multivalued fields belonging to an association in the generated XML document and in the associated DTD or XML Schema. This option can be specified in the U2XMLOUT.map file, or in an individual mapping file.

0 - Hides the empty attributes in the multivalued fields. 1 - Shows the empty attributes in the multivalued fields.

Matchelement

This element specifies how UniVerse displays empty values in multivalued fields belonging to an association in the XML output.

If Matchelement is set to 1 (the default), matching values or subvalues belonging to the same association display as empty elements for matching pairs.

2-9


Consider the following example:

LIST STUDENT.F LNAME FNAME COURSE_NBR COURSE_GRD COURSE_NAME SEMESTER01:04:52pm 06 Jan 2009 PAGE 1

STUDENT.... 424-32-5656Last Name.. MartinFirst Name. SallyCrs #......................... GD. Course Name.... TermPY100 C Introduction to SP94 PsychologyPE100 Golf - I

STUDENT.... 521-81-4564Last Name.. SmithFirst Name. HarryCrs #......................... GD. Course Name.... TermCS130 A Intro to FA93 Operating SystemsCS100 Intro to Computer SciencePY100 B Introduction to Psychology

CS131 B Intro to SP94 Operating SystemsCS101 B Intro to Computer SciencePE220 Racquetball

...>

Notice that three of the GRADE fields are empty, while their associated values for COURSE # and COURSE NAME are not.



When Matchelement is set to 1, the missing values for COURSE _GRD, <COURSE_GRD></COURSE_GRD>, display as a empty values in the XML document, as shown in the following example:

>LIST STUDENT.F LNAME CGA TOXML ELEMENTS

<?xml version="1.0" encoding="UTF-8"?><ROOT><STUDENT.F> <_ID>424325656</_ID> <LNAME>Martin</LNAME> <CGA_MV> <SEMESTER>SP94</SEMESTER> <COURSE_HOURS>3</COURSE_HOURS> <TEACHER>Masters</TEACHER> <CGA_MS> <COURSE_GRD>C</COURSE_GRD> <COURSE_NBR>PY100</COURSE_NBR> <COURSE_NAME>Introduction to Psychology</COURSE_NAME> </CGA_MS> <COURSE_HOURS>3</COURSE_HOURS> <TEACHER>Fisher</TEACHER> <CGA_MS> <COURSE_GRD/> empty value <COURSE_NBR>PE100</COURSE_NBR> <COURSE_NAME>Golf - I</COURSE_NAME> </CGA_MS> </CGA_MV></STUDENT.F><STUDENT.F> <_ID>521814564</_ID> <LNAME>Smith</LNAME> <CGA_MV> <SEMESTER>FA93</SEMESTER> <COURSE_HOURS>5</COURSE_HOURS> <TEACHER>James</TEACHER> <CGA_MS> <COURSE_GRD>A</COURSE_GRD> <COURSE_NBR>CS130</COURSE_NBR> <COURSE_NAME>Intro to Operating Systems</COURSE_NAME> </CGA_MS> <COURSE_HOURS>3</COURSE_HOURS> <TEACHER>Gibson</TEACHER> <CGA_MS> <COURSE_GRD/> empty value <COURSE_NBR>CS100</COURSE_NBR> <COURSE_NAME>Intro to Computer Science</COURSE_NAME> </CGA_MS> <COURSE_HOURS>3</COURSE_HOURS> <TEACHER>Masters</TEACHER> <CGA_MS> <COURSE_GRD>B</COURSE_GRD> <COURSE_NBR>PY100</COURSE_NBR>

2-11


<COURSE_NAME>Introduction to Psychology</COURSE_NAME> </CGA_MS> </CGA_MV> <CGA_MV> <SEMESTER>SP94</SEMESTER> <COURSE_HOURS>5</COURSE_HOURS> <TEACHER>Aaron</TEACHER> <CGA_MS> <COURSE_GRD>B</COURSE_GRD> <COURSE_NBR>CS131</COURSE_NBR> <COURSE_NAME>Intro to Operating Systems</COURSE_NAME> </CGA_MS> <COURSE_HOURS>4</COURSE_HOURS> <TEACHER>Gibson</TEACHER> <CGA_MS> <COURSE_GRD>B</COURSE_GRD> <COURSE_NBR>CS101</COURSE_NBR> <COURSE_NAME>Intro to Computer Science</COURSE_NAME> </CGA_MS> <COURSE_HOURS>3</COURSE_HOURS> <TEACHER>Fisher</TEACHER> <CGA_MS> <COURSE_GRD/> empty value <COURSE_NBR>PE220</COURSE_NBR> <COURSE_NAME>Racquetball</COURSE_NAME> </CGA_MS> </CGA_MV></STUDENT.F>...

This is the default behavior.



When Matchelement is set to 0, the missing value for COURSE_GRD, <COURSE_GRD></COURSE_GRD>, is ignored in the XML document, as shown in the following example:

LIST STUDENT.F LNAME CGA TOXML ELEMENTS<?xml version="1.0" encoding="UTF-8"?><ROOT><STUDENT.F> <_ID>424325656</_ID> <LNAME>Martin</LNAME> <CGA_MV> <SEMESTER>SP94</SEMESTER> <COURSE_HOURS>3</COURSE_HOURS> <TEACHER>Masters</TEACHER> <CGA_MS> <COURSE_GRD>C</COURSE_GRD> <COURSE_NBR>PY100</COURSE_NBR> <COURSE_NAME>Introduction to Psychology</COURSE_NAME> </CGA_MS> <COURSE_HOURS>3</COURSE_HOURS> <TEACHER>Fisher</TEACHER> <CGA_MS>

missing value <COURSE_NBR>PE100</COURSE_NBR> <COURSE_NAME>Golf - I</COURSE_NAME> </CGA_MS> </CGA_MV></STUDENT.F><STUDENT.F> <_ID>521814564</_ID> <LNAME>Smith</LNAME> <CGA_MV> <SEMESTER>FA93</SEMESTER> <COURSE_HOURS>5</COURSE_HOURS> <TEACHER>James</TEACHER> <CGA_MS> <COURSE_GRD>A</COURSE_GRD> <COURSE_NBR>CS130</COURSE_NBR> <COURSE_NAME>Intro to Operating Systems</COURSE_NAME> </CGA_MS> <COURSE_HOURS>3</COURSE_HOURS> <TEACHER>Gibson</TEACHER> <CGA_MS>

missing value <COURSE_NBR>CS100</COURSE_NBR> <COURSE_NAME>Intro to Computer Science</COURSE_NAME> </CGA_MS> <COURSE_HOURS>3</COURSE_HOURS> <TEACHER>Masters</TEACHER> <CGA_MS> <COURSE_GRD>B</COURSE_GRD> <COURSE_NBR>PY100</COURSE_NBR> <COURSE_NAME>Introduction to Psychology</COURSE_NAME>

2-13


</CGA_MS> </CGA_MV> <CGA_MV> <SEMESTER>SP94</SEMESTER> <COURSE_HOURS>5</COURSE_HOURS> <TEACHER>Aaron</TEACHER> <CGA_MS> <COURSE_GRD>B</COURSE_GRD> <COURSE_NBR>CS131</COURSE_NBR> <COURSE_NAME>Intro to Operating Systems</COURSE_NAME> </CGA_MS> <COURSE_HOURS>4</COURSE_HOURS> <TEACHER>Gibson</TEACHER> <CGA_MS> <COURSE_GRD>B</COURSE_GRD> <COURSE_NBR>CS101</COURSE_NBR> <COURSE_NAME>Intro to Computer Science</COURSE_NAME> </CGA_MS> <COURSE_HOURS>3</COURSE_HOURS> <TEACHER>Fisher</TEACHER> <CGA_MS>

missing value <COURSE_NBR>PE220</COURSE_NBR> <COURSE_NAME>Racquetball</COURSE_NAME> </CGA_MS> </CGA_MV></STUDENT.F>

</MAIN>

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 statement.

XML Configuration FileThe xmlconfig file allows you to specify the encoding used in XML documents and to set other XML options. There are two levels of XML configuration files:

System level. The default location of the system-level xmlconfig file is the UniVerse home directory.Account level. The default location of the account-level xmlconfig file is under the account directory. Configuration parameters in the account-level xmlconfig file override the settings in the system-level xmlconfig file.



The xmlconfig file is a text file in which each line is a key/value pair, as shown in the following example:

encoding=utf-8in-encoding=EUC-JPout-encoding=uft-8out-xml-declaration=trueout-pretty-format=trueout-newline=CR-LF

Keys and values are case-insensitive.

When you start a UniVerse session, UniVerse loads the xmlconfig files and validates the options. If it finds an error in an xmlconfig file, it reports one of the following error messages in errlog, if errlog exists in the UniVerse home directory:

38 Invalid XML config key 'key_name' at line line_number in xmlconfig file(xmlconfig_filename)39 Invalid XML config value 'value_string' at line line_number in xmlconfig file(xmlconfig_filename)40 Invalid XML config format 'name_value_string' at line line_number in xmlconfig file(xmlconfig_filename)

If an error is found in an xmlconfig file, no part of its content is loaded.

xmlconfig ParametersThe following XML options are available in the system-level and account-level xmlconfig files.

Parameter Description Default

encoding Specifies a setting for the encoding to be used in general in XML documents, such as UTF-8. If the setting is default, XML documents use the operating system’s default encoding.Valid encoding settings can be found at http://www.iana.org/assignments/ character-sets

default

xmlconfig Parameters

2-15


in-encoding Specifies a setting for the encoding to be used for strings that are imported to XML libraries. If NULL, strings imported to XML libraries use the same encoding as specified in the general encoding parameter (see above).

default

out-encoding Specifies a setting for the encoding to be used for strings exported from XML libraries. If NULL, strings exported from XML libraries use the same encoding as specified in the general encoding parameter.

default

version Specifies the XML version number. Currently, 1.0 is the only version supported.

1.0

standalone A flag that specifies whether the XML document is dependent on another XML document. yes – The XML document is standaloneno – The XML document is dependent on another XML document

yes

out-newline Specifies the newline character to be used in XML documents. NULL – Uses the operating system default (CR-LF for Windows or CR for UNIX)CR – Carriage return character (xD).CR-LF – Carriage return and linefeed characters (xD xA).LF – Linefeed character (xA).

NULL

out-xml-declaration Specifies whether the XML declaration is to appear in output.true – The XML declaration appears in output.false – The XML declaration does not appear in output.

true


xmlconfig Parameters (Continued)



out-format-pretty-print Specifies whether to add white space to produce an indented, human-readable XML document. The exact nature of the transformations is not specified by this parameter. true – Pretty-prints XML documents. Setting this state also sets the out-format-canonical parameter to false.false – Does not pretty-print XML documents. Setting this state also sets the out-format-canonical parameter to true.

true

out-normalize-characters Specifies whether to perform W3C text normalization of the characters in the document at the time they are written in output. Only those characters that are written are subject to change in the normal-ization process. The DOM document itself remains unchanged.true – Performs W3C text normalization.false – Does not perform text normalization.

true

out-split-cdata-sections Specifies whether to split character data (CDATA) sections of XML documents containing the CDATA termination marker ]]> or characters that cannot be represented in the output encoding.true – Splits CDATA sections containing the termination marker ]]> or characters that cannot be represented in the output encoding, and output the characters as their Unicode numeric character references. If a CDATA section is split, a warning is issued.false – Does not split CDATA sections. Issues an error if a CDTA section contains an unrepresentable character.

true



2-17


out-validation Specifies whether to validate the XML document against the abstract schema while the document is being serialized.true – Validates the XML document while it is being serialized. If validation errors are found during the serialization process, the error handler is notified. Setting this state also sets the use-abstract-schema parameter to true.false – Does not validate the XML document while it is being serialized.

false

out-expand-entity-references Specifies whether to expand EntityRef-erence nodes while an XML document is being serialized.true – Expands EntityReference nodes in the XML document while it is being serialized.false – Does not expand EntityReference nodes in the XML document while it is being serialized.

false

out-whitespace-in-element-content

Specifies whether to output all white space in an XML document.true – Outputs all white space.false – Outputs only the white space that is not within element content.

true

out-discard-default-content Specifies whether to suppress output of default content in the Attr nodes of an XML document.true – Suppresses output of default content in Attr nodes.false – Outputs all attributes and all content.

true





out-format-canonical Specifies whether the formatting process writes the XML document according to the rules specified in the Canonical XML specification, rather than pretty-prints the document.true – Prints XML documents in canonical format. Setting this state also sets the out-format-pretty-print parameter to false.false – Pretty-prints XML documents. Setting this state also sets the out-format-pretty-print parameter to true.

false

out-write-BOM A nonstandard extension was added in Xerces-C++ 2.2 (or XML4C 5.1) to enable writing the byte order mark (BOM) in the XML stream.Specifies whether to enable writing the byte order mark in the XML stream under certain conditions.true – Enables writing the byte order mark if a DOMDocumentNode is rendered for serialization and if the output encoding is one of the following:UTF-16UTF-16LEUTF-16BEUCS-4UCS-4LEUCS-4BEfalse – Disables writing the byte order mark.

false



2-19


matchelement Specifies how UniVerse displays empty values in multivalued fields belonging to an association in XML output.0 – For matching values or subvalues belonging to the same association, the empty value is ignored in the generated XML document.1 – For matching values or subvalues belonging to the same association, the second value is displayed as an empty element in the generated XML document.

1

elementmode Specifies whether to create XML documents in element mode.0 – Create XML documents in attribute mode. This mode does not produce an extra level of element tags. The display name of each field is used as an element tag. The content of the field is shown as attribute/value pairs within the field’s element tag. For example:

:LIST MYSTUDENT '1111' TOXML<?xml version="1.0"?><ROOT><MYSTUDENT _ID = "1111"/></ROOT>

1 – Create XML documents in element mode. This mode produces an extra level of element tags. All fields referenced in the query are represented as XML elements. The display name of the field is used for the field’s element tags. The display name of each field is used as a nested element tag. The content of the field is shown within the element tags. For example:

:LIST MYSTUDENT '1111' TOXML<?xml version="1.0"?><ROOT><MYSTUDENT> <_ID>1111</_ID></MYSTUDENT></ROOT>

1





schematype Specifies the format of the schema used in XML output.inline – Only the top-level element (the record element) is defined globally. All other elements are children of the record element. A drawback of this format is that it is difficult for other schemas to reference child elements.ref – All elements are global; every element is a child of the root element. This format is somewhat restrictive: all elements are at the same level, so the element names must be unique. However, this format includes a ref tag for every element, which makes it easier for other schemas to reference elements.

ref

hidemv Specifies whether to hide <MV> and </MV> tags for multivalued fields belonging to an association in the generated XML document and in the associated DTD or XMLSchema. This parameter applies only if the XML document is created in element mode.By default, the MV tag is generated as “association name_MV”.0 – Show MV tags for multivalued fields.1 – Hide MV tags for multivalued fields.

0

hidems Specifies whether to hide <MS> and </MS> tags for multi-subvalued fields belonging to an association in the generated XML document and in the associated DTD or XMLSchema. This parameter applies only if the XML document is created in element mode.0 – Show MS tags for multi-subvalued fields.1 – Hide MS tags for multi-subvalued fields.

0



2-21


collapsemv Specifies whether to collapse <MV> and </MV> tags, using only one set of these tags for multivalued fields belonging to an association in the generated XML document and in the associated DTD or XMLSchema. This parameter applies only if the XML document is created in element mode.0 – Expand MV tags for multivalued fields.1 – Collapse MV tags multivalued fields.

0

collapsems Specifies whether to collapse <MS> and </MS> tags, using only one set of these tags for multi-subvalued fields belonging to an association in the generated XML document and in the associated DTD or XMLSchema. This parameter applies only if the XML document is created in element mode.0 – Expand MS tags for multi-subvalued fields.1 – Collapse MS tags multi-subvalued fields.

0

hideroot Specifies whether to create the entire XML document or only a section of it.0 – UniVerse creates the entire XML document as well as a DTD and an XMLSchema.1 – UniVerse creates only the record portion of the XML document; it does not create a DTD or an XMLSchema. For example, you may want only a section of the XML document if you are using the SAMPLE keyword and other conditional clauses

0

root Specifies the name of the root element in XML output.

NULL





The Mapping FileYou can create the U2XMLOUT.map file in $UVHOME/&XML& to define commonly used global settings for creating XML documents. UniVerse reads and processes this mapping file each time UniVerse is started. For example, if you normally create element-centric output, and display empty elements for missing values or subvalues belonging to the same association, you can define these settings in the U2XMLOUT.map file, as shown in the following example:

<U2 matchelement = “1” treated-as = “element”/>

Defining these settings in the mapping file eliminates the need to specify them in each RetrieVe statement.

UniVerse processes XML options as follows:

1. Reads options defined in the U2XMLOUT.map file when UniVerse starts.2. Reads the $UVHome\xmlconfig file.3. Reads the account information from the XMLConfig file.4. Reads any options defined in a mapping file. This mapping file resides in

the &XML& directory in the current account, and is specified in the RetrieVe statement, as shown in the following example:LIST STUDENT.F SEMESTER TOXML XMLMAPPING mystudent.map

5. Processes any options you specify in the RetrieVe statement.

encode Specifies the ASCII code for the character to be encoded.

NULL

target Specifies the URL of the target namespace for XML output.

NULL

xmlns:namespace Specifies the URL of the XML namespace for XML output.

NULL



2-23


Options you specify in the RetrieVe statement override options defined in the mapping file. Options defined in the mapping file override options defined in the U2XMLOUT.map file.

A mapping file has the following format:

<?XML version=”1.0”?>  <U2xml:mapping file=”file_name”

Note: We suggest that you only put individual field options in the mapping file. Global options should be set in either the U2XMLOUT.map file or the xmlconfig file.

hidemv=”0” hidems=”0” hideroot=”0” collapsemv=”0” collapsems=”0” emptyattribute=”0” hastm=”yes” | “1” matchelement=”0” |”1” schematype=”ref” targetnamespace=”targetURL” xmlns:NAME=”URL” field=”dictionary_display_name” map-to=”name_in_xml_douniversec” type=”MV” | “MS” 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 (or Fmt)= “format -pattern”.. conversion (or Conv)= “conversion code” encode=”encoding characters” />

...

</U2xml-mapping>

The XML mapping file is, in itself, in XML format. 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 charac-teristics of a particular field’s 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 ElementsYou 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 defined in the dict file, making it a field element. If the field name is an association phrase, it is an association element.

The Mapping File Example section shows this in more detail.

Root Element AttributesThe 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. The record attribute in the root element changes the record name. The following example illustrates the record attribute:

record=”record-element-name”

2-25


Hideroot Attribute

The Hideroot attribute allows you to specify whether to create the entire XML document or only a section of it. For example, using the SAMPLE keyword or 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”

Hidemv Attribute

This attribute specifies whether to hide <MV> and </MV> tags for multivalued fields belonging to an association in the generated XML document and in the associated DTD or XML Schema. This parameter applies only if the XML document is created in element mode.

0 - Show MV tags for multivalued fields. 1 - HideMV tags for multivalued fields.

You can also use this option with XMLEXECUTE().

Note: If the document is created in attribute mode, it is not possible to eliminate the extra level of element tags.

Hidems Attribute

This attribute specifies whether to hide <MS> and </MS> tags for multivalued fields belonging to an association in the generated XML document and in the associated DTD or XML Schema. This parameter applies only if the XML document is created in element mode.

0 - ShowMS tags for multi-subvalued fields. 1 - Hide MS tags for multi-subvalued fields.

You can also use this option with XMLEXECUTE().

Note: If the document is created in attribute mode, it is not possible to eliminate the extra level of element tags.



Collapsemv Attribute

This attribute specifies whether to collapse <MV> and </MV> tags, using only one set of these tags for multivalued fields belonging to an association in the generated XML document and in the associated DTD or XMLSchema. This parameter applies only if the XML document is created in element mode.

0 - Expand MV tags for each set of multivalued fields. 1 - CollapseMV tags for each set of multivalued fields.

Collapsems Attribute

This attribute specifies whether to collapse <MS> and </MS> tags, using only one set of these tags for multi-subvalued fields belonging to an association in the generated XML document and in the associated DTD or XMLSchema. This parameter applies only if the XML document is created in element mode.

0 - Expand MS tags for multi-subvalued fields. 1 - Collapse MS tags for multi-subvalued fields.

Emptyattribute

This attribute determines how to display the empty attributes for multivalued fields belonging to an association in the generated XML document. This option can be specified in the U2XMLOUT.map file, or in an individual mapping file.

0 - Ignores the empty attributes in the multivalued fields. 1 - Shows the empty attributes in the multivalued fields.

Namespace Attributes

UniVerse provides the following attributes for defining namespaces:

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 the schema location.

2-27


If you define the targetnamespace and other explicit namespace definitions, UniVerse checks if the explicitly 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.

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 in the document.



The following example shows the output if the TARGETNAMESPACE attribute is set to “www.ibm.com”:

XMLSETOPTIONS TARGETNAMESPACE = “http:://www.ibm.com”

>LIST STUDENT.F LNAME COURSE_NBR COURSE_GRD COURSE_NAME SEMESTER FNAME TOXML WITHSCHEMA XMLMAPPING student.map<?xml version="1.0"?><xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema" targetNamespace="www.ibm.com" xmlns:ibm="http://www.ibm.com" xmlns="www.ibm.com" elementFormDefault="qualified"> <xsd:annotation> <xsd:documentation xml:lang="en"> account: C:\IBM\ud71\XMLDemo\udxml command: LIST STUDENT.F LNAME COURSE_NBR COURSE_GRD COURSE_NAME SEMESTER FNAME TOXML WITHSCHEMA XMLMAPPING student.map </xsd:documentation> </xsd:annotation> <xsd:element name="MAIN"> <xsd:complexType> <xsd:sequence> <xsd:element name="STUDENT" type="STUDENTType" minOccurs="0" maxOccurs="unbounded"/> </xsd:sequence> </xsd:complexType> </xsd:element> <xsd:complexType name="STUDENTType"> <xsd:sequence> <xsd:element name="_ID" type="xsd:string"/> <xsd:element name="LNAME" type="xsd:string"/> <xsd:sequence minOccurs="0" maxOccurs="unbounded"> <xsd:element name="SEMESTER" type="xsd:string"/> <xsd:sequence minOccurs="0" maxOccurs="unbounded"> <xsd:element name="COURSE_GRD" type="xsd:string"/> <xsd:element name="COURSE_NAME" type="xsd:string"/> <xsd:element name="COURSE_NBR" type="xsd:string"/> </xsd:sequence> </xsd:sequence> <xsd:element name="FNAME" type="xsd:string"/> </xsd:sequence> </xsd:complexType></xsd:schema><?xml version="1.0"?><MAIN xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="www.ibm.com" xmlns:ibm="http://www.ibm.com"><STUDENT> <_ID>123456789</_ID> <LNAME>Martin</LNAME>

2-29


<SEMESTER>SP94</SEMESTER> <COURSE_GRD></COURSE_GRD> empty value <COURSE_NAME>Introduction to Psychology</COURSE_NAME> <COURSE_NBR>PY100</COURSE_NBR> <COURSE_GRD>C</COURSE_GRD> <COURSE_NAME>Golf - I</COURSE_NAME> <COURSE_NBR>PE100</COURSE_NBR> <FNAME>Sally</FNAME></STUDENT>

<STUDENT> <_ID>987654321</_ID> <LNAME>Miller</LNAME> <SEMESTER>FA93</SEMESTER> <COURSE_GRD>C</COURSE_GRD> <COURSE_NAME>Engineering Principles</COURSE_NAME> <COURSE_NBR>EG110</COURSE_NBR> <COURSE_GRD></COURSE_GRD> empty value <COURSE_NAME>Calculus- I</COURSE_NAME> <COURSE_NBR>MA220</COURSE_NBR> <COURSE_GRD>B</COURSE_GRD> <COURSE_NAME>Introduction to Psychology</COURSE_NAME> <COURSE_NBR>PY100</COURSE_NBR> <SEMESTER>SP94</SEMESTER> <COURSE_GRD>B</COURSE_GRD> <COURSE_NAME>Fluid Mechanics</COURSE_NAME> <COURSE_NBR>EG140</COURSE_NBR> <COURSE_GRD>B</COURSE_GRD> <COURSE_NAME>Circut Theory</COURSE_NAME> <COURSE_NBR>EG240</COURSE_NBR> <COURSE_GRD></COURSE_GRD> empty value <COURSE_NAME>Calculus - II</COURSE_NAME> <COURSE_NBR>MA221</COURSE_NBR> <FNAME>Susan</FNAME></STUDENT>

</MAIN>>

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 XML Schema. If you use them together with the namespace attribute in the root element, you can indicate all of the local elements and local attributes that need to be qualified with the namespace.

File Attribute

UniVerse uses the File attribute to process both RetrieVe and UniVerse SQL commands. If you do not define the file attribute exactly as it is used on the command line, the 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, an I-descriptor, or an ‘association phrase name’. For more information, see Association Elements.

Field=”field-name”

Note: The file and field attributes are used to identify the query file and field needed to change the default directions. Use these attributes in the same element of the XML mapping file to pinpoint the database file and field.

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 uses the dictionary display 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”

2-31


Treated-as Attribute

The Treated-as attribute determines if the field should be treated as an element or an attribute in the generated XML document.

Matchelement Attribute

The Matchelement attribute specifies whether to display empty elements for missing values or subvalues belonging to the same association, or to ignore the missing values.

Encode Attribute

The Encode attribute encodes unprintable characters, or characters that have special meanings in XML, such as { : }, 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”

Fmt AttributeThe Fmt attribute changes the format defined in the dictionary record to the format you define.

fmt=”new format code” | format = “new format code”

Association ElementsAn association element contains the following four attributes:

file = “file name”field = “association phrase name”association-mv = “new multivalue element tag”association-ms = “new multi-subvalue element tag”



Mapping File ExampleThe following example illustrates the student.map mapping file:

 <U2 root="main" collapsemv='1' collapsems='1' schema="ref" hidemv="1" hidems="1" hideroot="0" elementformdefault="qualified" attributeformdefault="qualified" treated-as="element" /> <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" /> <U2 file="STUDENT.F" field = "TEACHER" type="ms" treated-as="element" />

2-33


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 attribute-centric 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.

Note: The global attributes listed above are not defined because they are set to “1”.

The next example illustrates an XMLSchema using the mapping file in the previous example.



Use the following command to create the .xsd schema:

>LIST STUDENT.F LNAME SEMESTER COURSE_NBR TOXML XMLMAPPING student.map SCHEMAONLY

<?xml version="1.0" encoding="UTF-8"?><xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema" targetNamespace="www.ibm.com" xmlns:intf="www.ibm.com" xmlns="www.ibm.com" elementFormDefault="qualified" attributeFormDefault="qualified"> <xsd:annotation> <xsd:documentation xml:lang="en"> account: C:\IBM\UV command: LIST STUDENT.F LNAME SEMESTER COURSE_NBR TOXML XMLMAPPING student.map SCHEMAONLY </xsd:documentation> </xsd:annotation> <xsd:element name="main"> <xsd:complexType> <xsd:sequence> <xsd:element ref="intf:STUDENT.F" minOccurs="0" maxOccurs="unbounded"/> </xsd:sequence> </xsd:complexType> </xsd:element> <xsd:element name="STUDENT.F"> <xsd:complexType> <xsd:sequence> <xsd:element name="_ID" minOccurs="0" type="xsd:string"/> <xsd:element name="LNAME" minOccurs="0" type="xsd:string"/> <xsd:sequence minOccurs="0" maxOccurs='unbounded'> <xsd:element name="SEMESTER" minOccurs="0" type="xsd:string"/> <xsd:sequence minOccurs="0" maxOccurs='unbounded'> <xsd:element name="COURSE_NBR" minOccurs="0" type="xsd:string"/> </xsd:sequence> </xsd:sequence> </xsd:sequence> </xsd:complexType> </xsd:element></xsd:schema>>

2-35


The next example illustrates an XML document created using the mapping file in the previous example. Use the following command to display the XML to the screen:

>LIST STUDENT.F LNAME SEMESTER COURSE_NBR TOXML XMLMAPPING student.map

<?xml version="1.0" encoding="UTF-8"?><main><STUDENT.F> <_ID>424325656</_ID> <LNAME>Martin</LNAME> <SEMESTER>SP94</SEMESTER> <COURSE_NBR>PY100</COURSE_NBR> <COURSE_NBR>PE100</COURSE_NBR></STUDENT.F><STUDENT.F> <_ID>521814564</_ID> <LNAME>Smith</LNAME> <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> <COURSE_NBR>PE220</COURSE_NBR></STUDENT.F>...</main>

Conversion Code ConsiderationsUniVerse uses the following rules when extracting data from database files:

If the dictionary record of a field you are extracting contains a conversion code, UniVerse 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 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 characters encountered in data, UniVerse uses the default XML entities to encode the data. For example, ‘<‘ becomes <, ‘>’ becomes >, ‘&’ becomes &, and ‘ “ ‘ becomes ". However, UniVerse does not convert ‘ to ', unless you specify it in attribute encode. (<, >, &, ', and " are all built-in entities for the XML parser).

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 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”

How Data is MappedRegardless 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>.

2-37


You can change these mapping defaults in the mapping file, as shown in the following example:

<U2xml:mapping root=”root_name”record=”record_name”/>



Mapping ExampleThe following example illustrates the creation of XML documents. These examples use the STUDENT.F file, which contains the following fields:

>LIST DICT STUDENT.F

DICT STUDENT.F 11:39:32am 11 Sep 2007 Page 1 Type &Field......... Field. Field........ Conversion.. Column......... Output Depth &Name.......... Number Definition... Code........ Heading........ Format Assoc..

@ID D 0 STUDENT 10L SID D 0 STUDENT 12R### S -##-## ##LNAME D 1 Last Name 40T SFNAME D 2 First Name 10L SMAJOR D 3 Major 20L SMINOR D 4 Minor 4L SADVISOR D 5 Advisor 8L SSEMESTER D 6 Term 4L S CGATESTSEME D 6 Term 4L SCOURSE_NBR D 7 Crs # 10L S CGATESTCOURSE D 7 Crs # 5L SCOURSE_GRD D 8 GD 3L S CGA?¼ ? ` ?GPA1 I SUBR('GPA1',C MD3 GPA 5R S

Type &Field......... Field. Field........ Conversion.. Column......... Output Depth &Name.......... Number Definition... Code........ Heading........ Format Assoc..

OURSE_HOURS,C OURSE_GRD)TEACHER I TRANS('COURSE Teacher 10L M CGA S',COURSE_NBR ,'TEACHER','X ')COURSE_NAME I TRANS('COURSE Course Name 15T S CGA S',COURSE_NBR ,'NAME','X')COURSE_HOURS I TRANS('COURSE Hours 5R M CGA S',COURSE_NBR ,CREDITS,'X')@ PH LNAME FNAME MAJOR MINOR ADVISOR

2-39


SEMESTER COURSE_NBR Type &Field......... Field. Field........ Conversion.. Column......... Output Depth &Name.......... Number Definition... Code........ Heading........ Format Assoc..

COURSE_GRDCGA PH SEMESTER COURSE_NBR COURSE_NAME COURSE_GRD COURSE_HOURS TEACHER@ORIGINAL S @ID M@SYNONYM S ID M

22 records listed.



TCL Commands for XMLYou can enter TCL commands to specify the encoding and other parameters for use in XML documents during the current session.

This section discusses the following TCL commands:

Session-level TCL CommandsExisting TCL Command Affected by XMLSETOPTIONS Command or XMLSetOptions() API

Session-level TCL CommandsThree XML commands are available from the TCL command line:

XMLSETOPTIONSXMLGETOPTIONSXMLGETOPTIONVALUE

XMLSETOPTIONS

SyntaxXMLSETOPTIONS <options>

Description

Use this command to set the encoding parameter and other options for XML documents in the current session. XML settings entered with this command override the settings in the system-level and account-level xmlconfig files during the current UniVerse session.

2-41


Parameters


XMLSETOPTIONS Parameters


options A string in the format of space-delimited key/value pairs.The XML options are the same as those in the xmlconfig file and accept the same values. Keys and values are case-insensitive.For a complete list of valid UniVerse XML options and settings, see xmlconfig Parameters.The XMLSETOPTIONS command also accepts three special strings as the options parameter. A special string must be entered as the only option:defaults – Sets all XML options to their default settings in the current session.

reload – Reloads the current system-level and account-level xmlconfig files, since they may have changed after you started your UniVerse session.

reset – Resets XML options to the original settings that were loaded when you started the UniVerse session.

Note: If UniVerse encounters a problem such as a syntax error or an invalid value in the options string, it displays an error message and none of the XML parameters are changed.

ExamplesThe following example shows the format for entering the XML options as key/value pairs in the TCL command.

XMLSETOPTIONS matchelement=1

The next example shows the format for entering a special string as the options parameter:

XMLSETOPTIONS defaults



XMLGETOPTIONS

Syntax

XMLGETOPTIONS <delimiterString>

Description

Use this command to return the values of the encoding parameter and other XML options in effect in the current UniVerse session.

Parameters


XMLGETOPTIONS Parameters


delimiterString Specifies the string to be used to separate the key/value pairs returned by the command.

Examples

The following example shows the format for entering delimiterString as the string used to separate the key/value pairs returned by the command. Key/value pairs can be separated by a space or by any string, such as <>, as shown in this example:

XMLGETOPTIONS <>

standalone=yes<>out-xml-declaration=true<>out-format-pretty-print=true<>out-normalize-characters=true<>out-split-cdata-sections=true<>out-validation=false<>out-expand-entity-references=false<>out-whitespace-in-element-content=true<>out-discard-default-content=true<>out-format-canonical=false<>out-write-bom=falsematchelement=1<>emptyattribute=0<>elementmode=0<>schematype=ref<>hidemv=0<>hidems=0<>collapsemv=0<>collapsems=0<>hideroot=0<>

2-43


If you enter the XMLSETOPTIONS command with no delimiterString, the key/value pairs are separated by a space, as shown in the next example:

XMLGETOPTIONS

standalone=yes out-xml-declaration=true out-format-pretty-print=true out-normalize-characters=true out-split-cdata-sections=true out-validation=false out-expand-entity-references=false out-whitespace-in-element-content=true out-discard-default-content=true out-format-canonical=false out-write-bom=false matchelement=1 emptyattribute=0 elementmode=0 schematype=ref hidemv=0 hidems=0 collapsemv=0 collapsems=0 hideroot=0

For a complete list of the standard UniVerse XML options and values returned by this command, see xmlconfig Parameters.

XMLGETOPTIONVALUE

Syntax

XMLGETOPTIONVALUE <optionName>

Description

Use this command to return the value of the encoding parameter or any other XML option in effect in the current UniVerse session.

ParametersThe following table describes each parameter of the syntax.

XMLGETOPTIONVALUE Parameters


optionName Specifies the name of the XML option for which you want to return the current value.For a complete list of valid UniVerse XML options, see xmlconfig Parameters.



Example

The following example shows the format for entering optionName to specify the XML parameter for which you want to return the current value.

XMLGETOPTIONVALUE encoding

This command returns the value of the encoding option, as shown below:

XMLGETOPTIONVALUE encoding

UTF-8

Existing TCL Command Affected by XMLSETOPTIONS Command or XMLSetOptions() APIThe syntax of the following TCL command remains unchanged. However, the command is affected by the XML options you set previously at the session level through the XMLSETOPTIONS command or through the XMLSetOptions() API.

DB.TOXML

Syntax

DB.TOXML “xml_doc_filename” “xmap_filename” “condition”

Description

Use the DB.TOXML command to create an XML document from the UniVerse database.

Note: The XML options set previously at the session level through the XMLSETOPTIONS command or through the XMLSetOptions() API are used when you run the DB.TOXML command in the current UniVerse session.

2-45


Parameters


DB.TOXML Parameters


xml_doc_filename The name of the XML document to create. If you do not enter a full path, the file is written to the &XML& directory.

xmap_filename The file name for the XMAP file.

condition A RetrieVe condition string, for example, WITH CLASSID = “Class002”

Example

The following example illustrates using DB.TOXML from TCL to create an XML document.

DB.TOXML SCHOOL_STUDENT.XML SCHOOL.MAP WITH CLASSID = “Class002”



Creating an XML Document Using RetrieVeTo create an XML document using RetrieVe, use the LIST command.

LIST [DICT | USING [DICT] dictname] filename ... [TOXML [ELEMENTS] [WITHDTD] [WITHSCHEMA | SCHEMAONLY] [XML-MAPPING mapping_file] [TO xmlfile]]


LIST Parameters


DICT Lists records in the file dictionary of filename. If you do not specify DICT, records in the data file are listed.

USING [ DICT ] dictname

If DICT is not specified, uses the data portion of dictname as the dictionary of filename. If DICT is specified, the dictionary of dictname is used as the dictionary of filename.

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 file name.

TOXML Outputs LIST results in XML format.

ELEMENTS Outputs results in element-centric format.

WITHDTD Output produces a DTD corresponding to the XML output.

WITHSCHEMA The output produces an XML schema corresponding to the XML output.

SCHEMAONLY The output produces a schema for the corresponding query.

XMLMAPPING mapping_file

Specifies a mapping file containing transformation rules for display. This file must exist in the &XML& file.

TO xmlfile This option redirects the query xml output from the screen to the &XML& file. This file has a .xml suffix. If you specify WITHSCHEMA in the query, UniVerse creates an xmlfile.xsd in the &XML& directory. If you specify WITHDTD, UniVerse creates an xmlfile.dtd.

For detailed information about the LIST command, see the Using RetrieVe.

2-47


Examples

Creating an Attribute-centric XML Document

Using the mapping file described in the Mapping File Example, the following example creates an attribute-centric 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

<?xml version="1.0" encoding="UTF-8"?><main><STUDENT _ID = "987654321" LNAME = "Miller" FNAME = "Susan"> <Term SEMESTER = "FA93"> <Courses_Taken COURSE_NBR = "EG110" COURSE_GRD = "C" COURSE_NAME = "Engineering Principles"/> <Courses_Taken COURSE_NBR = "MA220" COURSE_NAME = "Calculus- I"/> <Courses_Taken COURSE_NBR = "PY100" COURSE_GRD = "B" COURSE_NAME = "Introduction to Psychology"/> </Term> <Term SEMESTER = "SP94"> <Courses_Taken COURSE_NBR = "EG140" COURSE_GRD = "B" COURSE_NAME = "Fluid Mechanics"/> <Courses_Taken COURSE_NBR = "EG240" COURSE_GRD = "B" COURSE_NAME = "Circut Theory"/> <Courses_Taken COURSE_NBR = "MA221" COURSE_NAME = "Calculus - II"/> </Term></STUDENT><STUDENT _ID = "123456789" LNAME = "Martin" FNAME = "Sally"> <Term SEMESTER = "SP94"> <Courses_Taken COURSE_NBR = "PY100" COURSE_NAME = "Introduction to Psychology"/> <Courses_Taken COURSE_NBR = "PE100" COURSE_GRD = "C" COURSE_NAME = "Golf - I"/> </Term></STUDENT></main>>



Creating an XML Document with a DTD or XML Schema

If you only include the TOXML keyword in the RetrieVe statement, the resulting XML document does not include a DTD or XML Schema. To create an XML document that includes a DTD, use the WITHDTD keyword. To create an XML document that includes an XML Schema, use the WITHSCHEMA keyword.

2-49


The following example illustrates an XML document that includes a DTD:

>LIST STUDENT.F SEMESTER COURSE_NBR COURSE_GRD COURSE_NAME TOXML WITHDTD

<?xml version="1.0" encoding="UTF-8"?><!DOCTYPE ROOT[<!ELEMENT ROOT (STUDENT.F*)><!ELEMENT STUDENT.F ( CGA_MV* )><!ATTLIST STUDENT.F _ID CDATA #REQUIRED><!ELEMENT CGA_MV ( CGA_MS* )><!ATTLIST CGA_MV SEMESTER CDATA #IMPLIED><!ELEMENT CGA_MS EMPTY><!ATTLIST CGA_MS COURSE_NBR CDATA #IMPLIED COURSE_GRD CDATA #IMPLIED COURSE_NAME CDATA #IMPLIED>]>

<ROOT><STUDENT.F _ID = "424325656"> <CGA_MV SEMESTER = "SP94"> <CGA_MS COURSE_NBR = "PY100" COURSE_NAME = "Introduction to Psychology"/> <CGA_MS COURSE_NBR = "PE100" COURSE_GRD = "C"

COURSE_NAME = "Golf - I"/> </CGA_MV></STUDENT.F><STUDENT.F _ID = "521814564"> <CGA_MV SEMESTER = "FA93"> <CGA_MS COURSE_NBR = "CS130" COURSE_GRD = "A"

COURSE_NAME = "Intro to Operating Systems"/> <CGA_MS COURSE_NBR = "CS100" COURSE_GRD = "B"

COURSE_NAME = "Intro to Computer Science"/> <CGA_MS COURSE_NBR = "PY100" COURSE_GRD = "B"

COURSE_NAME = "Introduction to Psychology"/> </CGA_MV> <CGA_MV SEMESTER = "SP94"> <CGA_MS COURSE_NBR = "CS131" COURSE_GRD = "B"

COURSE_NAME = "Intro to Operating Systems"/> <CGA_MS COURSE_NBR = "CS101" COURSE_GRD = "B"

COURSE_NAME = "Intro to Computer Science"/> <CGA_MS COURSE_NBR = "PE220" COURSE_GRD = "A"

COURSE_NAME = "Racquetball"/> </CGA_MV></STUDENT.F>...>



Using WITHSCHEMA

Use the WITHSCHEMA keyword with the RetrieVe LIST command to create an XML schema.

The syntax for the LIST command is:

LIST [DICT | USING [DICT] dictname] filename ... [TOXML [ELEMENTS][WITHSCHEMA][WITHDTD] [SCHEMAONLY] TO filename [XMLMAPPING mapping_file] [TO xmlfile]]...

Note: If you specify both WITHDTD and WITHSCHEMA in the same RetrieVe statement, UniVerse does not produce an XML schema.

WITHSCHEMA creates an XML schema filename.xsd. By default, UniVerse writes this file to the &XML& directory when the TO xmlfile command is used. The infor-mation is displayed on the screen if the TO xmlfile command is not used. If you do not specify a targetNamespace in the mapping file, the filename.xml’s root element contains the following command to define the schema location:

noNamespaceSchemaLocation=filename.xsd

If you specify the targetNamespace in the mapping file, UniVerse generates the following:

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.

Mapping to an External Schema

A mapping file enables users to define how the dictionary attributes correspond to the DTD or XML Schema elements. This allows you to create many different forms of XML. Defining settings in the mapping file eliminates the need to specify them in each RetrieVe statement. The following example illustrates how to map to an external schema.

2-51


Assume you are trying to map to the following schema:

:<?xml version="1.0"?><xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:ibm="http://www.ibm.com" elementFormDefault="qualified"> <xsd:annotation> <xsd:documentation xml:lang="en"> This is a sample schema </xsd:documentation> </xsd:annotation> <xsd:element name="transcript"> <xsd:complexType> <xsd:sequence> <xsd:element name="student" type="studentType" minOccurs="0" maxOccurs="unbounded"/> </xsd:sequence> </xsd:complexType> </xsd:element> <xsd:complexType name="studentType"> <xsd:sequence> <xsd:element name="semesterReport" type="semesterReportType" minOccurs="0" maxOccurs="unbounded"/> </xsd:sequence> <xsd:attribute name="ref" type="xsd:string"/> <xsd:attribute name="firstName" type="xsd:string"/> <xsd:attribute name="lastName" type="xsd:string"/> </xsd:complexType> <xsd:complexType name="semesterReportType"> <xsd:sequence> <xsd:element name="results" type="resultsType" minOccurs="0" maxOccurs="unbounded"/> </xsd:sequence> <xsd:attribute name="term" type="xsd:string"/> </xsd:complexType> <xsd:complexType name="resultsType"> <xsd:sequence> <xsd:element name="courseGrade" type="xsd:string"/> <xsd:element name="courseHours" type="xsd:string"/> </xsd:sequence> <xsd:attribute name="courseNumber" type="xsd:string"/> <xsd:attribute name="courseName" type="xsd:string"/> <xsd:attribute name="courseInstructor" type="xsd:string"/> </xsd:complexType></xsd:schema>



The following map illustrates how to map your student file to this schema. Use the steps shown below to create the map:

1.Set the default settings for the map.

2.Rename singlevalued fields to match the schema names.

3.Rename the element tags used for the association.

4.Rename the multivalued fields.

5.Rename the multi-subvalued fields.

2-53


The following mapping file is the transcript.map file.

><u2

root="transcript"record="student"schema="type"xmlns:ibm="http://www.ibm.com"treated-as="element"collaosemv="1"

/>



<u2 file="STUDENT.F"field="@ID"map-to="ref"type="S"treated-as="attribute"/>

<u2 file="STUDENT.F"field="FNAME"map-to="firstName"type="S"treated-as="attribute"/>

<u2 file="STUDENT.F"field="LNAME"map-to="lastName"type="S"treated-as="attribute"/>

<u2 file="STUDENT.F"field="CGA"association-mv="semesterReport"association-ms="results"/>

<u2 file="STUDENT.F"field="SEMESTER"map-to="term"type="MV"treated-as="attribute"



/>



<u2 file="STUDENT.F"field="COURSE_NBR"map-to="courseNumber"type="MSV"treated-as="attribute"/>

<u2 file="STUDENT.F"field="COURSE_NAME"map-to="courseName"treated-as="attribute"type="MSV"/>

<u2 file="STUDENT.F"field="COURSE_GRD"map-to="courseGrade"type="MSV"/>

<u2 file="STUDENT.F"field="COURSE_HOURS"map-to="courseHours"type="MSV"/>

<u2 file="STUDENT.F"field="TEACHER"map-to="courseInstructor"type="MSV"treated-as="attribute"/>

2-55


You can now view the output from the schema using the following command:

>LIST STUDENT.F FNAME LNAME CGA SAMPLE 1 TOXML XMLMAPPING transcript.map

<?xml version="1.0" encoding="UTF-8"?><transcript xmlns:ibm="http://www.ibm.com"><student ref = "424325656" firstName = "Sally" lastName = "Martin"> <semesterReport term = "SP94" courseNumber = "PY100"

courseName = "Introduction to Psychology" courseInstructor = "Masters" courseNumber = "PE100"courseName= "Golf - I" courseInstructor = "Fisher">

<courseGrade>C</courseGrade> <courseHours>3</courseHours> <courseHours>3</courseHours> </semesterReport></student></transcript>>



Creating an XML Document with UniVerse SQLIn 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 or XML schema associated with the application to which you are sending the XML file. Determine which of your dictionary attri-butes correspond to the DTD or XML schema elements.

2. Create an XML mapping file, if necessary.3. List the appropriate fields using the UniVerse SQL SELECT command.

To create an XML document from UniVerse SQL, use the UniVerse SQL SELECT command.



SELECT clause Specifies the columns to select from the database.

FROM clause Specifies the tables containing the selected columns.

WHERE clause Specifies the criteria that rows must meet to be selected.

WHEN clause Specifies the criteria that values in a multivalued column must meet for an association row to be output.

GROUP BY clause Groups rows to summarize results.

HAVING clause Specifies the criteria that grouped rows must meet to be selected.

ORDER BY clause Sorts selected rows.

report_qualifiers Formats a report generated by the SELECT statement.

processing_qualifiers Modifies or reports on the processing of the SELECT statement.

TOXML Outputs SELECT results in XML format.

ELEMENTS Outputs results in element-centric format.

SELECT Parameters

2-57


You must specify clauses in the SELECT statement in the order shown in the syntax.

For a full discussion of the UniVerse SQL SELECT statement clauses, see Using UniVerse SQL.

Processing Rules for UniVerse SQL SELECT StatementsUniVerse 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.

WITHDTD Output produces a DTD corresponding to the query.

WITHSCHEMA Output produces an XML schema corresponding to the query.

SCHEMAONLY The output will produce a schema for the corresponding query.

XMLMAPPING ‘mapping_file’

Specifies a mapping file containing transformation rules for display. This file must exist in the &XML& file.

XMLDATA ‘extraction_mapping_file’

Specifies the file containing the extraction rules for the XML document. This file is used for receiving an XML file.

TO ‘xmlfile’ This option redirects the query xml output from the screen to the &XML& file. This file has a .xml suffix. If you specify WITHSCHEMA in the query, UniVerse creates an xmlfile.xsd in the &XML& directory. If you specify WITHDTD, UniVerse creates an xmlfile.dtd as well.


SELECT Parameters (Continued)



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 the Attribute-centric Mode section.

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 attri-butes 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 multi-values into single values.

UniVerse processes the ELEMENTS, WITHDTD, WITHSCHEMA, SCHEMAONLY and XMLMAPPING keywords in the same manner as it processes them for the RetrieVe LIST command.

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 SQLThe TOXML keyword is not allowed in the following cases:

In a sub-queryIn 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.

2-59


ExamplesThis 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:

>LIST DICT CUSTOMER.F

DICT CUSTOMER 02:11:01pm 11 Sep 2007 Page 1


@ID D 0 CUSTOMER 10L SNAME D 1 Customer Name 15T STAPES_RENTED D 7 Tapes 10L M

TAPE_INFO PH TAPES_RENTED Type & DATE_OUT DATE_DUE DAYS_BETWEEN TAPE_COST TAPE_NAME UP_NAMES29 records listed.

>LIST DICT TAPES.F

DICT TAPES.F 07:51:38am 07 Jan 2009 Page 1


@ID D 0 TAPES 10L SID D 0 TAPES 10L SNAME D 1 Tape Name 20T SRENTAL_PRICE D 2 MD2 Retail Charge 8R SCOPIES D 3 Copies Owned 4R SCOPIES_OUT D 4 Rented 4R SNUM_RENTALS D 5 MD0 Times Rented 6R SCOST D 6 MD2 Tape Cost 6R2$, SACTORS D 7 Actors 12L SDIRECTOR D 8 Director 12L SCATEGORIES D 9 Type of Video 12L S CATSNEW_PRICE I IF @ID[1,1] = MD2 Upgrade 5R S 'B' THEN 0 ELSE NUM_RENTALS;I F @1 > 10...>

2-61


Using WITHSCHEMA

The syntax for the UniVerse SQL SELECT command is:

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][SCHEMAONLY][XMLMAPPING ‘mapping_file’]][XMLDATA extraction_mapping_file][TO ‘xmlfile’];

When the TOXML command is used in SQL, both the mapping file and the TO xml file need to be quoted



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.F file. In the XML document, TAPES_RENTED appears in the CUSTOMER_TAPE_INFO_MV element.

>SELECT CUSTOMER.F.NAME, TAPES.F.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" encoding="UTF-8"?><ROOT><CUSTOMER.F NAME = "Barrie, Dick"> <TAPES.F> <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><CUSTOMER.F NAME = "Best, George"> <TAPES.F> <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><CUSTOMER.F NAME = "Bowie, David"> <TAPES.F> <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>...</ROOT>

2-63


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.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" encoding="UTF-8"?><!DOCTYPE ROOT[<!ELEMENT ROOT (CUSTOMER.F*)><!ELEMENT CUSTOMER.F ( TAPES.F* , CUSTOMER.F_TAPE_INFO_MV* )><!ATTLIST CUSTOMER.F NAME CDATA #REQUIRED><!ELEMENT TAPES.F ( TAPES.F_CATS_MV* )><!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 NAME = "Barrie, Dick"> <TAPES.F> <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><CUSTOMER.F NAME = "Best, George"> <TAPES.F> <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><CUSTOMER.F NAME = "Bowie, David"> <TAPES.F> <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><CUSTOMER.F NAME = "Chase, Carl"> <TAPES.F>



<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><CUSTOMER.F NAME = "Chase, Carl"> <TAPES.F> <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>...

</ROOT>>

2-65


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 section.

The following mapping file defines rules for the CUSTOMER and TAPES file.

>ED &XML& CUST_TAPES.mapTop of "CUST_TAPES.map" in "&XML&", 22 lines, 259 characters.*--: p001: <U2xml002: file="TAPES.F"003: field = "CAT_NAME"004: map-to="Cat_name"005: type="mv"006: />007: <u2008: file="CUSTOMER.F"009: field="TAPES_RENTED"010: map-to="Tapes_rented"011: TYPE="mv"012: />013: <u2014: file="CUSTOMER.F"015: field="DATE_OUT"016: TYPE="mv"017: />018: <u2019: file="CUSTOMER.F"020: field="DATE_DUE"021: TYPE="mv"022: />

To use this mapping file in the SELECT statement, specify the XMLMAPPING keyword, as shown in the following example:



Note: You must surround the name of the mapping file in single quotation marks.

>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_TAPES.MAP';

<?xml version="1.0" encoding="UTF-8"?><ROOT><CUSTOMER.F 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 DATE_OUT = "03/29/94" DATE_DUE = "03/31/94"/></CUSTOMER.F><CUSTOMER.F 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 DATE_OUT = "03/29/94" DATE_DUE = "03/31/94"/></CUSTOMER.F><CUSTOMER.F 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 DATE_OUT = "04/15/94" DATE_DUE = "04/17/94"/></CUSTOMER.F><CUSTOMER.F 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 DATE_OUT = "04/20/94" DATE_DUE = "04/22/94"/> <CUSTOMER.F_TAPE_INFO_MV DATE_OUT = "04/20/94" DATE_DUE = "04/22/94"/> <CUSTOMER.F_TAPE_INFO_MV DATE_OUT = "04/21/94" DATE_DUE = "04/23/94"/></CUSTOMER.F><CUSTOMER.F 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 DATE_OUT = "04/20/94" DATE_DUE = "04/22/94"/> <CUSTOMER.F_TAPE_INFO_MV DATE_OUT = "04/20/94" DATE_DUE =

2-67


"04/22/94"/> <CUSTOMER.F_TAPE_INFO_MV DATE_OUT = "04/21/94" DATE_DUE = "04/23/94"/></CUSTOMER.F><CUSTOMER.F 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 DATE_OUT = "04/20/94" DATE_DUE = "04/22/94"/> <CUSTOMER.F_TAPE_INFO_MV DATE_OUT = "04/20/94" DATE_DUE = "04/22/94"/> <CUSTOMER.F_TAPE_INFO_MV DATE_OUT = "04/21/94" DATE_DUE = "04/23/94"/></CUSTOMER.F><CUSTOMER.F 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 DATE_OUT = "04/19/94" DATE_DUE = "04/21/94"/></CUSTOMER.F>...

</ROOT>



Creating an XML Document Through UniVerse BasicUse the UniVerse Basic commands described in this section to create XML documents through UniVerse Basic.

2-69


.

Using the XMLExecute() Function

Syntax

XMLExecute(cmd, options, xmlvar, xsdvar)

Description

The XMLExecute function enables you to create an XML document using RetrieVe from UniVerse Basic and returns the xml and xsd schema in BASIC variables. By default, the XMLExecute command generates an XML Schema. The options can also be separated by a [space] command, using “=” to assign option values.



cmd Holds the text string of the RetrieVe LIST statement or the UniVerseUniVerseSQL SELECT statement. [IN]

options Each XML-related option is separated by a field mark (@FM), or space (“ “)If the option requires a value, the values are contained in the same field, separated by value marks (@VM), or equal signs (“=”).

WITHDTD Creates a DTD and binds it with the XML document. By default, UniVerse creates an XML schema. However, if you include WITHDTD in your RetrieVe or UniVerse SQLstatement, UniVerse does not create an XML schema, but only produces the DTD.

ELEMENTS The XML output is in element-centric format.

XMLMAPPING = ‘mapping_file_name’

Specifies the mapping file containing transfor-mation rules for display. This file must exist inthe &XML& directory.

SCHEMA = ’type’ The default schema format is ref type schema. You can use the SCHEMA attribute to define adifferent schema format.

XMLExecute Parameters



.

f

,

HIDEMV, HIDEMS Normally, when UniVerse processes multi-valued or multi-subvalued fields, UniVerse addsanother 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. When theseoptions are on, the generated XML document and the associated DTD or XML schema have fewer levels of nesting.

HIDEROOT = 1 Allows you to specify to only create a segmentof an XML document, for example, using the SAMPLE keyword and other conditional clauses. If you specify HIDEROOT, UniVerse only creates the record portion of the XML document, it does not create a DTD or XML schema.

RECORD = ’newrecords’ The default record name is FILENAME_recordThe record attribute in the ROOT element changes the record name.

ROOT = ’newroot’ The default root element name in an XML document is ROOT. You can change the name othe root element as shown in the following example:root=”root_element_name”

TARGETNAMESPACE = ’namespaceURL’

UniVerse displays the targetnamespace attributein the XMLSchema as targetNamespace, and uses the URL you specifyto define schemaLocation. If you define the targetnamespace and other explicit namespace definitions, UniVerse checks if the explicitly defined namespace has the same URL and the targetnamespace. If it does, UniVerse uses the namespace name to qualify the schema elementand the XML document element name.


XMLExecute Parameters (Continued)

2-71


COLLAPSEMV, COLLAPSEMS

Normally, when UniVerse processes multi-valued or multi-subvalued fields, UniVerse addsanother level of elements to produce multiple levels of nesting. You have the option of disabling this additional level by adding the COLLAPSEMV and COLLAPSEMS attri-butes. When these options are on, the generatedXML document and the associated DTD or XML Schema have fewer levels of nesting.

MATCHELEMENT The Matchelement attribute specifies whether to display empty elements for missing values or subvalues belonging to the same association, or to ignore the missing values. When this option is on, the generated XML document and the associated DTD or XML Schema have fewer levels of nesting.

EMPTYATTRIBUTE This attribute determines how to display the empty attributes for multivalued fieldsbelonging to an association in the generatedXML document and in the associated DTDor XML Schema. When this option is on, thegenerated XML document and the associated DTD or XML Schema have fewer levels of nesting.

XmlVar The name of the variable to which to store the generated XML document [OUT]

XsdVar The name of the variable in which to store the XML Schema if one is generated along with the XML document.


XMLExecute Parameters (Continued)



XMLSetOptions

Syntax

XMLSetOptions("options")

Description

Use this function in UniVerse Basic programs to set the encoding parameter and other XML options in the current UniVerse session. The settings specified in this API override the settings in the system-level and account-level xmlconfig files and in TCL commands during the current session.

Parameters


XMLSetOptions Parameters


options A string in the format of space-delimited key/value pairs. [IN]The XML options are the same as those in the xmlconfig file and accept the same values. Keys and values are case-insensitive.For a complete list of valid UniVerse XML options and settings, see xmlconfig Parameters.The XMLSetOptions function also accepts three special strings as the options parameter. defaults – Sets all XML options to their default settings in the current session.

reload – Reloads the current system-level and account-level xmlconfig files, since they may have changed after you started your UniVerse session.

reset – Resets XML options to the original settings that were loaded when you started the UniVerse session.

A special string must be entered as the only option.

2-73


Examples

The following example shows the format for entering the XML options in this API.

XMLSetOptions("encoding=iso-8859-1 newline=CR-LF")


XMLSetOptions("defaults")

Return Codes

The return code indicates success or failure. The following table describes each return code.

XMLSetOptions (defaults) Return Codes

Return Code Description

XML.SUCCESS Function completed successfully.

XML.ERROR When the return status is XML.ERROR, XMLGetError() returns one of the following error codes:

38 Invalid XML config key: ‘key_name’

39 Invalid XML config value: ‘value_string’

40 Invalid XML config format: ‘name_value_string’41 Invalid XML config key 'key_name' at line line_number in xmlconfig file(xmlconfig_filename)42 Invalid XML config value 'value_string' at line line_number in xmlconfig file(xmlconfig_filename)43 Invalid XML config format 'name_value_string' at line line_number in xmlconfig file(xmlconfig_filename)

Note: When the return code is XML.ERROR, none of the XML parameters are changed.


XMLSetOptions("reload")



XMLGetOptions

Syntax

XMLGetOptions(outOptions[, delimiterString])

Description

Use this function in UniVerse Basic programs to return the values for encoding and other XML options in effect in the current UniVerse session.

Parameters


XMLGetOptions Parameters


outOptions A variable used to retrieve the XML options key/value pairs in effect in the current UniVerse session. [OUT]

delimiterString Optional. Specifies the string to be used to separate the key/value pairs returned by the command. By default, delimiterString is a space. [IN]

Examples

The following example shows the format for entering delimiterString as the string used to separate the key/value pairs returned by the function. Key/value pairs can be separated by a space or by any string, such as <>, as shown in this example:

(xmlOptions, "<>")

encoding=default<>in-encoding=UTF-8<>version=1.1

If you enter the XMLGetOptions function with no delimiterString, the key/value pairs are separated by a space, as shown in the next example:

XMLGetOptions(xmlOptions)

encoding=default in-encoding=UTF-8 version=1.1

2-75


For a complete list of the standard UniVerse XML options and values returned by this function, see xmlconfig Parameters.

Return Codes

The return code indicates the status on completion of this function. The following table describes each return code.

XMLGetOptions Return Codes



XMLGetOptionValue

Syntax

XMLGetOptionValue(optionName, outOptionValue)

Description

Use this function in UniVerse Basic programs to return the value of encoding or any other XML option in effect in the current UniVerse session.

Parameters


XMLGetOptionValue Parameters


optionName The name of the XML option for which you want to retrieve the current value. [IN]The XML options are the same as those in the xmlconfig file. For a complete list of valid UniVerse XML options, see xmlconfig Parameters.

outOptionValue A variable used to retrieve the value of the specified XML option in the current UniVerse session. [OUT]



Example

The following example shows the format for entering the optionName and outOptionValue variables:

XMLGetOptionValue("encoding", xmlOptionValue)

This function returns the value of the encoding option in the second argument, xmlOptionValue.

Return Codes


XMLGETOPTIONVALUE Return Codes



XML.ERROR When the return status is XML.ERROR, XMLGetError() returns the following error code:


2-77


The following XML APIs accept additional parameters for encoding and other XML options, or other new parameters:

XDOMCreateRootXDOMTransformXDOMValidateXDOMValidateDomXDOMWriteXMAPToXMLDoc



XDOMCreateRoot

Syntax

XDOMCreateRoot(domHandle[, xmlOptions])

Description

XDOMCreateRoot 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. The default declaration for the XML document created by this function is as follows:

<?xml version=”1.0” encoding=”UTF-8” standalone=”no” ?>

Parameters


XDOMCreateRoot Parameters


domHandle Handle to the opened DOM structure. [OUT]

xmlOptions A string specifying the key/value pairs for the encoding, stand-alone, and version options to be declared in the XML document created by this function. [IN]The string can be entered in either of the following formats:"version=1.0 encoding=ISO-8859-1 standalone=yes"

or’version="1.0" encoding="iso-8859-1" standalone="no"’

The encoding, standalone, and version options are the same as those in the xmlconfig file and accept the same values. For details, see the xmlconfig Parameters section. Keys and values are case-insensitive.Valid encoding settings can be found at http://www.iana.org/assignments/character-sets

2-79


Return Codes


XDOMCreateRoot Return Codes



XML.ERROR An error occurred.If an error is encountered in xmlOptions, XMLGetError() returns one of the following error codes:



40 Invalid XML config format: ‘name_value_string’



XDOMTransform

Syntax

XDOMTransform(domHandle, styleSheet, ssLocation, outHandle[, outFormat])

Description

XDOMTransform transforms the input DOM structure using the style sheet specified by styleSheet to output the DOM structure, file, or string.

Parameters


XDOMTransform Parameters


domHandle Handle to the DOM structure. [IN]

styleSheet Handle to the context. [IN]

ssLocation A flag to specify whether styleSheet contains style sheet itself, or is just the style sheet file name. Value values are:XML.FROM.FILE XML.FROM.STRING[IN]

outHandle Handle to the resulting DOM structure, file, or string. [OUT]

outFormat Specifies one of the following values as the output format for the DOM structure:

XML.TO.DOM – Transforms the input DOM structure using the style sheet specified by styleSheet, and outputs the resulting document into a DOM structure.

XML.TO.FILE – Transforms the input DOM structure using the style sheet specified by styleSheet, and outputs the resulting document into a file.

XML.TO.STRING – Transforms the input DOM structure using the style sheet specified by styleSheet, and outputs the resulting document into a string.

2-81


Return Codes


XDOMTransform Return Codes


XML.SUCCESS The function completed successfully.

XML.ERROR An error occurred.

XML.INVALID.HANDLE An invalid DOM handle was returned to the function.



XDOMValidate

Syntax

XDOMValidate(xmlDocument, docLocation,, noNsSchema, noNsSchemaLocation[, NsSchemas])

Description

XDOMValidate validates the DOM document using an external no-namespace schema specified by noNsSchema and, optionally, external namespace schemas specified by NsSchemas.

Parameters


XDOMValidate Parameters


xmlDocument The name of the XML document. [IN]

docLocation A flag to specify whether xmlDocument is the document itself, or the document file name. Valid values are:XML.FROM.FILE XML.FROM.STRING XML.FROM.DOM[IN]

noNsSchema The external no-namespace schema file. [IN]

noNsSchemaLocation A flag to specify whether noNsSchema is the schema itself, or the schema file name. Valid values are:XML.FROM.FILE (default) XML.FROM.STRING[IN]

NsSchemas The external namespace schema files. [IN]

2-83


Return Codes


XDOMValidate Return Codes




XML.INVALID.HANDLE An invalid DOM handle was passed to the function.



XDOMValidateDom

Syntax

XDOMValidateDom(domHandle, noNsSchema, noNsSchemaLocation[, NsSchemas])

Description

XDOMValidateDom validates the DOM document using an external no-namespace schema specified by noNsSchema and, optionally, external namespace schemas specified by NsSchemas.

Parameters


XDOMValidateDom Parameters


domHandle Handle to the DOM structure. [IN]

noNsSchema The external no-namespace schema file. [IN]

noNsSchemaLocation A flag to specify whether noNsSchema is the schema itself, or the schema file name. Valid values are:XML.FROM.FILE (default) XML.FROM.STRING[IN]

NsSchemas The external namespace schema files. [IN]

2-85


Return Codes


XDOMValidateDom Return Codes




XML.INVALID.HANDLE An invalid DOM handle was passed to the function.



XDOMWrite

Syntax

XDOMWrite(domHandle, xmlDocument, docLocation[, xmlOptions])

Description

XDOMWrite writes the DOM structure to xmlDocument. xmlDocument can be a string or a file, depending on the value of the docLocation flag.

Parameters



domHandle Handle to the opened DOM structure. [IN]

xmlDocument The XML document [OUT]

docLocation A flag to specify whether xmlDocument is an output string that should hold the XML document, or is a file to which the XML document should be written. Valid values are:XML.TO.FILE XML.TO.STRING[IN]

XDOMWrite Parameters

2-87


Return Codes


XDOMWrite Return Codes



XML.ERROR An error occurred.If an error is encountered in xmlOptions, XMLGetError() returns one of the following error codes:

38 Invalid XML config key: ’key_name’

39 Invalid XML config value: ’value_string’

40 Invalid XML config format: ’name_value_string’

XML.INVALID.HANDLE Invalid DOM handle passed to the function.

xmlOptions A string specifying the key/value pairs of the XML options to be used in the XML document written by this function. [IN]The string can be entered in either of the following formats:"encoding=ISO-8859-1 standalone=yes newline=CR-LF"

or‘encoding="iso-8859-1" standalone="no"’

The XML options are the same as those in the xmlconfig file and accept the same values. Keys and values are case-insensitive. For a complete list of valid UniVerse XML options and settings, see xmlconfig Parameters.Valid encoding settings can be found at http://www.iana.org/assign-ments/character-sets


XDOMWrite Parameters (Continued)



XMAPToXMLDoc

Syntax

XMAPToXMLDoc(XMAPhandle, xmlfile, doc_flag[, xmlOptions])

Description

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.

Parameters



XMAPhandle The handle to the U2XMAP dataset.

xmlfile The name of the XML file, or the name of a UniVerse Basic variable to hold the XML document.

doc_flag 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

2-89


Return Codes


XMAPToXMLDoc Return Codes


XML_SUCCESS The XML document was opened successfully.

XML_ERROR An error occurred opening the XML document.If an error is encountered in xmlOptions, XMLGetError() returns one of the following error codes:



40 Invalid XML config format: ‘name_value_string’

XML_INVALID_HANDLE The XMAP dataset was invalid.

xmlOptions A string specifying the key/value pairs of the XML options to be used in the XML document generated by this function. [IN]The string can be entered in either of the following formats:"encoding=ISO-8859-1 standalone=yes newline=CR-LF"

or‘encoding="iso-8859-1" standalone="no"’

The XML options are the same as those in the xmlconfig file and accept the same values. Keys and values are case-insensitive.For a complete list of valid UniVerse XML options and settings, see xmlconfig Parameters.Valid encoding settings can be found at http://www.iana.org/assign-ments/character-sets


XMAPToXMLDoc Parameters (Continued)



Existing APIs Affected by XML OptionsOne or more XML options set in the xmlconfig files, the XMLSETOPTIONS command, or the XMLSetOptions() API are used by the following APIs:

DBTOXMLXDOMAddChildXDOMAppendXDOMCreateNodeXDOMEvaluateXDOMGetAttributeXDOMGetNodeNameXDOMGetNodeValueXDOMInsertXDOMLocateXDOMRemoveXDOMReplaceXDOMSetNodeValueXMAPAppendRecXMAPOpenXMAPReadNext

2-91


DBTOXML

Syntax

DBTOXML(xml_document, doc_location, u2xmap_file, u2xmap_location, condition, status)

Description

Creates an XML document from the UniVerse database.

Parameters


DBTOXML Parameters


xml_document The name of the XML document to create.

doc_flag 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 The name of the U2XMAP file to use to produce the XML document.

u2xmap_location The location of the U2XMAP file.XML.FROM.FILE – u2xmap_file is a file name.

XML.FROM.STRING – u2xmap_file is the name of a variable containing the mapping rules.

condition A query condition for selecting data from the UniVerse file, for example, WHERE SCHOOL = "CO002"

Status XML.SUCCESS or XML.FAILURE.

Note: The XML options set previously at the session level through the XMLSETOPTIONS command or through the XMLSetOptions() API are used when you run the DBTOXML API in the current UniVerse session.



XDOMAddChild

Syntax

XDOMAddChild(xmlHandle, xpathString, nsMap, nodeHandle, dupFlag)

Description

Finds the xpathString in the context xmlHandle in the DOM structure, and inserts a node 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



xmlHandle The handle to the context. [IN]

xpathString Relative or absolute xpath string. [IN]The xpathString parameter uses the in-encoding parameter set in the system-level or account-level xmlconfig file, the XMLSETOPTIONS command, or the XMLSetOptions() API.

nsMap The map of namespaces that resolves 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]The nsMap parameter uses the in-encoding parameter set in the system-level or account-level xmlconfig file, the XMLSETOPTIONS command, or the XMLSetOptions() API.

nodeHandle Handle to a DOM subtree. If nodeHandle points to a DOM document, all of its children are inserted, in the same order. [IN]

XDOMAddChild Parameters

2-93


Return Codes


XDOMAddChild Return Codes





dupFlag 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 (Continued)



XDOMAppend

Syntax

XDOMAppend(xmlHandle, xpathString, nsMap, nodeHandle, dupFlag)

Description

Finds the xpathString in the context xmlHandle in the DOM structure, and inserts nodeHandle into the DOM structure as the next sibling of the found node. If the inserted node type is XDOM.ATTR.NODE, this node is inserted as an attribute.

Parameters




xpathString Relative or absolute XPath string. [IN]The xpathString parameter uses the in-encoding parameter set in the system-level or account-level xmlconfig file, the XMLSETOPTIONS command, or the XMLSetOptions() API.

nsMap The map of namespaces that 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]The nsMap parameter uses the in-encoding parameter set in the system-level or account-level xmlconfig file, the XMLSETOPTIONS command, or the XMLSetOptions() API.

nodeHandle Handle to a DOM subtree. If nodeHandle points to a DOM document, all of its children are inserted, in the same order. [IN]

XDOMAppend Parameters

2-95


Return Codes


XDOMAppend Return Codes





dupFlag 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]


XDOMAppend Parameters (Continued)



XDOMCreateNode

Syntax

XDOMCreateNode(xmlHandle, nodeName, nodeValue, nodeType, nodeHandle)

Description

XDOMCreateNode creates a new node in the DOM structure.

Parameters


Parameters Description

xmlHandle A handle to the DOM structure. This handle acts as the context when resolving the namespace_uri from the prefix or resolving the prefix from the namespace_uri.[IN]

nodeName The name of the node to be created. [IN]The name can be in any of the following formats:

Local_name

prefix: local_name:namespace_uri

prefix:local_name

:local_name:namespace_uri

The nodeName parameter uses the in-encoding parameter set in the system-level or account-level xmlconfig file, the XMLSE-TOPTIONS command, or the XMLSetOptions() API.

nodeValue The string to hold the node value. [IN]The nodeValue parameter uses the in-encoding parameter set in the system-level or account-level xmlconfig file, the XMLSE-TOPTIONS command, or the XMLSetOptions() API.

XDOMCreateNode Parameters

2-97


Return Codes


XDOMCreateNode Return Codes




nodeType The type of the node to be created. Valid values are: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[IN]

nodeHandle A handle to the node to be created in the DOM structure.[IN]

Parameters Description

XDOMCreateNode Parameters (Continued)



XDOMEvaluate

Syntax

XDOMEvaluate(xmlHandle, xpathString, nsMap, aValue)

Description

XDOMEvaluate returns the value of xpathString in the context xmlHandle in the DOM structure.

Parameters


XDOMEvaluate Parameters


xmlHandle Handle to the context. [IN]

xpathString The relative or absolute XPath string. [IN]The xpathString parameter uses the in-encoding parameter set in the system-level or account-level xmlconfig file, the XMLSE-TOPTIONS command, or the XMLSetOptions() API.

nsMap The map of namespaces that 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]The nsMap parameter uses the in-encoding parameter set in the system-level or account-level xmlconfig file, the XMLSETOP-TIONS command, or the XMLSetOptions() API.

aValue The value of xpathString. [OUT]The aValue parameter uses the out-encoding parameter set in the system-level or account-level xmlconfig file, the XMLSETOP-TIONS command, or the XMLSetOptions() API.

2-99


Return Codes


XDOMEvaluate Return Codes







XDOMGetAttribute

Syntax

XDOMGetAttribute(nodeHandle, attrName, nodeHandle)

Description

XDOMGetAttribute gets the node's attribute node, whose attribute name is attrName.

Parameters


XDOMGetAttribute Parameters


nodeHandle Handle to the DOM node. [IN]

attrName Attribute name. [IN]The attrName parameter uses the in-encoding parameter set in the system-level or account-level xmlconfig file, the XMLSE-TOPTIONS command, or the XMLSetOptions() API.

nodeHandle Handle to the found attribute node. [OUT]

Return Codes


XDOMGetAttribute Return Codes





2-101


XDOMGetNodeName

Syntax

XDOMGetNodeName(nodeHandle, nodeName)

Description

XDOMGetNodeName returns the node name.

Parameters


XDOMGetNodeName Parameters


nodeHandle Handle to the DOM node. [IN]

nodeName String to store the node name. [OUT]The nodeName parameter uses the out-encoding parameter set in the system-level or account-level xmlconfig file, the XMLSETOPTIONS command, or the XMLSetOptions() API.

Return Codes


XDOMGetNodeName Return Codes







XDOMGetNodeValue

Syntax

XDOMGetNodeValue(nodeHandle, nodeValue)

Description

XDOMGetNodeValue gets the node value.

Parameters


XDOMGetNodeValue Parameters


nodeHandle The handle to the DOM node. [IN]

nodeValue The string to hold the node value. [OUT]The nodeValue parameter uses the out-encoding parameter set in the system-level or account-level xmlconfig file, the XMLSE-TOPTIONS command, or the XMLSetOptions() API.

Return Codes


XDOMGetNodeValue Return Codes





2-103


XDOMInsert

Syntax

XDOMInsert (xmlHandle, xpathString, nsMap, nodeHandle, dupFlag)

Description

XDOMInsert finds the xpathString in the context xmlHandle in the DOM structure, and inserts nodeHandle into the DOM structure as the previous sibling of the found node. If the inserted node type is XDOM.ATTR.NODE, this node is inserted as an attribute.

Parameters





nsMap The map of namespaces that 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]The nsMap parameter uses the in-encoding parameter set in the system-level or account-level xmlconfig file, the XMLSETOPTIONS command, or the XMLSetOptions() API.

nodeHandle The handle to a DOM subtree. If nodeHandle points to a DOM document, all of its children are inserted, in the same order. [IN]

XDOMInsert Parameters



Return Codes


XDOMInsert Return Codes





dupFlag XDOM.DUP: Clones nodeHandle, and inserts the duplicate node.XDOM.NODUP: Inserts the original node. The subtree is also removed from its original location.


XDOMInsert Parameters (Continued)

2-105


XDOMLocate

Syntax

XDOMLocate(xmlHandle, xpathString, nsMap, nodeHandle)

Description

XDOMLocate 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 will return an error.

Parameters


XDOMLocate Parameters


xmlHandle A handle to the DOM structure. [IN]

xpathString A string to specify the starting point. [IN]The xpathString parameter uses the in-encoding parameter set in the system-level or account-level xmlconfig file, the XMLSE-TOPTIONS command, or the XMLSetOptions() API.

nsMAP The map of namespaces that resolves the prefixes in the xpath-String. The format is:“xmlns=default_url xmlns:prefix1=prefix1_url xmlns:prefix2=prefix2_urlFor example:“xmlns=”http://myproject.mycompany.com xmlns:a_prefix=a.mycompany.com[IN]The nsMap parameter uses the in-encoding parameter set in the system-level or account-level xmlconfig file, the XMLSETOP-TIONS command, or the XMLSetOptions() API.

noteHandle Handle to the found node. [OUT]



Return Codes


XDOMLocate Return Codes




XML.INVALID.HANDLE An invalid handle was returned to the function.

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.

2-107


XDOMRemove

Syntax

XDOMRemove(xmlHandle, xpathString, nsMap, attrName, nodeHandle)

Description

XDOMRemove finds the xpathString in the context xmlHandle in the DOM structure, and then removes the found node or its attribute with name attrName.

Parameters



xmlHandle Handle to the context. [IN]

xpathString Relative or absolute xpath string. [IN]The xpathString parameter uses the in-encoding parameter set in the system-level or account-level xmlconfig file, the XMLSETOPTIONS command, or the XMLSetOptions() API.

XDOMRemove Parameters



Return Codes


XDOMRemove Return Codes





nsMap The map of namespaces that resolves 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]The nsMap parameter uses the in-encoding parameter set in the system-level or account-level xmlconfig file, the XMLSETOPTIONS command, or the XMLSetOptions() API.

attrName The attribute name. [IN]The attrName parameter uses the in-encoding parameter set in the system-level or account-level xmlconfig file, the XMLSETOPTIONS command, or the XMLSetOptions() API.

nodeHandle The removed node, if nodeHandle is not NULL. [OUT]


XDOMRemove Parameters (Continued)

2-109


XDOMReplace

Syntax

XDOMReplace(xmlHandle, xpathString, nsMap, nodeHandle, dupFlag)

Description

XDOMReplace finds the xpathString in the context xmlHandle in the DOM structure, and replaces the found node with nodeHandle.

Parameters





nsMap The map of namespaces that 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]The nsMap parameter uses the in-encoding parameter set in the system-level or account-level xmlconfig file, the XMLSETOPTIONS command, or the XMLSetOptions() API.

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]

XDOMReplace Parameters



Return Codes


XDOMReplace Return Codes





dupFlag 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 (Continued)

2-111


XDOMSetNodeValue

Syntax

XDOMSetNodeValue(nodeHandle, nodeValue)

Description

XDOMSetNodeValue sets the node value.

Parameters


XDOMSetNodeValue Parameters


nodeHandle The handle to the DOM node. [IN]

nodeValue The string to hold the node value. [IN]The nodeValue parameter uses the in-encoding parameter set in the system-level or account-level xmlconfig file, the XMLSE-TOPTIONS command, or the XMLSetOptions() API.

Return Codes


XDOMSetNodeValue Return Codes







XMAPAppendRec

Syntax

XMAPAppendRec(XMAPhandle, file_name, record)

Description

The XMAPAppendRec function formats the specified record from the UniVerse file as a U2XMAP dataset record and appends it to the U2XMAP dataset.

Parameters


XMAPAppendRec Parameters


XMAPhandle The handle to the U2XMAP dataset.The XMAPhandle parameter uses the in-encoding parameter set in the system-level or account-level xmlconfig file, the XMLSE-TOPTIONS command, or the XMLSetOptions() API for the input record value.

file_name The name of the UniVerse file that is being mapped in the U2 XMAP dataset.

record The data record formatted according to the dictionary record of the UniVerse file.

2-113


Return Codes


XMAPAppendRec Return Codes



XML_ERROR An error occurred opening the XML document.

XML_INVALID_HANDLE The XMAP dataset was invalid.



XMAPOpen

Syntax

XMAPOpen(xml_document, doc_flag, u2xmapping_rules, u2xmap_flag, XMAPhandle)

Description

The XMAPOpen function opens an XML document as a U2XMAP data set.

Parameters


XMAPOpen Parameters


xml_document The name of the XML document.

doc_flag 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 a variable containing the XML document.

u2xmapping_rules The name of the U2XMAP file, or the UniVerse Basic variable containing the XML to Database mapping rules.

u2xmap_flag 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.This API registers the current in-encoding and out-encoding parameters in the XMAPhandle. These parameters are used throughout the life of the XMAPhandle.

2-115


Return Codes


XMAPOpen Return Codes



XML_ERROR An error occurred opening the XML document.



XMAPReadNext

Syntax

XMAPReadNext(XMAPhandle, file_name, record)

Description

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.

Parameters


XMAPReadNext Parameters


XMAPhandle The U2XMAP dataset handle.The XMAPhandle parameter uses the out-encoding parameter set in the system-level or account-level xmlconfig file, the XMLSETOPTIONS command, or the XMLSetOptions() API for the record value.

file_name The name of the UniVerse file that is being mapped in the U2XMAP dataset.

record The data record formatted according to the dictionary record of the file.

Return Codes



XML_SUCCESS The XMAPReadNext was executed successfully.

XMAPReadNext Return Codes

2-117


XML_ERROR An error occurred in executing XMAPReadNext.

XML_INVALID_HANDLE U2 XMAP dataset handle was invalid.

XML_EOF The end of the U2XMAP dataset has been reached.


XMAPReadNext Return Codes (Continued)



UniVerse Basic ExampleThe following example illustrates a UniVerse Basic program that generates an XML document:

CT BP XML2BP:

$INCLUDE UNIVERSE.INCLUDE XML.H** Here we test different Options for HIDEMS, and also ELEMENT mode

CMD = "LIST STUDENT LNAME COURSE_NBR COURSE_GRD COURSE_NAME SEMESTER"OPTIONS ="XMLMAPPING=student.map"OPTIONS = OPTIONS:' HIDEMS=1 ELEMENTS'PRINT OPTIONSSTATUS = XMLExecute(CMD,OPTIONS,XMLVAR,XSDVAR)IF STATUS = 0 THEN STATUS = XDOMValidate(XMLVAR,XML.FROM.STRING,XSDVAR,XML.FROM.STRING) IF STATUS <> XML.SUCCESS THEN STATUS = XMLGetError(code,msg) PRINT code,msg PRINT "Validate FAILED." PRINT XSDVAR PRINT XMLVAR END ELSE PRINT "Options ": OPTIONS PRINT "XML output"

PRINT XMLVAR PRINT "" ENDENDELSE STATUS = XMLGetError(code,msg) PRINT code,msg PRINT "XMLExecute() failed"END

2-119


The next example illustrates the output from the program described in the previous example:

>RUN BP XML2XMLMAPPING=student.map HIDEMS=1 ELEMENTSOptions XMLMAPPING=student.map HIDEMS=1 ELEMENTSXML output<?xml version="1.0" encoding="UTF-8"?><STUDENT xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:ibm="http://www.ibm.com"><STUDENT> <_ID>221345665</_ID> <LNAME>Miller</LNAME> <Term> <SEMESTER>FA93</SEMESTER> <COURSE_GRD>C</COURSE_GRD> <COURSE_NAME>Engineering Principles</COURSE_NAME> <COURSE_NBR>EG110</COURSE_NBR> <COURSE_GRD>B</COURSE_GRD> <COURSE_NAME>Calculus- I</COURSE_NAME> <COURSE_NBR>MA220</COURSE_NBR> <COURSE_GRD>B</COURSE_GRD> <COURSE_NAME>Introduction to Psychology</COURSE_NAME> <COURSE_NBR>PY100</COURSE_NBR> </Term> <Term> <SEMESTER>SP94</SEMESTER> <COURSE_GRD>B</COURSE_GRD> <COURSE_NAME>Fluid Mechanics</COURSE_NAME> <COURSE_NBR>EG140</COURSE_NBR> <COURSE_GRD>B</COURSE_GRD> <COURSE_NAME>Circut Theory</COURSE_NAME> <COURSE_NBR>EG240</COURSE_NBR> <COURSE_GRD>B</COURSE_GRD> <COURSE_NAME>Calculus - II</COURSE_NAME> <COURSE_NBR>MA221</COURSE_NBR> </Term></STUDENT>...

</MAIN>



The following example shows the output if the HIDEMS attribute is set equal to “0”:

>LIST STUDENT SEMESTER COURSE_NBR TOXML XMLMAPPING student.map ELEMENTS

<?xml version="1.0" encoding="UTF-8"?><STUDENT xmlns:ibm="http://www.ibm.com"><STUDENT> <_ID>221345665</_ID> <Term> <SEMESTER>FA93</SEMESTER> <Courses_Taken> <COURSE_NBR>EG110</COURSE_NBR> </Courses_Taken> <Courses_Taken> <COURSE_NBR>MA220</COURSE_NBR> </Courses_Taken> <Courses_Taken> <COURSE_NBR>PY100</COURSE_NBR> </Courses_Taken> </Term> <Term> <SEMESTER>SP94</SEMESTER> <Courses_Taken> <COURSE_NBR>EG140</COURSE_NBR> </Courses_Taken> <Courses_Taken> <COURSE_NBR>EG240</COURSE_NBR> </Courses_Taken> <Courses_Taken> <COURSE_NBR>MA221</COURSE_NBR> </Courses_Taken> </Term></STUDENT>

2-121


The following example shows the output if the HIDEMS attribute is set equal to “1”:

XMLSETOPTIONS HIDEMS=1


<?xml version="1.0" encoding="UTF-8"?><STUDENT xmlns:ibm="http://www.ibm.com"><STUDENT> <_ID>221345665</_ID> <Term> <SEMESTER>FA93</SEMESTER> <COURSE_NBR>EG110</COURSE_NBR> <COURSE_NBR>MA220</COURSE_NBR> <COURSE_NBR>PY100</COURSE_NBR> </Term> <Term> <SEMESTER>SP94</SEMESTER> <COURSE_NBR>EG140</COURSE_NBR> <COURSE_NBR>EG240</COURSE_NBR> <COURSE_NBR>MA221</COURSE_NBR> </Term></STUDENT><STUDENT> <_ID>414446545</_ID> <Term> <SEMESTER>FA93</SEMESTER> <COURSE_NBR>CS104</COURSE_NBR> <COURSE_NBR>MA101</COURSE_NBR> <COURSE_NBR>FA100</COURSE_NBR> </Term> <Term> <SEMESTER>SP94</SEMESTER> <COURSE_NBR>CS105</COURSE_NBR> <COURSE_NBR>MA102</COURSE_NBR> <COURSE_NBR>PY100</COURSE_NBR> </Term></STUDENT><STUDENT> <_ID>424325656</_ID> <Term> <SEMESTER>SP94</SEMESTER> <COURSE_NBR>PY100</COURSE_NBR> <COURSE_NBR>PE100</COURSE_NBR> </Term></STUDENT>...>



Collapsemv Option

This option specifies whether to collapse <MV> and </MV> tags, using only one set of these tags for multivalued fields belonging to an association in the generated XML document and in the associated DTD or XMLSchema. This parameter applies only if the XML document is created in element mode.

0 - Expand MV tags for multivalued fields. 1 - CollapseMV tags for multivalued fields.

Collapsems Option

This attribute specifies whether to collapse <MS> and </MS> tags, using only one set of these tags for multi-subvalued fields belonging to an association in the generated XML document and in the associated DTD or XMLSchema. This parameter applies only if the XML document is created in element mode.

0 - Expand MS tags for multi-subvalued fields. 1 - Collapse MS tags for multi-subvalued fields.

2-123


The following example shows the output if the COLLAPSEMS attribute is set to “1”:

XMLSETOPTIONS COLLAPSEMS=1


<?xml version="1.0" encoding="UTF-8"?><STUDENT xmlns:ibm="http://www.ibm.com"><STUDENT> <_ID>221345665</_ID> <Term> <SEMESTER>FA93</SEMESTER> <Courses_Taken> <COURSE_NBR>EG110</COURSE_NBR> <COURSE_NBR>MA220</COURSE_NBR> <COURSE_NBR>PY100</COURSE_NBR> </Courses_Taken> </Term> <Term> <SEMESTER>SP94</SEMESTER> <Courses_Taken> <COURSE_NBR>EG140</COURSE_NBR> <COURSE_NBR>EG240</COURSE_NBR> <COURSE_NBR>MA221</COURSE_NBR> </Courses_Taken> </Term></STUDENT><STUDENT> <_ID>414446545</_ID> <Term> <SEMESTER>FA93</SEMESTER> <Courses_Taken> <COURSE_NBR>CS104</COURSE_NBR> <COURSE_NBR>MA101</COURSE_NBR> <COURSE_NBR>FA100</COURSE_NBR> </Courses_Taken> </Term> <Term> <SEMESTER>SP94</SEMESTER> <Courses_Taken> <COURSE_NBR>CS105</COURSE_NBR> <COURSE_NBR>MA102</COURSE_NBR> <COURSE_NBR>PY100</COURSE_NBR> </Courses_Taken> </Term></STUDENT>...>


:\ProgMarch


3Chapter

ram Fi18 201


IBM U2 Web Services Developer Deployment

Exporting Web Services . . . . . . . . . . . . . . . 3-3 Deploying the SOAP Server . . . . . . . . . . . . . . 3-5 Define Security between the Client and the SOAP Server . . . . 3-10 Set Connection Properties . . . . . . . . . . . . . . 3-12 Define UniVerse Database Connection Security. . . . . . . . 3-15Running and Stopping the SOAP Server . . . . . . . . . . . 3-18Monitoring a Remote SOAP Server . . . . . . . . . . . . . 3-19



The U2 Web Services Developer deployment feature enables you to select a SOAP server defined locally and generate a deployment package, in the form of a zip file, that contains the following:

WSDL filesThe runsoapserver and stopsoapserver scriptsAll required files for a runtime SOAP server

The zip file contains both a .bat and .sh script which enables you to deploy your web services on any platform.

You must be running JRE 1.5 or above to use the U2 Web Services Development deployment feature.



Exporting Web ServicesTo create the zip file to deploy your web services, right-click the SOAP server which contains the web service you want to deploy, as shown in the following example:

3-3


Click Export. The Export SOAP Servers dialog box appears, as shown in the following example:

In the Available SOAP Servers section, select the SOAP servers you want to export.

Enter the path for the zip file you want to create in the Archive File box, or click Browse to search for the location. By default, the U2 Web Services developer places the zip file in C:\IBM\U2Tools\soapservername.zip.



The following example shows sample contents of the zip file after the U2 Web Services Developer exports the SOAP server:

Deploying the SOAP ServerUnzip the zip file on the target machine. Review the rundeploytool.bat or runde-ploytool.sh file to verify that the path to javaw is correct.

From the directory where you unzipped the file, execute the rundeploytool command.

rundeploytool source_directory target_directory

For example:

rundeploytool . C:\temp\myservice

3-5


Expand Deployable SOAP Servers, right-click the SOAP server you want to deploy, then click Deploy, as shown in the following example. If the SOAP server already exists, click Deploy Into.



The U2 SOAP Service Deployment dialog box appears, as shown in the following example:

You can specify the environment for the new SOAP server in the U2 SOAP Service Deployment dialog box, including:

? The SOAP server configuration? The SOAP server connection security? The database connection properties? The database connection security

The Deployment tool populates the window with information from your local machine. You can change this information if necessary.

3-7


Server Name

In the Server Name box, enter a unique name for the SOAP server.

Site URL

The URL for the SOAP server you specify. Make sure the URL you specify is valid and accessible.

Port Number

The port number on which the server will listen.

Root Path

The path to the root directory where the definitions to the web service are stored.

Debug On

Select the Debug On check box if you want to capture debugging information. If you select this check box, the U2 IBM Web Services Developer starts the debug log each time you start the server.

Log File NameThe name of the debug log.

Connection Pooling On

The Connection Pooling On setting determines if the U2 Soap Server uses connection pooling to connect to UniVerse. The term connection pooling refers to the technology that pools permanent connections to data sources for multiple threads to share. It improves application performance by saving the overhead of making a fresh connection each time one is required. Instead of physically terminating a connection when it is no longer needed, connections are returned to the pool and an available connection is given to the next thread with the same credentials.

Connection Pooling in enabled by default. If you do not want to use Connection Pooling, clear the Connection Pooling On check box.



Note: IBM recommends using Connection Pooling for superior performance and scability.

Connection Pool Size

You can set the minimum and maximum size of the connection pool. If you do not define these sizes, the minimum size defaults to 1 and the maximum size defaults to 10. The minimum size determines the initial size of the connection pool.

The size of the connection pool changes dynamically between the minimum and maximum sizes you specify, depending on the system demands. When there are no pooled connections available, the U2 Soap Server either creates another connection, if the maximum connection pool size has not been reached, or keeps the thread waiting in the queue until a pooled connection is released or the request times out. If a pooled connection is idle for a specified time, it is disconnected.

Message Validation

Checks the SOAP request again the schema defined in the WSDL file. This option is time consuming. By default, message validation is not selected.

Default Name Space

The name space for the Web Services you define.

Server Cache SizeFor performance purposes, you can set this value to a number greater than 0 to indicate the number of web service definitions you want to keep in the cache. If you set this value, the SOAP Server will always try to read the web service definition from the cache first. If you do not set this value, the SOAP Server reloads the web service each time from disk.

If you are developing a web service, we recommend keeping this value at 0. This setting forces the SOAP Server to reload the new web service definition each time. Select the Cached Services tab to display the web services currently loaded in cache.

Click Next.

3-9


Define Security between the Client and the SOAP ServerClick the Specity Connection Security check box if you want to define connection security between the client and the SOAP server. The SOAP Server Connection Security dialog box appears, as shown in the following example:

Use SSLSelect the Use SSL check box if you want to define SSL security parameters.



Key Store

Enter the full path to the key store on the SOAP server.

Key Store Password

Enter the password corresponding to the key store you defined in the Key Store box.

In the Confirm Key Store Password box, reenter the password.

Key Password

Enter the encryption key password, if one exists, in the Key Password box. Reenter the password in the Confirm Key Password box.

Enable Authentication

If you want the client to send its certificate for authentication, select the Need Client Authentication check box.

Click Finish.

3-11


Set Connection PropertiesClick the DB Connection tab to define the connection properties for the SOAP server. The U2 Database - Connection Properties dialog box appears, as shown in the following example:

The deployment tool populates the fields in the U2 Database Connection Proper-ties dialog box based on the information contained in the deployable SOAP server. You can change this information if necessary.



Type

The type of database connection. At this release, the only type of connection supported is “fixed.”

Host

Enter the name of the host server. The server should be running.

Account

Enter the account name on the server you specified where you want attach when you connect to the server. This account must contain the data files you are accessing with the web service.

User ID and Password

In the User ID box, enter your log on name for the server. Enter the corresponding password in the Password box.

UniRPC Service Name

Enter the appropriate UniRPC Service Name in theUniRPC Service Name box. For UniVerse, the service name is uvcs.

UniRPC Port NumberEnter the port number of the UniRPC server running on the host in the UniRPC Port Number box.

3-13


Test Database Connection

To ensure that you can connect to the database, click Test Database Connection. If the connection is successful, the following message appears:

Use Connection Properties for Subsequent Servers

If you want to use the connection properties you specified for subsequent SOAP servers you deploy, select the Use this database connection and security for subsc-quent SOAP services during deployment check box.

Click Next.



Define UniVerse Database Connection SecurityClick the DB Security tab if you want to define security between the SOAP server and the UniVerse database. The U2 Database Connection Security dialog box appears, as shown in the following example:

Key Store

Enter the full path to the key store on the SOAP server, or click Browse to navigate to the key store.

3-15


Key Store Password

Enter the password corresponding to the key store you defined in the Key Store box.

In the Confirm Key Store Password box, reenter the password.

Key Password

Enter the encryption key password, if one exists, in the Key Password box. Reenter the password in the Confirm Key Password box.

Use Default Trust Store

Enable Authentication

If you want the client to send its certificate for authentication, select the Need Client Authentication check box.

Click Next.

For detailed information about SSL, see UniVerse Security Features.



U2 Web Services Developer deploys the web services you specified. When deployment is complete, a window similar to the following example appears:

The deployable web services appear in the SOAP Servers area of the U2 SOAP Service Deployment dialog box, and shown in the following example:

3-17


Running and Stopping the SOAP ServerTo run the SOAP server, in the target directory enter:

runsoapserver soap_server_name

To stop the SOAP server, in the target directory enter:

stopsoapserver soap_server_name



Monitoring a Remote SOAP ServerThrough the U2 Web Services Developer, you can monitor a remote SOAP server. Complete the following steps to set up remote monitoring:

Define the Remote ServerRight-click SOAP Servers, then click New SOAP Server. The Add a New SOAP Server dialog box appears, as shown in the following example:

Enter a name for the remote server in the Server Name box.

3-19


Enter the URL for the remote server in the URL box. Based on this URL, U2 Web Services Developer detects that the server is remote, and dims unavailable options, as shown in the following example:

Enter the port number for the remote server in the Port Number box.



If the remote SOAP server is running, a green icon appears next to the SOAP server, as shown in the following example:

3-21


Turn on LoggingRight-click the remote SOAP server, then click Turn on SOAP Server Debug to start logging, as shown in the following example:



U2 Web Services Developer displays the log from the remote server as shown in the following example:

Stop the Remote SOAP ServerTo stop the remote SOAP server, right-click the remote server you want to stop, then click Stop SOAP server.

Note: You cannot start the remote SOAP server from U2 Web Service Developer.

3-23

:\ProgMarch


4Chapter

ram Fi18 201


Pluggable Authentication Module (PAM)/LDAP

Pluggable Authentication Module (PAM) . . . . . . . . . . . 4-3 How UniVerse Authentication Currently Works. . . . . . . . 4-3 PAM Support . . . . . . . . . . . . . . . . . . 4-3



Pluggable Authentication Module (PAM)The PAM framework is a suite of shared libraries and modules on UNIX platforms that enable the local system administrator to choose how applications authenticate users. You can switch between authentication mechanisms without rewriting and recompling a PAM-aware application. You can plug in mechanisms for account, session, and password management through the PAM framework.

How UniVerse Authentication Currently WorksCurrently, UniVerse reads the encrypted password for a user from the passwd or the shadow file, then compares it with the encrypted form of the password the user supplies. If the passwords match, UniVerse authenticates the user and grants access to the system. If the passwords do not match the user’s request is rejected.

PAM SupportUniVerse 10.3 supports the PAM framework for the following products:

UniObjectsUniObjects for JavaUniObjects for .NETInterCallIBM JDBC Driver for UniData and UniVerseUniVerse ODBCUniOLEDB

UniVerse will not access LDAP servers directly from any of its servers, and will not support single sign-on. UniVerse will authenticate a client each time it tries to connect to a server, whether or not successful authentication occurred during a previous connection attempt.

When the server receives the user ID and password, UniVerse will first try to authen-ticate the user using the traditional UNIX method. If that attempt fails, UniVerse will call PAM to check the validity of the user. If both attempts fail, the connection is denied.

4-3

:\ProgMarch


5Chapter

ram Fi18 201


UniObjects For .NET Compact Framework

About UniObjects for .NET Compact Framework . . . . . . . . 5-4About the .NET Compact Framework . . . . . . . . . . . . 5-5 What Is the .NET Compact Framework? . . . . . . . . . . 5-5Features of UniObjects for .NET Compact Framework . . . . . . . 5-9 Limitations of UniObjects for .NET Compact Framework . . . . 5-9Setting Up the Development Environment in UniObjects for .NET

Compact Framework . . . . . . . . . . . . . . . . 5-10 Software Requirements . . . . . . . . . . . . . . . 5-10 Hardware Requirements . . . . . . . . . . . . . . . 5-11 Mobile CE Hardware Requirements . . . . . . . . . . . 5-11 Installing UniObjects for .NET Compact Framework . . . . . . 5-12Creating a UniObjects for .NET Compact Framework Application . . . 5-13 Building the Application . . . . . . . . . . . . . . . 5-18



This chapter introduces the IBM UniObjects for .NET Compact Framework interface. The chapter begins with a brief exploration of the .NET Compact Framework environment and how that is used in IBM UniObjects for .NET. It goes on to explain the differences between UniObjects for .NET and UniObjects for .NET Compact Framework. The final section demonstrates how to build a UniObjects for .NET Compact Framework application in Visual Studio 2005.



About UniObjects for .NET Compact Framework UniObjects for .NET Compact Framework is a proprietary middle-ware application program interface (API) designed specifically for software development in the .NET Compact Framework. This interface is managed code written in C# .

Software developers can use the UniObjects for .NET Compact Framework API within Visual Studio, and any CLR language (such as C#, VB.NET, or C++) to create applications for small hand-held devices.

You will need to know more about the.NET Compact Framework before we go on to discuss its use with UniObjects. The next section gives you a brief introduction to the .NET Compact Framework. For more information, please refer to Chapter 4, “Getting Started with UniObjects for .NET.”

5-4


About the .NET Compact FrameworkThe .NET Compact Framework is a subset of the .NET Framework, which is a complete software package for developing and delivering software applications.

The .NET Compact Framework is an environment in which managed applications are designed to run on Windows CE based devices, such as PDAs, mobile phones, factory controllers, and set-top boxes.

For a complete discussion on the differences between the .NET Framework and the .NET Compact Framework, please visit the MSDN Web site at http://msdn.microsoft.com.

What Is the .NET Compact Framework?The .NET Compact Framework is an integral Windows component for building and running software applications and Web services on small hand-held devices. It is composed of an optimized Common Language Runtime (CLR) and a unified set of class libraries.

The .NET Compact Framework is specifically designed to work with the limited resources available in the Windows CE Framework. It inherits the .NET system architecture and can use approximately 30 percent of the full .NET Framework class library. The .NET Compact Framework also has several libraries designed specifically for mobile devices.

Windows CE

Windows CE is the component-based, embedded operating system used by the .NET Compact Framework. The Windows CE system was created to work specifically with intelligent devices, and allows desktop developers to smoothly move desktop applications to these devices. Users can build an application that includes features such as forms, graphics, and Web services using a hand-held device.

Common Language Runtime (CLR)

The CLR is responsible for run-time services such as

language integration


http://msdn.microsoft.com


security enforcementmemory, process, and thread management

In addition, CLR has a role at development time when features such as life-cycle management, strong type naming, cross-language exception handling, and dynamic binding reduce the amount of code that the software developer must write to turn business logic into a reusable component.

The CLR is optimized for the .NET Compact Framework environment. The optimized CLR allows you to build and run applications without draining device batteries or taking up large amounts of memory.

Microsoft Intermediate Language (MSIL)

The .NET Compact Framework compilers generate this CPU-independent instruction set for the use of the Common Language Runtime. Before MSIL can be executed, the CLR must convert it to native, CPU-specific code.

Managed code

Managed code is executed and managed by the .NET Framework’s Common Language Runtime. Managed code must supply the instruction set necessary for the CLR to provide services such as memory management, cross-language integration, code access security, and automatic lifetime control of objects. All code that has been compiled in Microsoft Intermediate Language executes as managed code.

Unmanaged code

Unmanaged code is executed by the operating system, outside the .NET Framework’s Common Language Runtime. Unmanaged code must provide its own memory management, type checking, and security support, unlike managed code, which receives these services from the Common Language Runtime.

Class libraries

The .NET Compact Framework supports a subset of the .NET Framework class libraries. The class libraries provide a common, consistent development interface across all languages supported by the .NET Compact Framework, and are designed specifically to run on space and resource limited devices.

5-6


Base classes provide standard functionality such as input/output, string manipulation, security management, network communications, thread management, text management, and user interface design features.ADO.NET classes enable developers to interact with data accessed in the form of XML through the OLE DB, ODBC, Oracle, and SQL Server interfaces.XML classes enable XML manipulation, searching, and translation.ASP.NET classes support the development of Web-based applications and Web services.Windows Forms classes support the development of desktop-based smart client applications.

IBMU2.UODOTNET is the namespace assigned to UniObjects for .NET Compact Framework for the UniData and UniVerse databases.

UniObjects for .NET Compact Framework is the data access model for .NET Compact Framework applications that connect to the UniData and UniVerse databases. It contains a collection of classes that allow you to connect to the UniData and UniVerse databases, execute commands, and read and write results:

The UniSession class represents an open session to a UniData or UniVerse database.The UniFile and UniDictionary classes are used to access all file operations.The UniCommand class controls execution of database commands on the server. With it, users can run UniData or UniVerse commands or stored procedures on the server.The UniSubroutine class is used to execute cataloged BASIC server-side subroutine commands on the server.The UniTransaction class represents a Basic transaction to be made in a UniData or UniVerse database.The UniDataSet is a collection class used to read and write bulk UniRecord transactions in a UniData or UniVerse database.



Features of UniObjects for .NET Compact Framework UniObjects for .NET Compact Framework is managed code, written purely in C#. It does not use any functions outside of the .NET Compact Framework optimized CLR. The UniObjects for .NET Compact Framework code complies with the .NET Framework standard and it follows C# conventions for names, comments, and standards.

UniObjects for .NET Compact Framework shares the same source code base with UniObjects for .NET, and as such, most of the information in this guide applies to both UniObjects for .NET and UniObjects for .NET Compact Framework.

Limitations of UniObjects for .NET Compact FrameworkUniObjects for .NET and UniObjects for .NET Compact Framework share most of their core functions. There are, however, a few functional exceptions to UniObjects for .NET Compact Framework due to the constraints of the Compact Framework.

At this time, UniObjects for .NET Compact Framework does not support the following:

Connection poolingTracing and loggingPerformance countersSecure connectionConfiguration files

The SSL Stream class is not yet available in the .NET Compact Framework. Therefore, to ensure a secure connection for smart devices used out side a company’s Intranet, we recommended that you obtain a secure connection at a lower network level by using a VPN connection from the smart device to the company’s network.

Server-side applications still have logging and tracing capabilities, however, logging and tracing capabilities are not available on client-side applications at this release.

5-8


Setting Up the Development Environment in UniObjects for .NET Compact FrameworkThis section contains information on the requirements for setting up and installing UniObjects for .NET Compact Framework in your development environment:

Software RequirementsHardware RequirementsInstalling UniObjects for .NET Compact Framework

Software RequirementsThis section lists the software required to support UniObjects for .NET Compact Framework. Both client and documentation software components are required.

Client software components

The following table lists the client software components that must be installed before you install UniObjects for .NET Compact Framework.

Client Software Components

Software Requirement

Operating system Windows 2000 SP2 or later, or Windows XP Professional

Microsoft Data Access Compo-nents (MDAC)

Version 2.6 or later required by .NET Framework

.NET Framework Version 2.0 or later

UniData Version 7.1 or later

UniVerse Version 10.2 or later



Documentation software components

The following table lists the documentation software components that must be installed on your computer to support UniObjects for .NET.

Documentation Software Components


Internet software Microsoft Internet Explorer version 5.01 or later

Hardware RequirementsThe following table lists the development environment hardware required to support UniObjects for .NET Compact Framework.

Hardware Requirements


Processor Pentium 1 gigahertz (GHz) or greater recommended

Memory 512 MB RAM minimum

Hard disk space UniObjects for .NET component: 1 MBUniObjects for .NET Compact Framework component: 1 MB

Mobile CE Hardware RequirementsThe following table lists the development workstation hardware required to support UniObjects for .NET Compact Framework.

Hardware Requirements


Processor 400 megahertz (MHz) minimum

Memory 128 MB ROM; 128 MB RAM minimum

Operating System

Mobile 5 or Pocket PC 2003 (or later)

5-10


Installing UniObjects for .NET Compact FrameworkUniObjects for .NET Compact Framework is installed as part of the UniObjects Developer Kit (UniDK) installed on the U2 Clients CD. UniVerse 10.3 offers several options for installing UniObjects for .NET. Refer to Chapter 4, “Getting Started with UniObjects for .NET,” for complete installation instructions.



Creating a UniObjects for .NET Compact Framework ApplicationTo create a project:

1. Open Visual Studio 2005. Select File > New > Project from the toolbar menu. The New Project window opens.

2. Select the appropriate programming language from the project types window, and then expand [+] your selection.Note: The following example uses C#.

3. Select Smart Device from the list of devices, and then click the [+] button to expand the tree view. Select the appropriate device for your application. In this example, we use the Pocket PC 2003 device.

4. Give the application a name and then select OK to return focus to the Visual Studio window. An image of the selected device now appears in the design pane.

5-12


5. In the Solution Explorer pane, right-click the project name and select Add Reference from the menu.Select the Browse tab and navigate to the UODOTNET4CF.dll. The default location for this file is:

C:\IBM\unidk\uonet\bin 6. Click OK. Focus returns to the Visual Studio design pane.

To create an application:

Once you have created a project and added all of the appropriate references, you are ready to begin building your application.

In the following example, we create a UniXML application that displays customer information on the mobile device emulator.

1. Drag two buttons onto the form and position them at the top of the page. 2. Drag a DataGrid control onto the form and position the grid under the button

controls. 3. Drag a Label onto the form and position it under the DataGrid control.



4. Drag a TextBox onto the form and position it to the right of the Label. The form should now look similar to the one below:

5. In the Properties pane, set the properties for the controls you just created as follows:

Form Control Properties

Control name Property value

button 1 (Name) Set the Button 1 name to btnRUN

button 1Text Set the Button 1 text to RUN

button 2 (Name) Set the Button 2 name to btnQUIT

button 2 Text Set the Button 2 text to QUIT

Label Text Set the Label text to Customer ID

TextBox Text Set the TextBox Text field to empty

5-14


6. Once you have created all of the controls and updated all of the properties for those controls, you must create event handlers for each button control. To do this, double-click each control to open the Form.cs code view.While in the code view, you can change the code to run the application. Use the example code below to generate a list of customer names from the CUS-TOMER file, and then display them on the grid.

Note: You must double-click each control in the following order to generate the example code: RUN, QUIT, DataGrid, TextBox.



...

private void btnRUN_Click(object sender, EventArgs e) { // U2 DB Connect // for UniData use ("server_name", "user_id", "password", "demo", "udcs"); // UniVerse UniSession us = UniObjects.OpenSession("server_name", "user_ID", "password", "HS.SALES", "uvcs");

// Create XML Object UniXML unixml = us.CreateUniXML(); String id = textBox1.Text;

// Create XML document from LIST Command unixml.GenerateXML("LIST CUSTOMER " + id + " STATE" +

" CITY" + " ZIP");

// Get a dataset from XML DataSet ds = unixml.GetDataSet(); dataGrid1.DataSource = ds.Tables[0];

// Display dataset dataGrid1.Show();

// Close session UniObjects.CloseSession(us); }

private void btnQUIT_Click(object sender, EventArgs e) { Close(); }

private void dataGrid1_CurrentCellChanged(object sender, EventArgs e)

{

}

private void textBox1_TextChanged(object sender, EventArgs e) {

} }}

6. While in the code view, you also need to add the IBMU2.UODOT NET namespace to the application. Do this by adding the following code to the top of the page:

using IBMU2.UODOTNET;

5-16


Building the ApplicationOnce you have created the application, you will want to test it. Visual Studio allows you to test the application using the Device Emulator. The Emulator is a Visual Studio tool used to mimic device behavior for testing purposes, such as display orien-tation, serial port mapping, and networking support.

Note: You must have Microsoft ActiveSync installed in order to test the application. You can download the installation from the Microsoft Web site.

To build the application:

If it is not already open, open your application in Visual Studio 2005.

1. Build the application. To build the application, select Build > Build Solution from the Visual Studio toolbar.

2. Run the application. To run the application, select Tools > Device Emulator Manager from the Visual Studio toolbar. The Device Emulator Manager opens



3. A tree view list of devices appears in the Device Emulator Manager. Right-click the appropriate device and select Connect from the menu. The device emulator opens.

4. Click the Refresh button on the Device Emulator Manager. A green arrow now appears next to the selected device. Right-click the device and select Cradle from the menu.

5. The ActiveSync New Partnership wizard opens. You must use the wizard to establish a connection between your computer and the mobile device.

6. The wizard asks you to create a partnership between your computer and the emulator. Select the Guest Partnership option and then click Next. Note: If you are linking to an actual device, choose the Standard Partnership option and follow the wizard instructions.

The Microsoft ActiveSync window opens and informs you about the con-nection status of your application.

7. Once the connection is established, you can start the application. To start the application, select Debug > StartWithoutDebugging from the Visual Studio toolbar. The Deploy Device dialog box opens.

5-18


8. Choose the appropriate deployment device from the list that appears in the Deploy Device dialog box. For this example, we use the Pocket PC 2003 SE Emulator. Click Deploy.

The Device Emulator is now connected and ready to begin testing your application.

Click the Run button on your application. The information from the CUSTOMER file appears on the screen, as shown below.



Once the application is running, enter a specific customer ID into the text box and then click the RUN button. The information specific to that customer will display on the screen.

When you are done working with the application, click the QUIT button.

5-20

:\ProgMarch


6Chapter

ram Fi18 201


Using SSL with UniObjects for .NET

Software Requirements . . . . . . . . . . . . . . . . . 6-4Configuring the Database Server for SSL . . . . . . . . . . . 6-5UniObjects for .NET Secure Methods . . . . . . . . . . . . 6-7Installing a Certificate into a Windows Certificate Store . . . . . . 6-10



This chapter explains how to use SSL (Secure Socket Layer) with UniObjects for .NET.



Overview of SSL TechnologySecure Sockets Layer (SSL) is a transport layer protocol that provides a secure channel between two communicating programs over which arbitrary application data can be sent securely. It is by far the most widely deployed security protocol used on the World Wide Web.

Although it is most widely used in applications to secure web traffic, SSL actually is a general protocol suitable for securing a wide variety of other network traffic that is based on TCP, such as FTP and Telnet.

SSL provides server authentication, encryption and message integrity. It optionally also supports client authentication.

This document assumes that users who want to use this facility have some basic knowledge of public key cryptology.

For more information about the implementation of SSL with UniData and UniVerse, see the Developing UniBasic Applications manual for UniData and the Guide to UniVerse Basic for UniVerse.

6-4


Software RequirementsYou must have the following aplications installed and configured on the client machine:

Microsoft .NET Framework 2.0 or higherUniObjects for .NET version 2.2.1 or higher



Configuring the Database Server for SSLFirst, you need to create a Server Security Context Record (SCR).

A SCR contains all SSL related properties necessary for the server to establish a secured connection with an SSL client. The properties include the server’s private key, certificate, client authentication flag and strength, and trusted entities. For more information, see UniVerse Security Features.

The SCR can be generated by directly calling the UniData or UniVerse Security API from a BASIC program, or alternatively, by invoking UniAdmin.

The SCR is encrypted by a password and saved in a UniData or UniVerse security file with a unique ID. The path, password, and ID of the SCRfor a UniObjects for .NET server are important in the following descriptions.

In order to enable SSL support for UniObjects for .NET on the database server, you need to edit two configuration files, unirpcservices and .scrfile. Both of these files are locaed in the unishared /unirpc directory. On UNIX systems, you can determine the location of the unishared directory by enetering cat /.unishared. On Windows platforms, the default location can be found examining the registry record at:

HKEY_LOCAL_MACHINE\SOFTWARE\IBM\UniShared

First, on the database server, edit the unirpcservices file. Open the file with a text edi-tor, such ads vi on UNIX or Notepad on Windows platforms, and locate the line that corresponds to the UniObjects for .NET server. The line is similar to the following example:

uvcs C:\IBM\uv\bin\uvapi_server.exe * TCP/IP 0 3600

Append “SCR-ID password” to the end of this line as shown in the following exam-ple, where “SCR-ID” is the record ID of your Security Context Record.

uvcs C:\IBM\uv\bin\uvapi_server.exe * TCP/IP 0 3600 SCR-ID password

Now, edit the .scrfile. Refer to the section above to determine its location. This file contains the path to the Security Context Record store, which contains the Security Context Record specified in the “unirpcservices” file. The file format is as follow:

service-name path

6-6


For example:

uvcs c:\IBM\uv\test

Once these files have been edited appropriately, the database server should be prop-erly configured.



UniObjects for .NET Secure MethodsThe following four methods have been added to the UniObjects object for creating a secure connection:

public static UniSession OpenSecureSession (string hostname, string userid, string password, string account, X509Certificate clientcertificate)

This method returns a new UniSession object, which opens a connection to the UniData or UniVerse database.

string hostname is the name or network address of the instance of the UniData or UniVerse database to which to connect.

string userid is the user’s login name on the UniData or UniVerse database.

string password is the user’s password on the UniData or UniVerse database.

string account is the name of the UniData or UniVerse database account.

X509Certicate clientcertificate is the client certificate in case the server requires client authentication. If the server does not require client authentication, set this value to null. The X509Certificate is a Microsoft .NET framework class. For information about this class, see

http://msdn.microsoft.com/enus/library/system.security.cryptogra-phy.x509certificates.x509certificate.aspx

public static UniSession OpenSecureSession (string hostname, string userid, string password, string account, string service, X509Certificate clientcertificate)




6-8




string service is the type of UniData or UniVerse database account: udvs for UniData or uvcs for UniVerse.



public static UniSession OpenSecureSession (string hostname, int port, string userid, string password, string account, X509Certificate clientcertificate)



int port is the port number on the host to use for the connection.








public static UniSession OpenSecureSession (string hostname, int port, string userid, string password, string account, string service, X509Certificate clientcertificate)



int port is the port number on the host to use for the connection.f




string service is the type of UniData or UniVerse database account: udvs for UniData or uvcs for UniVerse.



If any of this group of methods fail, it throws an Exception.

6-10


Installing a Certificate into a Windows Certificate StoreIn order for UniObjects for .NET to function properly, you must install your root certificate in the Windows Trusted Root Certificate Store.

Fromthe Internet Explorer toolbar, click Tools, then click Internet Options, then click the Contents tab, then click Certificates. A window similar to the following example appears:

Click Import. Follow the Certificate Import wizard to install your root certificate. The import file name is your_root_cert_name, such as myroot.cer. Make sure you import the certificate into the “Trusted Root” certificate store.


:\ProgMarch


7Chapter

ram Fi18 201


Basic Developer Toolkit

The U2 Resource View . . . . . . . . . . . . . . . . . 7-3 Filters . . . . . . . . . . . . . . . . . . . . . 7-3 Comparing Source Code . . . . . . . . . . . . . . . 7-8 Setting UniVerse BASIC Program Options . . . . . . . . . 7-13The Basic Program Editor . . . . . . . . . . . . . . . . 7-14 Syntax Highlighting . . . . . . . . . . . . . . . . 7-14 Code Assist . . . . . . . . . . . . . . . . . . . 7-16 Collapsing Blocks of Text . . . . . . . . . . . . . . 7-22 The Outline View . . . . . . . . . . . . . . . . . 7-23 Code Templates . . . . . . . . . . . . . . . . . . 7-24 Refactoring . . . . . . . . . . . . . . . . . . . 7-26 Dynamic Array Editor. . . . . . . . . . . . . . . . 7-29 XML Editor . . . . . . . . . . . . . . . . . . . 7-29


At this release, the Basic Developer Toolkit is introduced. This tool enables you to write UniVerse BASIC code using a number of views and wizards, in addition to advanced editing and debugging support. Features include syntax highlighting, code assistance, a built-in compiler, and other tools.

The Basic Developer Tool runs on a client machine and accesses resource reposi-tories and runtime environments on the UniVerse server.

This section describes the Basic Developer Toolkit perspective. For more infor-mation, including information about installation and debugging a UniVerse BASIC program, see the Basic Developer Toolkit manual.

The following example illustrates the default Basic Developer Toolkit perspective:

ResourceView Outline

View

DictionaryView

PropertiesView

ProblemsView

ConsoleView

CommandView

DebugView

Editing Area


The U2 Resource ViewThe U2 Resource View contains information about each UniVerse account of the server to which you are connected. This information includes accounts, data files, dictionary files, UniVerse BASIC programs, XML/DB mapping files, and cataloged programs. The following example illustrates the U2 Resource information for the HS.SALES account:

FiltersYou can establish filters to filter out information you do not want the Basic Developer Toolkit to display. There are two types of filters, Resource-type filters and pattern filters.

Resource-type Filters

Resource-type filters include server filters, account filters, and file filters.

The U2 Resource View 7-4

Server Filter

Use the server filter to exclude UniVerse servers from being displayed in the Basic Developer Toolkit. By default, the server filter is empty.

Account Filter

Use the account filter to exclude UniVerse accounts from being displayed in the Basic Developer Toolkit. By default, the Basic Developer Toolkit filters out UniVerse system accounts using the following pattern:

Master*, sys*, bin_*.

File Filter

Use the file filter to exclude UniVerse files from being displayed in the Basic Developer Toolkit. By default, UniVerse excludes the following files:

CTLGSAVEDLISTS&HOLD&&PH&&XML&savedlists&MAP&&report&AE-related filesCTLGTBENGLISH.MSGERRMSGHELP.FILEMENUFILEREP_RECV_LOGREP_RECV_RECVOC&DEBUG&


&MAP&vocprivilege&REPORT&&SCREEN&UV.ACCOUNTAPP.PROGSBASIC.HELPcatdirGLOBAL.CATDIRNLS-related filesDICT. filesUNIVERSE. filesUV_ filesUV. filesSYS. filesREVISE. files

Pattern Filters

Use a pattern filter to exclude any name defined by the pattern you specify from being displayed in the Basic Developer Toolkit.


Creating a Filter

To create a filter, click the Filter icon in the U2 Resource View, as shown in the following example:

FilterIcon


The U2 Explorer Filters dialog box appears, as shown in the following example:

If you want to create a pattern filter, select the Name filter patterns check box. Separate each pattern with a comma (,). Pattern matching characters are:

* = any string? = any character,, (2 commas) = , (comma)


Select the type of Resource filter you want to create in the Select the filters to exclude matched elements from the viewarea. You can also click Select All to select all of the filters, Deselect All to clear all of the filters, or Invert Selection.

In the Filter Details dialog box, enter the pattern matching details for the type of fil-ter you selected.

Comparing Source CodeYou can compare two UniVerse BASIC programs with each other to display the differences in the programs.


Select the first program you want to compare in the account and file where it resides. Holding down the CTRL key, select the second program with which you want to compare the first. Using the right mouse key (right-click), select Compare With, the select Each Other, as shown in the following example:


In the following example, the RefactoringExample2 program has the DONE variable changed to FINISHED. The first program you select appears in the left frame, while the second program you select appears in the right frame. The Basic Developer Toolkit highlights the differences in the programs:


Comparing Local History

You can compare the history of changes to a program made on your local machine. To compare local history, right-click the program for which you want to view history, then select Team, the click Show Local History, as shown in the following example:


The Basic Developer Toolkit shows the local history for the program you selected, as shown in the following example:

You can compare changes made to the programby select the two revision times you want to compare, then follow the steps in “Comparing Source Code” on page 9.


Setting UniVerse BASIC Program OptionsYou can specify compilation and cataloging options for UniVerse BASIC programs at the account-level or the program-level. To set program options, right-click the account or directory file for which you want to set the options, then click U2 Basic Program Options. A dialog box similar to the following example appears:

Select the catalog options for the directory or account, then click Finish.

Note: Program options set at the directory-level override program options set at the account-level.


The Basic Program EditorThe Basic Program Editor provides several options to assist you in creating or editing UniVerse BASIC programs, including:

Syntax HighlightingCode Assist

Syntax HighlightingThe Basic Developer Toolkit recognizes UniVerse BASIC syntax, and provides syntax highlighting. You can configure the colors used and formatting for the code. The Basic Developer Toolkit highlights syntax error marks after each unsuccessful compilation.


Customizing Syntax Colors

To customize the colors for syntax highlighting, click Window, then click Prefer-ences, then click U2 Basic, expand Editor, then click Syntax Coloring. A dialog box similar to the following example appears:

You can customize the coloring for the following elements:

KeywordReserved wordFunction Name@ VariableStringCommentOther

The Basic Program Editor 7-16

Code AssistCode Assist uses code templates and helps in avoiding syntax errors. Code assist checks the following elements in addition to the code template:

VerbsKeywordsFunctions@ Variables$ VariablesDefined labelsDefined variablesDefined user functions

The Basic Developer Toolkit uses as set of default verbs, keywords, functions, @ variables and $ variables, defined in Appendix A, “Default Symbols and Words.” You can override these defaults by creating the XTOOLSUB.DATA file in the universe_home/include directory. This file contains two sections, one for symbols and one for words.

Specifying Symbols

The symbols section should start with “*symbols” and each line of the section should have the following format:

{“symbol_name”, symbol_type, 0}

The symbol_type should be one of the following:

Vavariable – @ Variable (read/write)Vrvariable – @ Varaible (read only)Vprequate – Pre-defined equate statement


The following example illustrates the symbols section of the file:

**symbols*{"@SYSTEM.RETURN.CODE", Vavariable, 0}{"@STDFIL", Vavariable, 0}{"@SELECTED", Vavariable, 0}{"@IM", Vprequate, 0, "Add: more ITM"}{"@FM", Vprequate, 0}{"@AM", Vprequate, 0}{"@VM", Vprequate, 0}...

Specifying Words

The words section should start with “*words” and each line of the section should have the following format:

{“name”, type, num_of_args, max_num_of_args, optional_arg_flag, left_value_arg_list, optional_description}

The following table describes valid values for the type variable:

Type Description

Lunknown Type unknown

Lbflag Statement that starts at the line.

Lbfunc Function style statement (CONVERT, DELETE, REMOVE)

Lbos Beginning of line statement

Lelse Special case: ‘ELSE’

Lend Special case: ‘END’

Lflag Check keyflag

Lfunct Check for following ‘(‘

Lloc Special case: ‘LOCATE’

Llock Special case: ‘LOCKED’ (also checks keyflag)

Lloop Special case: ‘UNTIL’ & ‘WHILE’

words Section Types


The code assist feature uses the num_of_args, max_num_of_args, optional_arg_flag, and left_value_arg_list for functions only.

The following example illustrates the *words portion of the XTOOLSUB.DATA file:

**words* {"$DEFINE", Lbos, 0, 0, 0, 0} {"$ELSE", Lcdir, 0, 0, 0, 0} {"$ENDIF", Lcdir, 0, 0, 0, 0} {"$F", 0, 0, 0, 0, 0} {"$FALSE", 0, 0, 0, 0, 0} {"$IFDEF", Lbig, 0, 0, 0, 0} {"$IFNDEF", Lbig, 0, 0, 0, 0} {"$OPTIONS", Lbos, 0, 0, 0, 0}...

Lnext Special case: ‘NEXT’

Lsub Special case: ‘SUBROUTINE’

Lthen Special case: ‘THEN’

Lget Special case: ‘GET (‘

Lseek Special case: ‘SEEK (‘

Lprntr Special case: ‘PRINTERR’

Lexec Special case: ‘PERFORM’

Lstat Special case: ‘STATUS’

Lerror Special case: ‘(ON) ERROR

Lbig Special case: ‘$DEFINE, $UNDEFINE

Lcdir Special case: ‘$ELSE, $ENDIF

Type Description

words Section Types (continued)


Using Code Assist with GOSUB

If you enter a GOSUB or GOTO statement, The Basic Developer Toolkit displays all the labels contained in the program. Enter:

GOSUB (CTRL+SPACE)

The Basic Developer Toolkit displays all labels with the program, as shown in the following example:

Select the correct subroutine from the list.


Using Code Assist with CALL

If you enter a CALL statement followed by a (CTRL + space), the Basic Developer Toolkit displays all globally and locally cataloged programs in alphabetical order, as shown in the following example:

Using Code Assist with Functions

When you enter the name of a UniVerse function, the Basic Developer Toolkit displays details information for the function. In the next example, the following code was entered:

RET = XDOM(CTRL+SPACE)


The Basic Developer Toolkit displays all functions beginning with “XDOM” as shown in the following example:

When you select the function, the Basic Developer Toolkit inserts the function as a template, as shown in the following example:

You can enter the tab key to enter your values for the function parameters.

Viewing Syntax

You can hover over a UniVerse BASIC function or statement to view the syntax. After the syntax appears, click the F2 to keep the syntax on the screen. The following example illustrates the syntax for the XDOMOpen function:


Collapsing Blocks of TextYou can collapse certain blocks of text within the program. Consider the following LOOP statement:

If you click the “-” icon, the Basic Developer Toolkit collapes the statement. After the statement is collapsed, you can hover over the “+” to view the statement, as shown in the following example:


The Outline ViewThe Basic Developer Toolkit displays all procedures and lables that appear in the source code you specify. With this outline, you can easily jump to appropriate reference in the source code. The following example illustrates an outline view:

The Basic Developer Toolkit uses the following icons:

Included FileLabelVariable or user functionCommon variableArray


Code TemplatesThe Basic Developer Toolkits allows you to use code templates, which are definitions of the UniVerse BASIC syntactical constructions. You can create your own code templates to expand your own shortcuts, such as a template to insert the author and date for the source code.

From the Window menu, click Preferences, expand U2 Basic, expand Editor, then click Templates. A dialog box similar to the following example appears:


The following example illustrates the template for the FOR statement:

To create a new template, from the Templates dialog box, click New. To edit and existing template, click Edit. To delete a template, click Remove.


Creating a Template Automatically

From the Basic Developer Toolkit Editor, you can automatically create a template by marking a segment of the source code. After marking the source code, click the U2 Basic , then click Copy Selection as Template. A dialog box similar to the following example appears:

In the Name box, enter the name for the new template. Enter a description for the template in the Description box.

RefactoringThe Basic Developer Toolkit supports refactoring for renaming variables or labels in the current UniVerse BASIC source code. Refactoring changes a program’s internal structure without modifying its external behavior or existing functionality. You usually refactor a program to improve the readability, improve extensibility, or simplify code structure.


Right-click the name of an element you want to change in your UniVerse BASIC source code, expand Refactor, then click Rename. A dialog box similar to the following example appears:


Enter the new name for the element, then click Preview. The Basic Developer Toolkit displays the instances of the original variable name and previews the changes, as shown in the following example:

To process the changes, click OK, or click Cancel to exit the program without changing the element name.


Dynamic Array EditorYou can edit a program using a dynamic array editor. Select the source code you would like to edit, then click the U2 Basic menu, then click Edit Selection as Dynamic Array. The dynamic array editor appears, as shown in the following example:

XML EditorYou can edit a program using an XML editor. Select the source code you would like to edit, as shown in the following example:

doc='<ADDRBOOK cmt="my address book"> <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>[email protected]</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>[email protected]

m</EMAIL> </ENTRY> </ADDRBOOK>'


Click the U2 Basic menu, then click Edit Selection as XML. The XML editor appears, as shown in the following example: