unidata 7.2 new features - rocket software · the eda driver api enables you to write your own...

C:\Program Files\Adobe\FrameMaker8\UniData 7.2\7.2rebranded\NEWFEATURES\NEWFEATTITLE.fmMarch 8, 2010 2:01 pm

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

UniData

UniData 7.2 New Features

UDT-720-NF-1

ii UniData 7.2 New

C:\Program Files\Adobe\FrameMaker8\UniData 7.2\7.2rebranded\NEWFEATURES\NEWFEATTITLE.fmMarch 8, 2010 2:01 pm

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

Notices

EditionPublication date: June 2008Book number: UDT-720-NF-1Product version: UniData 7.2

Copyright© Rocket Software, Inc. 1988-2008. 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

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

UniData 7.2 New Features iii

http://www.rocketsoftware.com

http://www.rocketsoftware.com

Table of Contents

:\ProgbookT

Table of Contents

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

Chapter 1 External Database Access APIExternal Database Access Driver API . . . . . . . . . . . . . 1-2Registering an EDA Driver . . . . . . . . . . . . . . . . 1-3EDA Driver Functions . . . . . . . . . . . . . . . . . 1-4

EDADRV_LoadSymbols . . . . . . . . . . . . . . . 1-5EDADRV_Connect . . . . . . . . . . . . . . . . . 1-7EDADRV_Disconnect . . . . . . . . . . . . . . . . 1-9EDADRV_EndTransaction . . . . . . . . . . . . . . 1-10EDADRV_PrepareStmt . . . . . . . . . . . . . . . 1-11EDADRV_ExecuteStmt . . . . . . . . . . . . . . . 1-13EDADRV_CloseStmt . . . . . . . . . . . . . . . . 1-15EDADRV_DropStmt . . . . . . . . . . . . . . . . 1-16EDADRV_FetchStmt . . . . . . . . . . . . . . . . 1-17EDADRV_Perform . . . . . . . . . . . . . . . . . 1-19EDADRV_GetEDAAttr . . . . . . . . . . . . . . . 1-20EDADRV_GetErrmsg . . . . . . . . . . . . . . . . 1-22EDADRV_Cleanup . . . . . . . . . . . . . . . . . 1-23EDADRV_FreeResult . . . . . . . . . . . . . . . . 1-23EDADRV_GetDBInfo . . . . . . . . . . . . . . . . 1-24EDADRV_GetSpecialInfo. . . . . . . . . . . . . . . 1-26

ECL Command . . . . . . . . . . . . . . . . . . . . 1-29EDA Driver Log Files. . . . . . . . . . . . . . . . . . 1-30The EDA Driver Header File . . . . . . . . . . . . . . . 1-31

Chapter 2 Pluggable Authentication Module (PAM)Pluggable Authentication Module (PAM) . . . . . . . . . . . 2-2

How UniData Authentication Currently Works . . . . . . . . 2-2PAM Support . . . . . . . . . . . . . . . . . . . 2-2

ram Files\Adobe\FrameMaker8\UniData 7.2\7.2rebranded\NEWFEATURES\NEWFEATTOC.fm OC template)

v UniD

Chapter 3 Automatic Data EncryptionEncrypted File Types . . . . . . . . . . . . . . . . 3-2Encryption With UniData Data Replication . . . . . . . . . 3-2

Key Store . . . . . . . . . . . . . . . . . . . . . 3-3How Encryption Works . . . . . . . . . . . . . . . . . 3-4Defining a Master Key . . . . . . . . . . . . . . . . . 3-6

Changing a Master Key After Data is Encrypted . . . . . . . 3-7Using Encryption Wallets . . . . . . . . . . . . . . . . 3-8

Wallet ECL Commands . . . . . . . . . . . . . . . 3-8UniData Encryption Algorithms . . . . . . . . . . . . . . 3-10Changes to UniData Utilities . . . . . . . . . . . . . . . 3-11

convmark. . . . . . . . . . . . . . . . . . . . 3-11udtlangconfig . . . . . . . . . . . . . . . . . . 3-11dumpgroup . . . . . . . . . . . . . . . . . . . 3-12fixgroup . . . . . . . . . . . . . . . . . . . . 3-12fixfile . . . . . . . . . . . . . . . . . . . . . 3-12guide . . . . . . . . . . . . . . . . . . . . . 3-12newacct . . . . . . . . . . . . . . . . . . . . 3-12shfbuild . . . . . . . . . . . . . . . . . . . . 3-13

Encryption Commands . . . . . . . . . . . . . . . . . 3-14CREATE.ENCRYPTION.KEY . . . . . . . . . . . . . 3-14DELETE.ENCRYPTION.KEY . . . . . . . . . . . . . 3-14LIST.ENCRYPTION.KEY . . . . . . . . . . . . . . 3-15GRANT.ENCRYPTION.KEY . . . . . . . . . . . . . 3-16REVOKE.ENCRYPTION.KEY . . . . . . . . . . . . 3-17ENCRYPT.FILE . . . . . . . . . . . . . . . . . 3-18DECRYPT.FILE . . . . . . . . . . . . . . . . . 3-20LIST.ENCRYPTION.FILE . . . . . . . . . . . . . . 3-22ACTIVATE.ENCRYPTION.KEY . . . . . . . . . . . . 3-22DEACTIVATE.ENCRYPTION.KEY . . . . . . . . . . . 3-23DISABLE.DECRYPTION . . . . . . . . . . . . . . 3-23ENABLE.DECRYPTION . . . . . . . . . . . . . . 3-24

UniBasic Encryption Commands . . . . . . . . . . . . . . 3-26ACTIVATEKEY . . . . . . . . . . . . . . . . . 3-26DEACTIVATEKEY . . . . . . . . . . . . . . . . 3-27DISABLEDEC . . . . . . . . . . . . . . . . . . 3-29ENABLEDEC . . . . . . . . . . . . . . . . . . 3-31STATUS Function Changes . . . . . . . . . . . . . . 3-32FILEINFO() Function Changes . . . . . . . . . . . . . 3-33

The encman Utility . . . . . . . . . . . . . . . . . . 3-34

ata 7.2 New Features

Viewing Audit Trail Information . . . . . . . . . . . . . 3-34Generating a Key Store . . . . . . . . . . . . . . . . 3-35Removing a Key Store . . . . . . . . . . . . . . . . 3-36Importing and Exporting Metadata . . . . . . . . . . . . 3-36

Installation Changes . . . . . . . . . . . . . . . . . . 3-39New Installations . . . . . . . . . . . . . . . . . . 3-39Upgrade Installation . . . . . . . . . . . . . . . . . 3-39

Using UniAdmin for Encryption . . . . . . . . . . . . . . 3-41Adding an Encryption Key. . . . . . . . . . . . . . . 3-42Deleting an Encryption Key . . . . . . . . . . . . . . 3-42Viewing Encryption Key Details . . . . . . . . . . . . . 3-43Granting Privileges . . . . . . . . . . . . . . . . . 3-44Revoking Privileges . . . . . . . . . . . . . . . . . 3-45Encryption Wallet Management . . . . . . . . . . . . . 3-46Deleting an Encryption Wallet . . . . . . . . . . . . . 3-47Viewing Encryption Wallet Details . . . . . . . . . . . . 3-48Granting Privileges to Encryption Wallet . . . . . . . . . . 3-50Revoking Encryption Wallet Privileges . . . . . . . . . . . 3-51Encrypting a File . . . . . . . . . . . . . . . . . . 3-52Decrypting a File . . . . . . . . . . . . . . . . . . 3-55Listing Encryption Information . . . . . . . . . . . . . 3-58Viewing Audit Information . . . . . . . . . . . . . . 3-60

Chapter 4 XML EnhancementsSummary of XML Enhancements . . . . . . . . . . . . . . 4-2

In This Chapter . . . . . . . . . . . . . . . . . . 4-2XML Configuration File . . . . . . . . . . . . . . . . . 4-4

xmlconfig Parameters . . . . . . . . . . . . . . . . 4-5ECL Commands . . . . . . . . . . . . . . . . . . . 4-14

New Session-level ECL Commands . . . . . . . . . . . . 4-14Existing ECL Command Affected by XMLSETOPTIONS Command or

XMLSetOptions() API . . . . . . . . . . . . . 4-20UniBasic APIs . . . . . . . . . . . . . . . . . . . . 4-22

New Session-level XML APIs . . . . . . . . . . . . . 4-22Existing APIs That Support Additional XML Parameters . . . . . 4-29Existing APIs Affected by XML Options . . . . . . . . . . 4-42

Chapter 5 UniData Replication EnhancementsEnabling and Disabling Replication . . . . . . . . . . . . . 5-4Replication Files with Multiple VOC Pointers . . . . . . . . . . 5-5

Table of Contents vi

vii UniD

Listing Replication Files . . . . . . . . . . . . . . . . 5-6UniData Command Replication . . . . . . . . . . . . . . 5-7

File-Level Command Replication . . . . . . . . . . . . 5-7Other Command Replication . . . . . . . . . . . . . 5-8

Writeable Subscriber Files . . . . . . . . . . . . . . . . 5-9Replication Configuration File Changes. . . . . . . . . . . . 5-10

LEVEL Phrase . . . . . . . . . . . . . . . . . . 5-10FILE Phrase . . . . . . . . . . . . . . . . . . . 5-10EXCLUDED_FILE Phrase . . . . . . . . . . . . . . 5-11RESERVED_FILE_SPACE Phrase . . . . . . . . . . . 5-11Account-Level Group Example . . . . . . . . . . . . . 5-12

Dual-threaded Subscriber Processing . . . . . . . . . . . . 5-13Compatibility with Previous UniData Releases . . . . . . . . . 5-14

Upgrading to UniData 7.2 . . . . . . . . . . . . . . 5-14UniData Data Replication Restrictions . . . . . . . . . . . . 5-15

Chapter 6 Miscellaneous Enchancements64-bit Sequential File Access . . . . . . . . . . . . . . . 6-2Support for 64-bit Log Files with The Recoverable File System . . . . 6-4

Backing Up Archive Files . . . . . . . . . . . . . . 6-4Log File Size Recommendations . . . . . . . . . . . . 6-5

Resizing Files Concurrently . . . . . . . . . . . . . . . 6-6ECL RESIZE Command Enhancements . . . . . . . . . . 6-6Recovering from a Concurrent Resize Error . . . . . . . . . 6-8File Tools Enhancements . . . . . . . . . . . . . . . 6-9Log Files . . . . . . . . . . . . . . . . . . . . 6-9

Extensible Administration Tool . . . . . . . . . . . . . . 6-10New Stub Functions for OFS . . . . . . . . . . . . . . . 6-12

activatekey . . . . . . . . . . . . . . . . . . . 6-12disabledec . . . . . . . . . . . . . . . . . . . 6-12

Chapter 7 Deploying Web ServicesExporting Web Services . . . . . . . . . . . . . . . 7-2Deploying the SOAP Server . . . . . . . . . . . . . . 7-4Define Security between the Client and the SOAP Server . . . . 7-8Set Connection Properties . . . . . . . . . . . . . . 7-10Define UniData Database Connection Security . . . . . . . . 7-13

Running and Stopping the SOAP Server . . . . . . . . . . . 7-16Monitoring a Remote SOAP Server . . . . . . . . . . . . . 7-17

ata 7.2 New Features

1Chapter

External Database Access API

External Database Access Driver API . . . . . . . . . . . . 1-2Registering an EDA Driver . . . . . . . . . . . . . . . 1-3EDA Driver Functions . . . . . . . . . . . . . . . . . 1-4 EDADRV_LoadSymbols . . . . . . . . . . . . . . . 1-5 EDADRV_Connect . . . . . . . . . . . . . . . . 1-8 EDADRV_Disconnect . . . . . . . . . . . . . . . 1-9 EDADRV_EndTransaction . . . . . . . . . . . . . . 1-10 EDADRV_PrepareStmt . . . . . . . . . . . . . . . 1-11 EDADRV_ExecuteStmt . . . . . . . . . . . . . . . 1-13 EDADRV_CloseStmt . . . . . . . . . . . . . . . . 1-15 EDADRV_DropStmt . . . . . . . . . . . . . . . . 1-16 EDADRV_FetchStmt . . . . . . . . . . . . . . . . 1-17 EDADRV_Perform . . . . . . . . . . . . . . . . 1-19 EDADRV_GetEDAAttr . . . . . . . . . . . . . . . 1-21 EDADRV_GetErrmsg. . . . . . . . . . . . . . . . 1-23 EDADRV_Cleanup . . . . . . . . . . . . . . . . 1-24 EDADRV_FreeResult . . . . . . . . . . . . . . . . 1-24 EDADRV_GetDBInfo . . . . . . . . . . . . . . . 1-25 EDADRV_GetSpecialInfo . . . . . . . . . . . . . . 1-27ECL Command . . . . . . . . . . . . . . . . . . . 1-30EDA Driver Log Files . . . . . . . . . . . . . . . . . 1-31The EDA Driver Header File . . . . . . . . . . . . . . . 1-32

External Database Access Driver APIExternal Database Access (EDA) enables you to convert data stored in the UniData database to a 1NF database, such as IBM DB2, then access that data using existing UniBasic programs, UniQuery, or UniData SQL.

Note: EDA was not designed to access data that already resides in a 1NF database. To access this type of data, use the UniBasic SQL Client Interface (BCI).

The EDA Driver API enables you to write your own driver to access data in any relational database, such as Microsoft SQLServer or Informix Dynamic Server. The EDA Driver API is a set of sixteen functions which EDA calls to communicate with an external database.

1-2 UniData 7.2 New Features

Registering an EDA DriverEDA drivers definitions reside as records in the EDA_DRIVER file, located in $UDTHOME/sys. The following table describes each attribute of the EDA_DRIVER record:

EDA Driver Attributes

AttributeNo Attribute Name Description

0 @ID The record ID for the EDA driver.

1 Data Model The type of database to which the driver is connecting. At this release, the only valid value is 1NF.

2 DBMS Family The name of the database management system family. Valid values are:

DB2

IBMU2

ORACLE

Microsoft SQL Server

Other

3 DBMS Name The user-defined name and version of the database management system.

4 Description A user-defined description of the EDA driver.

5 Driver Name The name of the driver dll.

6 Driver Version The version of the EDA driver.

7 Driver Supplier Name The name of the supplier of the EDA driver.

8 Driver Creation Date The date the EDA driver was created.

Registering an EDA Driver 1-3

EDA Driver FunctionsThe following table lists the EDA Driver functions.

EDA Driver Functions

Function Name Description

EDADRV_LoadSymbols Loads other functions to the EDA Driver symbol array.

EDADRV_Connect Connects to an external database.

EDADRV_Disconnect Disconnects from an external database.

EDADRV_EndTransaction Ends a transaction on an external database.

EDADRV_PrepareStmt Prepares a statement.

EDADRV_ExecuteStmt Executes an SQL statement that has been prepared with the EDADRV_PrepareStmt function.

EDADRV_CloseStmt Closes a statement.

EDADRV_DropStmt Closes a statement and makes in unavailable.

EDADRV_FetchStmt Retrieves rows from an open cursor.

EDADRV_Perform Executes a statement directly on the external database.

EDADRV_GetEDAAttr Communicates an EDA attribute value to the driver.

EDADRV_GetErrmsg Retrieves the last error message.

EDADRV_Cleanup Releases memory, external handles, and the environment.

EDADRV_FreeResult Frees the buffer allocated for the result set.

EDADRV_GetDBInfo Retrieves information about the database.

EDADRV_GetSpecialInfo Retrieves information about the database to which the application is connected, such as rename table, rename index, and BLOB data type equivalents.

Note: See the edadrv_public.h file described in The EDA Driver Header File for the definition of all data types and symbols used in the EDA Driver API. The edadrv_public.h file resides in the $UDTHOME/edadrv_exam directory.


EDADRV_LoadSymbolsThe EDADRV_LoadSymbols function loads other functions to the EDA Driver Symbol array. This is the first function EDA calls.

Syntax

RETCODE EDA_LoadSymbols(numsymbols, symbols)

Output Variables

The following table describes the output variables.

EDADRV_LoadSymbols Output Variables

Type Argument Description

int * numsymbols The number of symbols returned.

EDA_T_SYMBOL * symbols The Driver Symbol Array pointer.

Description

The EDA Driver Symbol array is an array of structures of the type EDA_T_SYMBOL. It contains pointers to all other driver functions as array elements.

EDA Driver Functions 1-5

EDADRV_LoadSymbols allocates memory for the Driver Symbol array, fills in the array with either pointers to other driver functions or constants according to the following template.

Array Index Array Element Value Description

0 EDASYM_DBTYPE The driver’s data model. At this release, UniData only supports EDA_1NF.

1 EDASYM_DBFAMILY The name of the driver database, such as DBMS_DB2, DBMS_MSSQLSERVER, DBMS_OTHERS. For more infor-mation, see “Registering an EDA Driver” on page 3.

2 EDASYM_VERSION The version of this driver. This is for information purposes only, EDA does not use this value.

3 EDASYM_CONNECT The pointer to EDADRV_Connect.

4 EDASYM_DISCONNECT The pointer to EDADRV_Disconnect.

5 EDASYM_END_TRANSACTION The pointer to EDADRV_EndTransaction.

6 EDASYM_PREPARE_STMT The pointer to EDADRV_PrepareStmt.

7 EDASYM_DROP_STMT The pointer to EDADRV_DropStmt.

8 EDASYM_EXECUTE_STMT The pointer to EDADRV_Execute.

9 EDASYM_CLOSE_STMT The pointer to EDADRV_Close.

10 EDASYM_FETCH_STMT The pointer to EDADRV_FetchStmt.

11 EDASYM_PERFORM The pointer to EDADRV_Perform.

12 EDASYM_SET_ATTRIBUTE The pointer to EDADRV_GetEDAAttr.

Driver Functions


Return Codes

The following table describes the EDADRV_LoadSymbols return codes.

EDADRV_LoadSymbols Return Codes

Return Code Error Description

0 N/A Successful.

101 EDADRV_ERR_MEMORY Internal memory allocation error.

108 EDADRV_CONFIG_NOT_EXIST edaconfig file does not exist.

109 EDADRV_OPEN_CONFIG_ERROR Could not open edaconfig file.

110 EDADRV_DB2INSTANCE_NOT_SET DB2INSTANCE in edaconfig file not set.

EDADRV_ConnectEDA calls the EDADRV_Connect funtion to connect to an external database.

13 EDASYM_GET_ERRMSG The pointer to EDADRV_GetErrmsg.

14 EDASYM_CLEANUP The pointer to EDADRV_Cleanup.

15 EDASYM_GET_DBINFO The pointer to EDADRV_GetDBInfo.

16 EDASYM_FREE_RESULT The pointer to EDADRV_FreeResult.

17 EDASYM_GETSPECIALINFO The pointer to EDADRV_GetSpecialInfo.

Array Index Array Element Value Description

Driver Functions


Syntax

RETCODE EDADRV_Connect(connhdl,datasource,login_name,password)

Input Variables

The following table describes the input variables.

EDADRV_Connect Input Variables


char * datasource The name of the data source.

char * login_name The user login name.

char * password The password corresponding to the login name.

Output Variable

The following table describes the output variable.

EDADRV_Connect Output Variable


EDA_T_CONN_HDL * connhdl The connection handle.

Description

The EDADRV_Connect function makes a connection to an external database.


Return Codes

The following table describes the EDADRV_Connect return codes.

EDADRV_Connect Return Codes


0 N/A Successful.

1 EDADRV_ERR_SYSTEM External system error.


EDADRV_DisconnectEDA calls the EDADRV_Disconnect funtion to disconnect from an external database.

Syntax

RETCODE EDADRV_Disconnect(connhdl)

Input Variable

The following table describes the input variable.

EDADRV_Disconnect Input Variable


EDA_T_CONN_HDL connhdl The connection handle.

DescriptionThe EDADRV_Disconnect function disconnects from an external database and releases the connection handle.


Return Codes

The following table describes the EDADRV_Disconnect return codes.

EDADRV_Disconnect Return Codes


0 N/A Successful.


102 EDADRV_INVALID_CONN_ID Invalid connection handle.

EDADRV_EndTransactionEDA calls the EDADRV_EndTransaction function to end a transaction on an external database.

Syntax

RETCODE EDADRV_EndTransaction(connhdl,trans_flag)

Input Variables


EDADRV_EndTransaction Input Variables



int trans_flag The action to take if the transaction ends. Valid values are:

0 – EDA_COMMIT. Commit the transaction.

1 – EDA_ROLLBACK. Rollback the transaction.


Description

The EDADRV_EndTransaction function commits or rolls back a transaction on the external database, depending on the value of trans_flag.

Return Codes

The following table describes the EDADRV_EndTransaction return codes.

EDADRV_EndTransaction Return Codes


0 N/A Successful.



114 EDADRV_INVALID_TRANS_FLAG Invalid END TRANSACTION flag.

EDADRV_PrepareStmtEDA calls the EDADRV_PrepareStmt function to prepare a statement.

Syntax

RETCODE EDADRV_PrepareStmt(connhdl,stmthdl,stmt)

Input VariablesThe following table describes the input variables.

EDADRV_PrepareStmt Input Variables



EDA_T_STMT stmt The statement content.


Output Variable


EDADRV_PrepartStmt Output Variable


EDA_T_STMT_HDL * stmthdl The statement handle.

Description

The EDADRV_PrepareStmt function prepares a statement passed to it by EDA. If the driver already has a statement handle that it can reuse, it may choose to return this preallocated handle in the stmthdl output variable, otherwise, it allocates a new statement handle and returns it in stmthdl.

If the statement is a DDL statement (statement type EDASTMT_DDL) or a DML statement, such as INSERT, UPDATE or DELETE (statement type EDASTMT_DML), or a SELECT statement (statement type EDASTMT_QUERY), the statement may contain input parameters. These parameters are designated by parameter markers (“?”). In this case, EDA supplies as many parameter descriptions as there are parameter markers.

If the statement is a stored procedure call (statement type EDASTMT_PROCEDURE), the statement may contain input, output, and input/output parameters (parameter types of EDAPARAM_IN, EDAPARAM_OUT, and EDAPARAM_INOUT). In this case, EDA supplies as many parameter descrip-tions as there are input and input/output parameters of a stored procedure.

The EDADRV_PrepareStmt function allocates an array of EDA_T_PTYPE struc-tures, converts EDA data type into the corresponding external database data type, and associates this array with the statement handle for its later use in EDADRV_ExecuteStmt.


Return Codes

The following table describes the EDADRV_PrepareStmt return codes.

EDADRV_PrepareStmt Return Codes


0 N/A Successful.




112 EDADRV_INVALID_DATATYPE Invalid data type

EDADRV_ExecuteStmtEDA calls the EDADRV_ExecuteStmt function to execute an SQL statement that has been prepared with EDA_PrepareStmt.

Syntax

RETCODE EDADRV_ExecuteStmt(stmthdl,parameters,rowcount)


EDADRV_ExecuteStmt Input Variables


EDA_T_STMT_HDL stmthdl The statement handle.

EDA_T_STRING parameters The statement parameters.


Output Variable


EDADRV_ExecuteStmt Output Variable


int * rowcount The number of the rows affected by the INSERT, UPDATE, or DELETE statement, or the number of columns in the result set, or the values of output and input/output parameters of a stored procedure.

Description

EDA provides parameter values for each input and input/output parameter. Parameter values are supplied in a string format, separated by field marks. The value of the field mark is determined by calling the EDADRV_GetADDAttr function. The EDADRV_ExecuteStmt function binds each parameter and executes a statement that has already been prepared with the EDADRV_PrepareStmt function. If the statement is INSERT, UPDATE, or DELETE (statement type EDASTMT_DML), the output variable rowcount contains the number of rows affected by the operation. If the statement is a query (statement type EDASTMT_QUERY), rowcount contains the number of columns of the result set. If the statement is a stored procedure (statement type EDASTMT_PROCEDURE), rowcount is not set.

Return CodesThe following table describes the EDADRV_ExecuteStmt return codes.


0 N/A Successful.


2 EDADRV_SYSERR_OBJ_EXIST Object already exists.


103 EDADRV_INVALID_STATEMENT_ID Invalid statement handle.

EDADRV_ExecuteStmt Return Codes


EDADRV_CloseStmtEDA calls the EDADRV_CloseStmt function to close a stateme nt..

Syntax

RETCODE EDADRV_CloseStmt(stmthdl)

Input Variable

The following table describes the input parameter.

EDADRV_CloseStmt


EDA_T_STMT_HDL stmthdl Statement handle.

DescriptionOnce a cursor is opened by the execution of the EDADRV_ExecuteStmt function, it remains open even after all the rows have been fetched. The EDADRV_CloseStmt closes any open cursors associated with the statement handle.

Warning: The result buffer allocated by the EDADRV_FetchStmt function should not be freed by this function, it can only be freed by the EDADRV_FreeResult function.

111 EDADRV_INVALID_PARAM_TYPE Invalid parameter type


113 EDADRV_TOO_MANY_OUT_PARAM Too many output parameters.


EDADRV_ExecuteStmt Return Codes (continued)


Return Codes

The following table describes the EDADRV_CloseStmt return codes.

EDADRV_CloseStmt Return Codes


0 N/A Successful.


103 EDADRV_INVALID_STMT_ID Invalid statement handle.

EDADRV_DropStmtEDA calls the EDADRV_DropStmt function to close a statement and make it unavailable.

Syntax

RETCODE EDADRV_DropStmt(stmthdl)

Input Variable

The following table describes the input parameter.

EDADRV_DropStmt


EDA_T_STMT_HDL stmthdl Statement handle.

DescriptionThe EDADRV_DropStmt function closes any open cursors associated with the statement handle and makes the SQL statement unavailabe for any future use.

Warning: The result buffer allocated by the EDADRV_FetchStmt function should not be freed by this function, it can only be freed by the EDADRV_FreeResult function.


Return Codes

The following table describes the EDADRV_DropStmt return codes.

EDADRV_DropStmt Return Codes


0 N/A Successful.


103 EDADRV_INVALID_STMT_ID Invalid statement handle.

EDADRV_FetchStmtEDA calls the EDADRV_FetchStmt function to fetch rows from an open cursor.

Syntax

RETCODE EDADRV_FetchStmt(stmthdl,direction,numrows,rowsfetched, result)

Input Variables


EDADRV_FetchStmt Input Variables

Type Variable Description

EDA_T_STMT_HDL stmthdl The statement handle.

int direction The fetch direction. Valid values are:0 – Fetch Forward

int numrows The number of rows to fetch.


Output Variables


EDADRV_FetchStmt Output Variables


int * rowsfetched The number of the row retrieved.

EDA_T_RESULT * result The result string.

Description

The EDADRV_FetchStmt function fetches numrows rows from an open cursor. Currently, EDA only uses forward scrolling. EDA expects the result set to be returned in a string format. The rows of the result are separated with record marks (EDADRV_ATTR_RM) and column values within each row separated with the NULL character (“\0”).

In order to hold the result set, the EDADRV_FetchStmt function allocates a buffer. This buffer can only be freed by the EDADRV_FreeResult function.

Return Codes

The following table describes the EDADRV_FetchStmt return codes.

EDADRV_FetchStmt Return Codes


0 N/A Successful.



103 EDADRV_INVALID_STMT_ID Invalid cursor handle.

104 EDADRV_INVALID_FETCH_DIR Invalid fetch direction.


EDADRV_PerformEDA calls the EDADRV_Perform function to execute a statement directly on the external database.

Syntax

RETCODE EDADRV_Perform(connhdl,stmt,numrows,result)

Input Variables


EDADRV_Perform Input Variables



EDA_T_STMT stmt The statement content.

Output Variables


EDADRV_Perform Output Parameters

Type Variable Descripton

int * numrows The number of rows retrieved or affected.

EDA_T_RESULT * result The result string.

Description

The EDADRV_Perform function combines the processing of the EDADRV_PrepareStmt and the EDADRV_Execute functions, and if the statement is a query, it also fetches the entire result set as in EDADRV_FetchStmt. See the above functions for a description of the processing performed by the EDADRV_Perform function. The driver designer may choose to either Prepare and Execute or Execute Direct on the external database side.


Return Codes

The following table describes the EDADRV_Perform return codes.

EDADRV_Perform Return Codes


0 N/A Successful.


2 EDADRV_SYSERR_OBJ_EXIST Object already exists.



106 EDADRV_TOO_MANY_DATA Too much data fetched.


113 EDADRV_TOO_MANY_OUT_PARAM Too many output parameters.

EDADRV_GetEDAAttrEDA calls the EDADRV_GetEDAAttr function to communicate an EDA attribute value to the driver.

Syntax

RETCODE EDADRV_GetEDAAttr(attribute_type,value)


EDADRV_SetParam Input Variables


int attribute_type The name of the EDA driver attribute.

EDA_T_SYMBOL value The value for the EDA driver attribute.


Description

The EDADRV_GetEDAAttr function receives an attribute name – value pair.

Valid values for the EDA driver attribute are:

EDADRV_GetEDAAttr Values

Type Attribute Name Description

EDADRV_T_STR EDADRV_ATTR_SYSNAME At this release, the only valid value is UniData.

EDADRV_T_STR EDADRV_ATTR_VERSION Valid values are 7.1 or 7.2.

EDADRV_T_INT EDADRV_ATTR_RM The ASCII character representing a record mark (RM), such as ^255.

EDADRV_T_INT EDADRV_ATTR_FM The ASCII character representing a field mark (FM), such as ^254.

EDADRV_T_INT EDADRV_ATTR_VM The ASCII character representing a value mark (VM), such as ^253.

EDADRV_T_INT EDADRV_ATTR_SM The ASCII character representing a subvalue mark (SM), such as ^252.

EDADRV_T_INT EDADRV_ATTR_TM The ASCII character representing a text mark (TM), such as ^251.

EDADRV_T_INT EDADRV_NULLVAL The ASCII character representing the null value.

Return CodesThe following table describes the EDADRV_GetEDAAttr return codes.

EDADRV_GetEDAAttr Codes


0 N/A Successful.

105 EDADRV_INVALID_DRV_ATTR Invalid driver attribute.


EDADRV_GetErrmsgEDA calls the EDADRV_GetErrmsg function to retrieve the last error message.

Syntax

RETCODE EDADRV_GetErrmsg(errmsg)

Output Variable


EDADRV_GetErrmsg Output Variable


EDA_T_RESULT * errmsg The error message string.

Description

If the last driver function returned an error code, EDA calls this function to retrieve the corresponding error message string. If the error is returned from the external database, the driver returns this external database error. Otherwise, the driver should generate its own error message.

Return Codes

The following table describes the EDADRV_GetErrmsg return codes.

EDADRV_GetErrmsg Return Codes


0 N/A Successful.




EDADRV_CleanupEDA calls the EDADRV_Cleanup function to release memory, external handles, and the environment.

Syntax

RETCODE EDADRV_Cleanup

Description

This is the last function that EDA calls. This function frees all allocated memory and all handles to the external database, closes all files, and frees the driver environment.

Return Codes

The following table describes the EDADRV_Cleanup return codes.

EDADRV_Cleanup Return Codes


0 N/A Successful.

EDADRV_FreeResultEDA calls the EDADRV_FreeResult function to free the buffer allocated for the result set.

SyntaxRETCODE EDADRV_FreeResult(buf)


Input Variable

The following table describes the input variable.

EDADRV_FreeResult Input Variable


EDA_T_RESULT buf The result buffer

Description

The buffer allocated by the EDADRV_FetchStmt or the EDADRV_Perform function is not freed until EDA calls the EDADRV_FreeResult function. The EDADRV_FreeResult function frees the result set buffer.

Return Codes

The following table describes the EDADRV_FreeResult return codes.

EDADRV_FreeResult Return Codes


0 N/A Successful.

EDADRV_GetDBInfoEDA calls the EDADRV_GetDBInfo function to retrieve information about the database to which the application is connected.

Syntax

RETCODE EDADRV_GetDBInfo(connhdl,infotype,dbinfo)


Input Variables


EDADRV_GetDBInfo Input Variables



int infotype The information type. Valid values are:EDADRV_DBMS_NAME – The name of the database

EDADRV_DBMS_VERSION – The database version.

EDADRV_SERVER_NAME – The name of the instance on the external database.

EDADRV_DATABASE_NAME – The name of the database.

Output Variable


EDADRV_GetDBInfo Output Variable


EDA_T_RESULT * dbinfo The database information.

DescriptionThe EDADRV_GetDBInfo function returns general information about the database to which the application is currently connected.


Return Codes

The following table describes the EDADRV_GetDBInfo return codes.

EDADRV_GetDBInfo Return Codes


0 N/A Successful.




115 EDADRV_INVALID_INFOTYPE Invalid information type.

EDADRV_GetSpecialInfoEDA calls the EDADRV_GetSpecialInfo function to retrieve special information about the database to which it is currently connected, such as rename table, rename index, and BLOB data type equivalents.

Syntax

RETCODE EDADRV_GetSpecialInfo(infotype,parameters,dbinfo)


Input Variables

The following table describes the input variables for the EDADRV_GetSpecialInfo function.

EDADRV_GetSpecialInfo Input Variables

Variable Description

infotype The information type. Valid values are:EDADRV_BLOB_FIELD – The data type for the BLOB field.

EDADRV_RENAME_TABLE – The rename table statement.

EDADRV_RENAME_INDEX – The rename index statement.

EDADRV_DRIVER_INFO – information about the EDA driver.

parameters The parameter array.

Output Variable

The following table describes the output variable for the EDADRV_GetSpecialInfo function.

EDADRV_GetSpecialInfo Input Variables


EDA_T_RESULT * dbinfo The database information.

Description

EDA calls the EDADRV_GetSpecialInfo function to retrieve special information about the database to which it is currently connected, such as rename table, rename index, and BLOB data type equivalents.

When you specify EDADRV_BLOB_FIELD as the infotype, do not specify the parameter input variable. The output parameter returns the data type for the BLOB field on the external database, followed by the separator ‘\0’ and ‘0’ or ‘1’ for precision. For example, DB2 returns ‘CLOB\01’ and SQL Server returns ‘VARCHAR(MAX)\00.’


When you specify EDADRV_RENAME_TABLE or EDADRV_RENAME_INDEX as the infotype, you must also specify both the source table or index name and the target table or index name, separated by “\0.” The output variable returns the rename table or rename index statement from the external database.

When you specify EDADRV_DRIVER_INFO as the infotype, do not specify the parameter variable. The output parameter returns EDA driver information, including the EDA driver version, the supplier of the EDA driver, the date the EDA driver was created, the EDA driver target database name, and the EDA driver target database version.

Return Codes

The following table describes the EDADRV_GetSpecialInfo return codes.

EDADRV_GetSpecialInfo Return Codes


0 N/A Successful.


115 EDADRV_INVALID_INFOTYPE Invalid information type.


ECL CommandUse the EDA.VERSION command to retrieve information about the EDA Driver.

SyntaxEDA.VERSION datasource

where datasource is the name of the external data source.

The EDA.VERSION command returns the following information:

The driver target database nameThe driver target database versionThe supplier of the driverThe version of the driverThe date the driver was created

ECL Command 1-29

EDA Driver Log FilesYou can enable logging of the EDA Driver by setting the LOGLEVEL value in the edaconfig file to 1 or 2. The edaconfig file is located in /usr/ud72/include on UNIX platforms, or $UDTHOME\include on Windows platforms.

You can set the following log levels:

1 – Logs the status of the EDA Driver API functions and the input/output parameters.2 – Logs the status of the CLI or ODBC functions and the input/output parameters.

The name of the log is EDADRV_pid, and is located in the /tmp directory on UNIX platforms, or $UDTHOME\Temp on Windows platforms.


The EDA Driver Header File#ifndef edadrv_public_H_DEFINED#define edadrv_public_H_DEFINED

/* * edadrv_public.h 7.2 Jun. 19, 2007 * * Version: 1.0 */

/* * The EDA driver symbols and prototypes: * * EDA Drivers are DLLs to deal with external databases. All drivers must * have a list symbols defined. Symbols are either data symbol or function * symbols. Data symbols represent global variables and function symbols * represent the C functions of the driver. All symbols are defined in * Driver Symbol Codes. It's allowed that some drivers do not support some * specific symbols. In this case, Any access to these symbols will * * generate a error to Upper layer. * All symbols will be loaded into Driver Dynamic Symbol Array after * driver DLL is loaded by Driver Manager through EDADRV_LOAD_SYMBOLS. * EDADRV_LOAD_SYMBOLS is a function defined in driver. It is resposible * to allocate the Driver Dynamic Symbol Array and load the symbols in * the order defined in Driver Symbol Codes. * * This header file defines the driver symbols and prototypes. All data * types of function symbols are also defined, as well as error codes it * returned. */

/***************************************************************************** * Section One: Definition of Datatypes *****************************************************************************/typedef int (* T_FUNC)();/* Datatype of function pointer *//*************** Datatype of Driver Symbols *****************/typedef struct EDA_T_SYMBOL {

intsymtype;/* Symbol type, defined below */union {

T_FUNC func;/* Pointer to driver functions */char * strparam;/* Pointer to driver string parameters */int intparam;/* Pointer to driver integer parameters */

} sym; /* The symbol */char * description;/* Description of the symbol */

} EDA_T_SYMBOL;/*********** Symbol Type Values *****************/#define EDAT_FUNC0#define EDAT_INT1#define EDAT_STRING2

/*********** Datatype of EDA String ****************/typedef struct EDA_T_STRING {

The EDA Driver Header File 1-31

int len;/* length of data content */int buflen;/* length of buffer */char * buf;/* buffer pointer */

} EDA_T_STRING;/* for data transfering between driver API */

typedef EDA_T_STRING EDA_T_RESULT;

/************ Datatype of EDA Statement *************/typedef struct EDA_T_PTYPE {

short inout;/* IN/OUT */short datatype;/* parameter datatype */

} EDA_T_PTYPE;/* define a parameter type *//************ Parameter IN/OUT **************/#define EDAPARAM_IN0/* Input parameter */#define EDAPARAM_OUT1/* Output parameter */#define EDAPARAM_INOUT2/* In/Out Parameter *//************ Parameter Types **************/#define EDAPARAM_CHAR1#define EDAPARAM_VARCHAR2#define EDAPARAM_INTEGER3#define EDAPARAM_LONG4#define EDAPARAM_SHORT5#define EDAPARAM_FLOAT6#define EDAPARAM_DOUBLE7#define EDAPARAM_DATE8#define EDAPARAM_TIME9#define EDAPARAM_TIMESTAMP10#define EDAPARAM_CLOB11#define EDAPARAM_BLOB12#define EDAPARAM_NUMERIC13#define EDAPARAM_DECIMAL14

typedef struct EDA_T_STMT {short type;/* statement type, defined below. */short flags;/* statement flags, defined below. */char * stmt;/* statement buffer, stmt is null ended */int numparam;/* number of question marks in stmt */EDA_T_PTYPE * paramdef;/* array of parameter defs */

} EDA_T_STMT;/* EDA statement definition *//********** Statement Types *************/#define EDASTMT_SQL_DDL1/* SQL DDL statement */#define EDASTMT_SQL_DML2/* SQL DML statement */#define EDASTMT_SQL_QUERY3/* SQL QUERY statement */#define EDASTMT_PROCEDURE 4/* Stored Procedure */#define EDASTMT_XQUERY5/* XQUERY statement *//********* Statement Flags ************/#define EDASTMT_TIMEOUT 0x01#define EDASTMT_SCROLLABLE0x02

/****** Definitionof Driver Connection Handle *******/typedeflong EDA_T_CONN_HDL;#define INVALID_CONN_HDL(hdl) ((hdl)<0)#define CLEAR_CONN_HDL(hdl) ((hdl)=-1)/* Clear a handle */

/*********** Definition of Driver Statement Handle **************/typedef long EDA_T_STMT_HDL;/* Positive integer */#define INVALID_STMT_HDL(hdl) ((hdl)<0)/* validation of handle */#define CLEAR_STMT_HDL(hdl) ((hdl)=-1)/* Clear handle */

/************************************************************************* * Section 2: Definition of Driver Loading API and Dynamic Symbol Array


*************************************************************************//******************** Driver Loading Function Name ****************/#define EDADRV_LoadSymbols "EDA_driver_load_symbols" /* Load driver symbol */extern int EDA_driver_load_symbols();/********************************************************************* * FUNCTION: EDADRV_LoadSymbols:Load EDA Driver Symbol Array. * DESCRIPTION: This is the function called after a driver DLL is loaded. * The driver should allocate the Driver Symbol Array and * load the driver symbols into the array according to Driver Symbol * Code. It can invoke driver initialization if needed. * CALLS BY : Driver Manager after loading the driver DLL. * Parameters * int * numsymbols; OUT: The number of symbols returned. * EDA_T_SYMBOL *symbols;OUT:The Driver Symbol Array pointer. * RETURN : int * 0: Succeeded; * errcode if failed. * GLOBAL : *********************************************************************/

#defineEDA_SYMBOL_NUM17/************************** Driver Symbol Codes ************************/#define EDASYM_DBTYPE0/* Integer: Driver Data Type code */#define EDASYM_DBFAMILY1/* Integer: Driver DBMS Family code */#define EDASYM_VERSION2/* String: the version string */#define EDASYM_CONNECT3/* Function: Make Connection */#define EDASYM_DISCONNECT4/* Function: Disconnect */#define EDASYM_END_TRANSACTION5/* Function: End Transaction */#define EDASYM_PREPARE_STMT6/* Function: Prepara Statement */#define EDASYM_DROP_STMT7/* Function: Drop Statement */#define EDASYM_EXECUTE_STMT8/* Function: Execute Statement */#define EDASYM_CLOSE_STMT9/* Function: Close Statment */#define EDASYM_FETCH_STMT10/* Function: Fetch Statement */#define EDASYM_PERFORM11/* Function: Perform a command */#define EDASYM_GET_EDA_ATTR12/* Function: Get EDA attribute */#define EDASYM_GET_ERRMSG13/* Function: Get last error message */#define EDASYM_CLEANUP14/* Function: Cleanup the driver */#define EDASYM_GET_DBINFO15/* Function: Get external DB info */#define EDASYM_FREE_RESULT16/* Function: Free result buffer */#define EDASYM_GET_SPECIALINFO17/* Function: Get special info */

/*********** EDASYM_DBTYPE Code: Driver Data Type ************/#define EDA_UNKNOW 0#define EDA_1NF 1/* Relational Database */#define EDA_NF2 2/* Multi-valued Database */#define EDA_XML 3/* XML Database */#define EDA_OBJ 4/* Object Database */

/*********** EDASYM_DBFAMILY Code: Driver DBMS Family **********/#define DBMS_OTHERS0/* Other DBMS */#define DBMS_DB21/* DB2 family */#define DBMS_ORACLE2/* Oracle family */#define DBMS_MSSQL3/* Microsoft SQL Server family */#define DBMS_U24/* IBM U2 family */

/************************************************************************** * Section 3: Definition of EDA API Functions


**************************************************************************//********************************************************************* * FUNCTION SYMBOL: EDASYM_CONNECT * FUNCTION : EDADRV_Connect: Make connection to external database. * DESCRIPTION: * CALLS BY : Connetion Manager per request. * PARAMETERS : * EDA_T_CONN_HDL * connhdl;OUT: The connection handle. * char * datasource;IN: The datasource name. * char * loginname;IN: login user name. * char * password;IN: login password. * RETURN : * 0: Succeeded; * errcode if failed. * GLOBAL : *********************************************************************/

/********************************************************************* * FUNCTION SYMBOL: EDASYM_DISCONNECT * FUNCTION : EDADRV_Disconnect: Disconnect a connection. * DESCRIPTION: * CALLS BY : Connetion Manager per request. * PARAMETERS : * EDA_T_CONN_HDL connhdl;IN: the connection handle. * RETURN : * 0: Succeeded; * errcode if failed. * GLOBAL : *********************************************************************/

/********************************************************************* * FUNCTION SYMBOL: EDASYM_END_TRANSACTION * FUNCTION : EDADRV_EndTransaction, Ending a transaction on a * connection. * DESCRIPTION: Either Commit or Rollback a transaction. * CALLS BY : Transaction Control Module. * PARAMETERS : * EDA_T_CONN_HDL connhdl;IN: the connection handle * int trans_flag;IN: Commit or Rollback. * RETURN : * 0: Succeeded; * errcode if failed. * GLOBAL : *********************************************************************//********* Transaction flag for EDADRV_EndTransaction *********/#define EDA_COMMIT0#define EDA_ROLLBACK1

/********************************************************************* * FUNCTION SYMBOL: EDASYM_PREPARE_STMT * FUNCTION : EDADRV_PrepareStmt: Prepare a statement. * DESCRIPTION: Driver create a statement by given connection handle * and a statement string. Statement string may include Question Marks * for later parameter input. A list of parameter types is specified for * later execution. The number of auguments must match the number of * Question Marks, otherwise it will cause errors in the execution. * If the prepared statement is a stored procedure, the values of input


* parameters will be passed in by EDASYM_ExecuteStmt, and the results * of output parameters will be passed out by EDASYM_FetchStmt. * NOTE: Driver can use a pre-allocated handle to prepare the * statement; or allocate a new handle every time according to its * implementation. * CALLS BY : Transaction Control Module. * PARAMETERS : * EDA_T_CONN_HDL connhdl;IN: connection handle. * EDA_T_STMT_HDL *stmthdl;OUT: the statement handle. * EDA_T_STMT stmt;IN: the statement content. * RETURN : * 0: Succeeded; * errcode if failed. * GLOBAL : *********************************************************************/

/********************************************************************* * FUNCTION SYMBOL: EDASYM_EXECUTE_STMT * FUNCTION : EDADRV_ExecuteStmt: * DESCRIPTION: EDADRV_ExecuteStmt open the execution of a statement * by given parameters. The statement must have been prepared and the * number and types of parameters given here must match those in * preparing. Parameters are separated by FM. If the statement handle is * still open, EDADRV_ExecuteStmt will close the old one and re-open it * with the given parameters. * CALLS BY : Transaction Control Module * PARAMETERS : * EDA_T_STMT_HDL stmthdl;IN: Statement handle * EDA_T_STRING parameters;IN: Statement parameters * int*rowcount;OUT: number of row affected * RETURN : * 0: Succeeded; * errcode if failed. * GLOBAL : *********************************************************************/

/********************************************************************* * FUNCTION SYMBOL: EDASYM_CLOSE_STMT * FUNCTION: EDADRV_CloseStmt:Close the execution of a statement. * DESCRIPTION: A statement is opened after calling EDADRV_ExecuteStmt * and will keep opening even though all rows has been fetched by * EDADRV_FetchStmt. EDADRV_CloseStmt close the execution of the * statement. * CALLS BY : Transaction Control Module * PARAMETERS : * EDA_T_STMT_HDL stmthdl; IN: the statement handler * RETURN : * 0: Succeeded; * errcode if failed. * GLOBAL : *********************************************************************/

/********************************************************************* * FUNCTION SYMBOL: EDASYM_DROP_STMT * FUNCTION : EDADRV_DropStmt: Drop a statement. * DESCRIPTION: EDADRV_DropStmt drop a statement and make it unavailable. * If a statement is opened EDADRV_DropStmt will close it before * dropping it. * CALLS BY : Transaction Control Module * PARAMETERS : * EDA_T_STMT_HDL stmthdl; IN: the statement handler


* RETURN : * 0: Succeeded; * errcode if failed. * GLOBAL : *********************************************************************/

/********************************************************************* * FUNCTION SYMBOL: EDASYM_FETCH_STMT * FUNCTION : EDADRV_FetchStmt: Fetch an open statement * DESCRIPTION: EDA always treat driver statement as scrollable cursor. * The format of result differs on the driver's data type: * EDA_1NF: Result is rows returned by SQL statement. Columns * are separated by '\0' and rows are separated by RM. * EDA_XML: Result is XML document. * EDA_NF2: Result is multi-valued records separated by RM. * EDA_OBJ: Result is self-defined. * CALLS BY : Transaction Control Module * PARAMETERS : * EDA_T_STMT_HDL stmthdl;IN: statement handle. * int direction;IN: fetch direction. * int numrows;IN: number of rows to fetch. * int *rowsfetched;OUT: number of rows fetched. * EDA_T_RESULT *result;OUT: the result string. * RETURN : * 0: Succeeded; * errcode if failed. * GLOBAL : *********************************************************************//************* Fetch Direction ************/#define EDA_FETCH_FORWARD0#define EDA_FETCH_BACKWARD1#define EDA_FETCH_FIRST2#define EDA_FETCH_LAST3

/********************************************************************* * FUNCTION SYMBOL: EDASYM_PERFORM * FUNCTION : EDADRV_Perform: Perform a statement directly onto * external DBMS. * DESCRIPTION: The statement could be a DDL, DML or SQL query without * question marks. If the statement is a stored precedure, the question * marks in the statements must represent output parameters. * If the statement has result returned, the format of returned * result is same as those defined in EDA_FetchStmt. * CALLS BY : Transaction Control Module * PARAMETERS : * EDA_T_CONN_HDL connhdl;IN: connection handle. * EDA_T_STMT stmt;IN: statement content. * int *numrows;OUT: number of rows fetched or affected. * EDA_T_RESULT *result;OUT: the result string. * RETURN : * 0: Succeeded; * errcode if failed. * GLOBAL : *********************************************************************/

/********************************************************************* * FUNCTION SYMBOL: EDASYM_GET_EDA_ATTR


* FUNCTION : EDADRV_GetEDAAttr: Get attribute from EDA engine. * DESCRIPTION: Get attribute from U2 EDA engine. * CALLED BY: Driver Manager * PARAMETERS : * int attrname;IN: driver attribute name,defined below * EDA_T_SYMBOL value;IN: driver attribute value. * RETURN : * 0: Succeeded; * errcode if failed. * GLOBAL : *********************************************************************//************* Driver Attribute Names ************/#define EDADRV_ATTR_SYSNAME1/* EDADRV_T_STR: UniData or UniVerse*/#define EDADRV_ATTR_VERSION2/* EDADRV_T_STR: U2 Version string */#define EDADRV_ATTR_RM3/* EDADRV_T_INT: U_RM */#define EDADRV_ATTR_FM4/* EDADRV_T_INT: U_FM */#define EDADRV_ATTR_VM5/* EDADRV_T_INT: U_VM */#define EDADRV_ATTR_SM6/* EDADRV_T_INT: U_SM */#define EDADRV_ATTR_TM7/* EDADRV_T_INT: U_TM */#define EDADRV_ATTR_NULLVAL8/* EDADRV_T_INT: U_NULLVAL *//* More to be defined */

/********************************************************************* * FUNCTION SYMBOL: EDASYM_GET_ERRMSG * FUNCTION : EDADRV_GetErrmsg: Get last error message string. * DESCRIPTION: if error code returned from a driver API, the calling * module can call this function to get the detailed error message. * If the error reported from external DBMS, the driver will return the * system error message; Otherwise, driver should generate it's own error * message. * PARAMETERS : * EDA_T_RESULT * errmsg;OUT: Error message string. * RETURN : * 0: Succeeded; * errcode if failed. * GLOBAL : *********************************************************************/

/********************************************************************* * FUNCTION SYMBOL: EDASYM_CLEANUP * FUNCTION : EDADRV_Cleanup: Cleanup the driver. * DESCRIPTION: Driver should free all allocated memory segement and all * handlers to external DBMS client; close all opened files and * cleanup driver environment. * PARAMETERS : * RETURN : * 0: Succeeded; * errcode if failed. * GLOBAL : *********************************************************************/

/********************************************************************* * FUNCTION SYMBOL: EDASYM_FREE_RESULT * FUNCTION : EDADRV_FreeResult: Free memory space allocated by driver. * DESCRIPTION: Driver should free memory allocated by itself. * PARAMETERS : * EDA_T_RESULT buf;IN: the result buffer * RETURN : * 0: Succeeded; * errcode if failed.


* GLOBAL : *********************************************************************/

/********************************************************************* * FUNCTION SYMBOL: EDASYM_GET_DBINFO * FUNCTION : EDADRV_GetDBInfo: Get database information. * DESCRIPTION: Get general information about the DBMS taht the * application is currently connected to. * CALLED BY: Driver Manager * PARAMETERS : * EDA_T_CONN_HDL connhdl;IN: connection handle. * intinfotype;IN: information type * EDA_T_RESULT *dbinfo;OUT: the DB info. * RETURN : * 0: Succeeded; * errcode if failed. * GLOBAL : *********************************************************************//************* Infotypes in EDADRV_GetDBInfo ************/#define EDADRV_DBMS_NAME1/* DBMS name */#define EDADRV_DBMS_VERSION2/* DBMS version */#define EDADRV_SERVER_NAME3/* DB2 instance */#define EDADRV_DATABASE_NAME4/* Database name */

/********************************************************************* * FUNCTION SYMBOL: EDASYM_GET_SPECIALINFO * FUNCTION : EDADRV_GetSpecialInfo: Get special information * for external database or driver. * DESCRIPTION : Get special information about the DBMS that the * application is currently connected to, like rename * table, rename index, blob data type. Also get the * information for this driver. * CALLED BY : Driver Manager * PARAMETERS : * int infotype; IN: information type * EDA_T_STRING parameters; IN: paramerter array * EDA_T_RESULT *spinfo; OUT: the special info. * RETURN : * 0: Succeeded; * errcode if failed. * GLOBAL : *********************************************************************//************* Infotypes in EDADRV_GetSpecialInfo ************/#defineEDADRV_BLOB_FIELD1/* data type for BLOB field */#defineEDADRV_RENAME_TABLE2/* get rename table statement */#defineEDADRV_RENAME_INDEX3/* get rename index statement */#defineEDADRV_DRIVER_INFO4/* EDA driver info. *//* More to be defined */

/*********************** Driver Error Codes *************************/#define EDADRV_ERR_SYSTEM1/* General External system error */#define EDADRV_SYSERR_OBJ_EXIST2/* Object existing */#define EDADRV_ERR_MEMORY101/* Internal memory allocation error */#define EDADRV_INVALID_CONN_ID102/* Invalid connection handle */#define EDADRV_INVALID_STMT_ID103/* Invalid statement handle */#define EDADRV_INVALID_FETCH_DIR 104/* Invalid fetch direction */#define EDADRV_INVALID_EDA_ATTR105/* Invalid EDA attribute */#define EDADRV_TOO_MANY_DATA106/* Too many data fetched */#define EDADRV_GET_UDTHOME_ERROR 107/* Get UDTHOME error */#define EDADRV_CONFIG_NOT_EXIST 108/* edaconfig file not exist */#define EDADRV_OPEN_CONFIG_ERROR 109/* Open edaconfig error */


#define EDADRV_DB2INSTANCE_NOT_SET 110/* DB2INSTANCE not set */#defineEDADRV_INVALID_PARAM_TYPE 111/* Invalid parameter type */#defineEDADRV_INVALID_DATATYPE 112/* Invalid data type */#defineEDADRV_TOO_MANY_OUT_PARAM 113/* Too many output parameters */#define EDADRV_INVALID_TRANS_FLAG 114/* Invalid end transaction flag */#define EDADRV_INVALID_INFOTYPE 115/* Invalid information type *//* More to be defined */

#endif


2Chapter

Pluggable Authentication Module (PAM)

Pluggable Authentication Module (PAM) . . . . . . . . . . . 2-2 How UniData Authentication Currently Works . . . . . . . . 2-2 PAM Support . . . . . . . . . . . . . . . . . . 2-2

Pluggable Authentication Module (PAM) 2-2

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 UniData Authentication Currently WorksCurrently, UniData 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, UniData authenticates the user and grants access to the system. If the passwords do not match the user’s request is rejected.

PAM SupportUniData 7.2 supports the PAM framework for the following products:

UniObjectsUniObjects for JavaUniObjects for .NETInterCallIBM JDBC Driver for UniData and UniVerseUniData ODBCUniOLEDB

UniData will not access LDAP servers directly from any of its servers, and will not support single sign-on. UniData 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, UniData will first try to authen-ticate the user using the traditional UNIX method. If that attempt fails, UniData will call PAM to check the validity of the user. If both attempts fail, the connection is denied.

3Chapter

Automatic Data Encryption

Encrypted File Types . . . . . . . . . . . . . . . . 3-2 Encryption With UniData Data Replication . . . . . . . . . 3-2Key Store . . . . . . . . . . . . . . . . . . . . . 3-3How Encryption Works. . . . . . . . . . . . . . . . . 3-4Defining a Master Key . . . . . . . . . . . . . . . . . 3-6 Changing a Master Key After Data is Encrypted . . . . . . . 3-7Using Encryption Wallets . . . . . . . . . . . . . . . . 3-8 Wallet ECL Commands . . . . . . . . . . . . . . . 3-8UniData Encryption Algorithms . . . . . . . . . . . . . . 3-10Changes to UniData Utilities . . . . . . . . . . . . . . . 3-11 convmark. . . . . . . . . . . . . . . . . . . . 3-11 udtlangconfig . . . . . . . . . . . . . . . . . . 3-11 dumpgroup . . . . . . . . . . . . . . . . . . . 3-12 fixgroup . . . . . . . . . . . . . . . . . . . . 3-12 fixfile . . . . . . . . . . . . . . . . . . . . . 3-12 guide . . . . . . . . . . . . . . . . . . . . . 3-12 newacct . . . . . . . . . . . . . . . . . . . . 3-12 shfbuild . . . . . . . . . . . . . . . . . . . . 3-13Encryption Commands . . . . . . . . . . . . . . . . . 3-14 CREATE.ENCRYPTION.KEY . . . . . . . . . . . . . 3-14 DELETE.ENCRYPTION.KEY . . . . . . . . . . . . . 3-14 LIST.ENCRYPTION.KEY . . . . . . . . . . . . . . 3-15 GRANT.ENCRYPTION.KEY . . . . . . . . . . . . . 3-15 REVOKE.ENCRYPTION.KEY . . . . . . . . . . . . 3-16 ENCRYPT.FILE . . . . . . . . . . . . . . . . . 3-17 DECRYPT.FILE . . . . . . . . . . . . . . . . . 3-18 LIST.ENCRYPTION.FILE . . . . . . . . . . . . . . 3-20

ACTIVATE.ENCRYPTION.KEY. . . . . . . . . . . . . 3-20 DEACTIVATE.ENCRYPTION.KEY . . . . . . . . . . . 3-21 DISABLE.DECRYPTION . . . . . . . . . . . . . . . 3-22 ENABLE.DECRYPTION . . . . . . . . . . . . . . . 3-23UniBasic Encryption Commands . . . . . . . . . . . . . . 3-24 ACTIVATEKEY . . . . . . . . . . . . . . . . . . 3-24 DEACTIVATEKEY . . . . . . . . . . . . . . . . . 3-25 DISABLEDEC . . . . . . . . . . . . . . . . . . 3-27 ENABLEDEC . . . . . . . . . . . . . . . . . . . 3-28 STATUS Function Changes. . . . . . . . . . . . . . . 3-29 FILEINFO() Function Changes . . . . . . . . . . . . . 3-30The encman Utility. . . . . . . . . . . . . . . . . . . 3-31 Viewing Audit Trail Information . . . . . . . . . . . . . 3-31 Generating a Key Store . . . . . . . . . . . . . . . . 3-32 Removing a Key Store . . . . . . . . . . . . . . . . 3-33 Importing and Exporting Metadata . . . . . . . . . . . . 3-33Installation Changes . . . . . . . . . . . . . . . . . . 3-36 New Installations . . . . . . . . . . . . . . . . . . 3-36 Upgrade Installation . . . . . . . . . . . . . . . . . 3-36

3-2

At this release, automatic data encryption is introduced. With this feature, you can encrypt specified fields or entire records, and UniData automatically decrypts the data when accessed by UniData or UniBasic commands. This enhancement includes the following features:

Define which fields in the UniData file to encryptAutomatically encrypt the data you specify when writing the record to the UniData fileAutomatically decrypt the data you specify when reading the record from the UniData fileKey management supportAudit trail for operations on keys and encrypted filesSupport of 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, UniData only encrypts hashed data files. UniData does not encrypt directory files, system log files, dictionary files, or system temporary files.

Encryption With UniData Data ReplicationIf you are using UniData Data Replication, care must be taken when adding automatic data encryption. If a file that is encrypted is also being replicated, UniData transfers the 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 may not be synchronized with the source data and will not be usable when failover is required.

3-2UniData 7.2 New Features

Key StoreThe most important part of an encrypted system is key management. To ensure a fully secure system, UniData 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 UniData key store is protected by a master key. This master key is known only to UniData, and is also used to derive all other keys. After you install UniData, you should define a master key, either providing one of your own, using a UniData-generated random key, or using the UniData default.

UniData stores the master key and loads it into memory each time UniData starts.

Key Store 3-3

How Encryption WorksThis section gives an overview of how encryption works on a UniData database.

After installing UniData, you define a master key. You can define your own master key, use a UniData-generated master key, or use a UniData default. IBM recommends that you define your own master key or use a UniData-generated master key. UniData uses the master key in all operations related to 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 just a field or fields in the record. UniData 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 UniData read or write operation, either from UniBasic, UniQuery, or UniData SQL, UniData 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 UniBasic ACTIVATEKEY statement.

For UniQuery, if the encryption key is not active, UniData still returns and displays cipher text data. For UniBasic, if the encryption key is not active and decryption is not disabled, UniData sets an error STATUS and does not return any data. For UniData SQL, if the encryption key is not active and decryption is not disabled, UniData SQL does not return any records from the file.

If the operation you specify is a read operation and the key is not active, UniData returns an error in the UniBasic STATUS command, then presents no data. However, if you disable encryption through the DISABLE.DECRYPTION command, UniData does not attempt to decrypt the 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 choose a site-specific master key (one you define or one that UniData generates), the encrypted data can only be decrypted on the installed system.

If you choose to use the UniData default master key, and you move the encrypted data and key store to another UniData 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 the 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 UniData system with default master key and encryption key.

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

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

Strong Protection. Data can be accessed on another UniData 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 UniData system with the same user-defined master key and the same encryption key and password if the system is set up.

How Encryption Works 3-5

Defining a Master KeyUniData Data Encryption requires that you set a master key before it runs. Use the confcmd 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\ud72>confcmd [-m new_master_key [-f] [-o file]] [-t source,target]

Warning: changing the Master Key will render your current encrypteddata inaccessible. If you already have encrypted data, exit thisutility and complete the following steps:

1. Decrypt your data 2. Execute encman to remove key store 3. Shutdown UniData RDBMS 4. Execute confprod_cmdln to change the Master Key 5. Restart UniData RDBMS 6. Execute encman to re-create key store 7. Reencrypt your data

Do you want to continue [Yes/No - Default: No]?

There are three types of master keys:

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

If the master key was previously defined, the confcmd 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, UniData 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 following 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, UniData stores the key in the mygenkey file in the directory where you executed confcmd.

We recommend 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.

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 UniData data encryption involve 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 34.

Defining a Master Key 3-7

Using Encryption WalletsYou can create an encryption key wallet, which contains encryption keys and passwords. Instead of activating encrypt keys individually, you can supply a wallet and its corresponding password to UniData to activate all the encryption keys contained in the wallet. UniData stores the wallet in the key store.

Client applications can use the encryption key wallet to activate keys for the entire session. Call the ACTIVATE_WALLET() and DEACTIVATE_WALLET() subrou-tines 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

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 UniData, 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 subroutine method of a session object.

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

Wallet ECL CommandsThe following ECL 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 <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.KEYcommand 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 UniBasic ACTIVATEKEY and DEACTIVEKEY statements also accept <wallet_id> and <wallet_password>.

Using Encryption Wallets 3-9

UniData Encryption AlgorithmsUniData 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 UniData 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.


Changes to UniData UtilitiesThis section discusses changes to UniData utilities to accommodate data encryption.

convmarkComplete the following steps to convert an account containing encrypted files to another language group.

1. Back up UniData system files contained in $UDTHOME/sys.2. Manually convert encrypted files that were encrypted using the

WHOLERECORD option or contain at least one multivalued or multi-subvalued encrypted field. If a file contains only singlevalued encrypted fields, you do not need to decrypt it.

3. Decrypt files.4. Execute the convmark command on the file.5. Execute the udtlangconfig command. This command automatically

converts the system keystore files (_KEYSTORE_ and _ENCINFO_) located in the $UDTHOME/sys directory, as well as other files.

6. Restart UniData.7. Encrypt files decrypted in previous steps.

udtlangconfigPrior to UniData 7.2, UniData had to be shut down before executing the udtlang-config utility. To support data encryption, UniData must be running when you execute udtlangconfig. UniData converts the _KEYSTORE_ and _ENCINFO_ files, shuts down UniData, converts the remainder of the files, then restarts UniData. If udtlangconfig encounters an encrypted file that contains multivalued encrypted fields, it displays a warning message and skips the file. You will hjave to convert the file manuallu by running UniData in the old language group and using the precon-version keystore files, as described in convmark.

Changes to UniData Utilities 3-11

dumpgroupWhen handling an encrypted file, the following actions occur:

If the file was encrypted with the WHOLERECORD option, UniData does not convert any marks. The record is dumped to a file exactly as it is stored in the UniData file.You must have root or Administrator privilege for the _KEYSTORE_ or _ENCINFO_ files.UniData does not decrypt the dumped record.

fixgroupWhen handling an encrypted file, the following actions occur:

If the file was encrypted with the WHOLERECORD option, UniData does not convert any marks. The record is written to a UnData file exactly as it is stored in the temporary file.You must have root or Administrator privilege for the _KEYSTORE_ or _ENCINFO_ files.UniData does not decrypt records written to the UniData file.

fixfileHas the same behavior as dumpgroup and fixgroup.

guideguide now reports that a file is encrypted if it encounters an encrypted file.

newacctUniData creates file pointers in the VOC file for _KEYSTORE_ and _ENCINFO_.


shfbuildIf you supply an encrypted file as the source file. shfbuild copies the encryption infor-mation from the source file to the target file, and creates an entry in the _ENCINFO_ file. UniData copies the data directly into the target file in ciphertext.

Changes to UniData Utilities 3-13

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

Example

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

:CREATE.ENCRYPTION.KEY test myunidataCreate encryption key test 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]


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.

Example

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

:DELETE.ENCRYPTION.KEY test myunidataWould you like to remove this encryption key? (Y/N)YRemove encryption key test 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 UniQuery commands, such as LIST, LIST.ITEM, SORT, SORT.ITEM, and so forth.

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

Encryption Commands 3-15

Example

The following example illustrates output from the LIST.ENCRYPTION.KEY command:

:LIST.ENCRYPTION.KEY

LIST _KEYSTORE_ CREATOR DATE TIME GRANTEES FILES FIELDS WITH TYPE=1 15:23:13 May 12 2008 1_KEYSTORE_ test1CREATOR c1aireadayDATE 04/09/2008TIME 04:04PMGRANTEES PUBLICFILES FIELDS

_KEYSTORE_ testCREATOR c1aireadayDATE 05/12/2008TIME 03:23PMGRANTEESFILES FIELDS

2 records listed

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.

SyntaxGRANT.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, UniData 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.

ExampleThe following example illustrates granting PUBLIC access to the “test” encryption key:

:GRANT.ENCRYPTION.KEY test myunidata 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...}}

Parameters


GRANT.ENCRYPTION.KEY Parameters


key.id The encryption key.

password The password for the encryption key.

PUBLIC Revokes 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, UniData revokes access to all users belonging to the group.Grantees cannot revoke access to the encryption key to other users.

Example

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

:REVOKE.ENCRYPTION.KEY test myunidata PUBLICREVOKE.ENCRYPTION.KEY to PUBLIC successful.

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

Note: You cannot encrypt an index file.


Syntax

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

ENCRYPT.FILE accepts all parameters of the memresize command. If the file you are encrypting is empty, you do not need to specify any of the memresize 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 memresize parameters.

Parameters

The following table describes each parameters of the syntax.

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, UniData 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 “UniData Encryption Algorithms” on page 10 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, UniData 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.

Example

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

:ENCRYPT.FILE CUSTOMER WHOLERECORD,aes128,test,myunidataThe temporary file for ENCRYPT.FILE is C:\IBM\ud72\Demo\rsztpa04076.29 record(s) in file.Encrypt CUSTOMER successfully.Total time used = 0 (sec)

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

Syntax

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

Parameters

DECRYPT.FILE accepts all memresize command parameters. If the file you are decrypting is empty, you do not need to specify any of the memresize 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 memresize 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, UniData 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 ENCRYPT.FILE.

ExampleThe following example illustrates decrypting a file that was originally encrypted with the WHOLERECORD option:

:DECRYPT.FILE CUSTOMER WHOLERECORD,test,myunidataThe temporary file for DECRYPT.FILE is C:\IBM\ud72\Demo\rsztpa05492.29 record(s) in file.Decrypt CUSTOMER successfully.Total time used = 0 (sec)



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

Example

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

LIST.ENCRYPTION.FILE CUSTOMERWhole-record encryption, algorithm aes128, key test.

ACTIVATE.ENCRYPTION.KEYUse the ACTIVATE.ENCRYPTION.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.ENCRYPTION.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, UniData deactivates all keys in the wallet.


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.

Example

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

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

ENABLE.DECRYPTIONUse the ENABLE.DECRYPTION command to turn on 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.

field_list 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 file:

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


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

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

Syntax

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

Parameters



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

ACTIVATEKEY Parameters


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

Example

The following example illustrates how to activate an encryption key:

ACTIVATEKEY "test","myunidata" ON ERROR PRINT "Unable to activate key"

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 <NFA_SERVER>] [ON ERROR <statements>]


ON NFA_SERVER The name of the NFA_SERVER on which you want to activate the encryption key. The syntax for NFA_SERVER can be either:

@domain.var where domain.var specifies the ID for a VOC entry that contains the NFA server connection parameters.

OR“MACHINE <host> PORT <port> [, UDTHOME <udthome>]”

NFA files are always encrypted and decrypted on the remote machine by the NFA server.

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


ACTIVATEKEY Parameters (continued)

UniBasic Encryption Commands 3-27

Parameters


DEACTIVATEKEY Parameters


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


ON NFA_SERVER The name of the NFA_SERVER on which you want to deactivate the encryption key. The syntax for NFA_SERVER can be either:

@domain.var where domain.var specifies the ID for a VOC entry that contains the NFA server connection parameters.

OR“MACHINE <host> PORT <port> [, UDTHOME <udthome>]”

NFA files are always encrypted and decrypted on the remote machine by the NFA server.


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:

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 "test","myunidata" 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>], <field_list> [ON ERROR <statements>]


Parameters


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


STATUS Codes

DISABLEDEC has the following STATUS codes:

DISABLEDEC STATUS Codes

STATUS Code Description

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","NAME,PHONE" ON ERROR PRINT "Unable to disable decryption”

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

CUST="CUSTOMER"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>], <field_list> [ON ERROR <statements>]

Parameters


ENABLEDEC Parameters


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

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



STATUS Codes

ENABLEDEC has the following STATUS codes:

ENABLEDEC STATUS Codes

STATUS Code Description

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 file

6 Cannot locate information to disable encryption

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","NAME,PHONE" ON ERROR PRINT "Unable to enable decryption

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

CUST="CUSTOMER"FIELDS="NAME,PHONE"ENABLEDEC CUST,FIELDS ON ERROR PRINT "Unable to enable decryption"

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

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


For UniBasic WRITE statements, STATUS() returns -9 to indicate that an encryption error occurred during the WRITE operation.

FILEINFO() Function ChangesTwo new values have been added to the FILEINFO() function to obtain encryption information:

Code Value 27 – Returns 1 if the file is encrypted, 0 if the file is not encrypted.Code Value 28 – If the file is encrypted, UniData 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:<location>@SM<key-id>@SM<algorithm>@SM<field_name>If the file is not encrypted, UniData returns an empty string.


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. Run the command from the UniData home directory.

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 – Deletesencryption key

GRANT – Grantskey access

REVOKE – Revokes key access

ACTIVATE – Activates encryption key

DEACTIVT – Deactivatesencryption key

ENABLE – Enables encryption key

DISABLE – Disables encryption key

ENCRYPT – Encrypts a file

DECRYPT – Decrypts a file

RMKEYST – Removes a 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 filename Displays the audit trail date from the filename you specify.–

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


encman -audit Parameters (continued)

The encman Utility 3-35

Syntax

encman [[-genkeystore] [-n]]

Parameters


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

Parameters


encman -delkeystore Parameters


-f Remove key store without confirmation.

-a Remove 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 kay> 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 “@”, UniData treats the rest of the string as the name of the file that contains the master key. If <master key> is the literal string “SYSTEM”, UniData uses the current system master key as the system default. If <master key> or <password> contain spaces or other nonalphanumeric characters, you must place <master key> or <password> in quotation marks.

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

encman -import <master key> [<password>] {chown <owner>,<newowner> {<owner>,<newowner>} | -chpath <path>,<new-path> {<path>,<newpath>}} <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.

The encman Utility 3-37

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. UniData 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:

/usr1/dis1/acct1/FILEA


Installation ChangesThis section describes the changes to the UniData 7.2 installation process.

New InstallationsUniData does not automatically install a master key. At the end of the installation process, a message appears advising you to create the default master key, as shown in the following example.

There are three types of master keys:

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

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

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 confcmd command.

Installation Changes 3-39

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

The source license file is from UniData 7.1 or earlierThe source license file is not authorizedThe source license file or target license file is for the UniData Personal EditionThe master key is not set up in the current license fileThe source or target license file 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 confcmd command:

C:\IBM\ud72>confcmd [-m new_master_key [-f] [-o file]] [-t source,target]

UniData stores the master key in the product.info license file. You specify the source directory where the old license file resides (usually $UDTBIN), and the target directory where the new license file resides (usually $UDTBIN). The confcmd command then transfers the current master key into the new license 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 UniData Data Encrypt Configure dialog box appears, as shown in the following example:

Using UniAdmin for Encryption 3-41

Adding an Encryption KeyTo create an 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.


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.

To grant privileges to groups, enter the group ID in the Enter Groups check box. Separate each group ID with a comma.\

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

To showglobal 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.

Note: You can only revoke privileges from Public on Windows platforms.


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

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


Viewing Encryption Wallet DetailsTo view details about an 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 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 Passwordbox.

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.


Granting Privileges to Encryption WalletTo grant privileges to the encryption wallet to a user or group, click Grant. The Grant Encryption wallet 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.

To grant privileges to groups, enter the group ID in the Enter Groups check box. Separate each group ID with a comma.

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

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

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


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

Encrypting an Entire RecordDefine 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 memresize parameters to use when encrypting the file. For a list of valid parameters, see memresize in the UniData Commands Reference.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 an entire record:

Algorithm – Enter the algorithm to use for encrypting the record. For a list of valid algorithms, see UniData Encryption Algorithms in Chapter 4, “ Automatic Data Encryption.” Key – Select the encryption key you want to use when encrypting the data from the Key list. Password – Enter the password corresponding the encryption key, if one exists.

Click Apply. UniData 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 memresize parameters to use when encrypting the file. For a list of valid parameters, see memresize in the UniData Commands Reference.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 UniData Encryption Algorithms in Chapter 4, “ Automatic Data Encryption.”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.


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

Decrypting an Entire Record

Define 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 ant to decrypt data.Parameters – The memresize parameters to use when decrypting the file. For a list of valid parameters, see memresize in the UniData Commands Reference.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 decrypting 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 the encryption key, if one exists.

Click Apply. UniData 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 memresize parameters to use when decrypting the file. For a list of valid parameters, see memresize in the UniData Commands Reference.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.


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. A dialog box similar to the following example appears:

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 backup the current audit file, enter the path 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 path 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.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 – Creating encryption key DELETE – Deleting encryption key GRANT – Granting key accessREVOKE – Revoking key accessACTIVATE – Activating encryption keyDEACTIVT – Deactivating encryption keyENABLE – Enabling encryption keyDISABLE – Disabling encryption keyENCRYPT – Encrypting a fileDECRYPT – Decrypting a fileRMKEYSTR – Deleting Key StoreFLHDCHG – Encryption flag change in file headerCREATWLT - Creates a wallet


DELETWLT - Deletes 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:


4Chapter

XML Enhancements

Summary of XML Enhancements . . . . . . . . . . . . . 4-2 In This Chapter . . . . . . . . . . . . . . . . . . 4-2XML Configuration File . . . . . . . . . . . . . . . . 4-4 xmlconfig Parameters . . . . . . . . . . . . . . . . 4-5ECL Commands . . . . . . . . . . . . . . . . . . . 4-15 New Session-level ECL Commands . . . . . . . . . . . 4-15 Existing ECL Command Affected by XMLSETOPTIONS

Command or XMLSetOptions() API . . . . . . . . . . . 4-21UniBasic APIs . . . . . . . . . . . . . . . . . . . 4-23 New Session-level XML APIs . . . . . . . . . . . . . 4-23 Existing APIs That Support Additional XML Parameters. . . . . 4-30 Existing APIs Affected by XML Options . . . . . . . . . . 4-43

C:\Program Files\Adobe\FrameMaker8\UniData

Summary of XML EnhancementsAt version 7.2, the UniData XML APIs provide support for multibyte characters. With this enhancement, UniData can handle most encodings and character sets, including UTF-8, SBCS, and DBCS.

In XML documents, node names (such as element name or attribute name) and node values (such as text or attribute values) can be in any given encoding. In addition to specifying the encoding used in XML documents, you can set a number of other parameters to control the behavior of XML documents.

In This ChapterUniData 7.2 implements several means to control the behavior of XML documents. This chapter discusses each way to change the settings used in XML documents:

XML Configuration File – The settings in the xmlconfig files control the behavior of XML documents at the system level and at the account level.ECL CommandsNew Session-level ECL Commands – Three new session-level ECL commands are provided to set and get XML options. The XML options set by the ECL command override the settings in system-level and account-level xmlconfig files during the current session.Existing ECL Command Affected by XMLSETOPTIONS Command or XMLSetOptions() API – One existing ECL command is affected by the XML options set at the session level through the XMLSETOPTIONS command or through the XMLSetOptions() API.

4-2

C:\Program Files\Adobe\FrameMaker8\UniData 7.2\7.2rebranded\NEWFEATURES\NEWFEATCH04.fm3/8/10

UniBasic APIs New Session-level XML APIs – Three new APIs for use in UniBasic programs override the settings in system-level and account-level xmlconfig files and in ECL commands during the current session.Existing APIs That Support Additional XML Parameters – Some of the existing UniBasic APIs support additional parameters for encoding and other XML options, as well as other new XML-related parameters.Existing APIs Affected by XML Options – Several existing UniBasic APIs are affected by the XML options set in the system-level or account-level xmlconfig file, the XMLSETOPTIONS command, or the XMLSetOptions() API during the current session.



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 \udthome\include on Windows or /usr/ud72/include on UNIX.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=utf8in-encoding=EUCJPout-encoding=uft8out-xml-declaration=trueout-pretty-format=trueout-newline=CR-LF

Keys and values are case-insensitive.

When you start a UniData session, UniData 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 udt.errlog:

38 Invalid XML config key: ‘key_name’39 Invalid XML config value: ‘value_string’40 Invalid XML config format: ‘name_value_string’

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

4-4


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

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

xmlconfig Parameters



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

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


xmlconfig Parameters (Continued)

4-6


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

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



4-8


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

matchelement Specifies how UniData 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 second 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 attribute of the field is used as a nested element tag. The content of the attribute is shown within the attribute’s element tags. For example:

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

1



4-10


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.type – To be described at a later release.

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





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 – UniData creates the entire XML document as well as a DTD and an XMLSchema.1 – UniData 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

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

NULL



4-12


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





ECL CommandsIn UniData 7.2, you can enter ECL commands to specify the encoding and other parameters for use in XML documents during the current session.

This section discusses the following enhancements to ECL commands:

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

New Session-level ECL CommandsThree new XML commands are available from the ECL command line:

XMLSETOPTIONSXMLGETOPTIONSXMLGETOPTIONVALUE

4-14


XMLSETOPTIONS

Syntax

XMLSETOPTIONS <options>

Description

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

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 UniData XML options and settings, see “xmlconfig Parameters” on page 4-5.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 UniData session.

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

Note: If UniData 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.



Examples

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

XMLSETOPTIONS encoding=UTF-8 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

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

XMLSETOPTIONS defaults

4-16


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



If you enter the XMLGETOPTIONS 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=falsematchelement=1 emptyattribute=0 elementmode=0 schematype=ref hidemv=0 hidems=0 collapsemv=0 collapsems=0 hideroot=0

For a complete list of the standard UniData XML options and values returned by this command, see “xmlconfig Parameters” on page 4-5.

4-18


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 UniData session.

Parameters


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 UniData XML options, see “xmlconfig Parameters” on page 4-5.

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 ECL Command Affected by XMLSETOPTIONS Command or XMLSetOptions() APIThe syntax of the following ECL 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 UniData 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 UniData session.

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 UniQuery condition string, for example, WITH SCHOOL = “CO002”

4-20


Example

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

DB.TOXML SCHOOL_STUDENT.XML STUDENT.MAP WITH SCHOOLID = “CO002”



UniBasic APIsIn UniData 7.2, UniBasic programs support new and enhanced XML APIs:

New Session-level XML APIsExisting APIs That Support Additional XML ParametersExisting APIs Affected by XML Options

New Session-level XML APIsUniBasic programs in UniData 7.2 support three new APIs for XML documents:

XMLSetOptionsXMLGetOptionsXMLGetOptionValue

These three APIs apply to the settings of XML documents at the session level.

4-22


XMLSetOptions

Syntax

XMLSetOptions("options")

Description

Use this function in UniBasic programs to set the encoding parameter and other XML options in the current UniData session. The settings specified in this API override the settings in the system-level and account-level xmlconfig files and in ECL 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 UniData XML options and settings, see “xmlconfig Parameters” on page 4-5.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 UniData session.

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

A special string must be entered as the only option.



Examples

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

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

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

XMLSetOptions("defaults")

Return Codes

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

XMLSetOptions 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’

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

4-24


XMLGetOptions

Syntax

XMLGetOptions(outOptions[, delimiterString])

Description

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

Parameters


XMLGetOptions Parameters


outOptions A variable used to retrieve the XML options key/value pairs in effect in the current UniData 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<>standalone=no<> out-xml-declaration=true<>out-format-pretty-print=false<>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=true<>out-write-bom=false<>



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 standalone=no out-xml-declaration=true out-format-pretty-print=false 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=true out-write-bom=false

For a complete list of the standard UniData XML options and values returned by this function, see “xmlconfig Parameters” on page 4-5.

Return Codes

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

XMLGetOptions Return Codes



4-26


XMLGetOptionValue

Syntax

XMLGetOptionValue(optionName, outOptionValue)

Description

Use this function in UniBasic programs to return the value of encoding or any other XML option in effect in the current UniData 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 UniData XML options, see “xmlconfig Parameters” on page 4-5.

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

Example

The following example shows the format for entering the optionName and outOp-tionValue 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:


4-28


Existing APIs That Support Additional XML ParametersSome of the existing XML APIs have been enhanced to accept additional parameters for encoding and other XML options, or other new parameters:

XDOMCreateRootXDOMTransformXDOMValidateXDOMValidateDomXDOMWriteXMAPToXMLDoc



XDOMCreateRoot

Syntax

XDOMCreateRoot(domHandle[, xmlOptions])

Note: This function is case-sensitive. If you want it to be case-insensitive, you must compile your programs using the BASIC command with the -i option.

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 “xmlconfig Parameters” on page 4-5. Keys and values are case-insensitive.Valid encoding settings can be found at http://www.iana.org/assignments/character-sets

4-30


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:






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



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 (default) XML.FROM.STRING[IN]

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

XDOMTransform Parameters

4-32


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.

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.


XDOMTransform Parameters (Continued)



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 (default) 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]

4-34


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]

4-36


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

4-38


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 UniData XML options and settings, see “xmlconfig Parameters” on page 4-5.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. UniData writes the data to a file or a UniBasic variable.

Parameters



XMAPhandle The handle to the U2XMAP dataset.

xmlfile The name of the XML file, or the name of a UniBasic 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 UniBasic variable.

XMAPToXMLDoc Parameters

4-40


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:




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 UniData XML options and settings, see “xmlconfig Parameters” on page 4-5.Valid encoding settings can be found at http://www.iana.org/assign-ments/character-sets


XMAPToXMLDoc Parameters (Continued)



Existing APIs Affected by XML OptionsThe syntax of the following UniBasic APIs remains unchanged. However, one or more XML options set in the xmlconfig files, the XMLSETOPTIONS command, or the XMLSetOptions() API are used by the following APIs:

DBTOXMLXDOMAddChildXDOMAppendXDOMCreateNodeXDOMEvaluateXDOMGetAttributeXDOMGetNodeNameXDOMGetNodeValueXDOMInsertXDOMLocateXDOMRemoveXDOMReplaceXDOMSetNodeValueXMAPAppendRecXMAPOpenXMAPReadNext

4-42


DBTOXML

Syntax

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

Description

Creates an XML document from the UniData 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 UniData 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 UniData session.



XDOMAddChild

Syntax

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


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.

XDOMAddChild Parameters

4-44


Return Codes


XDOMAddChild Return Codes





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

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.

XDOMAppend Parameters

4-46


Return Codes


XDOMAppend Return Codes





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

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

4-48


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.NODEUniData uses this argument, along with direction and childIndex, to get the right type node. For example, if direction is XDOM.PREV.SIBLING, and nodeType is XDOM.ELEMENT.NODE, UniData finds the element node that is the first previous sibling of nodeHandle. If direction is XDOM.CHILD, childIndex is XDOM.FIRST.CHILD, and nodeType is XDOM.ELEMENT.NODE, UniData finds the element node that is the first element child of nodeHandle. If the direction is XDOM.CHILD, childIndex is 2, and nodeType is XDOM.ELEMENT.NODE, UniData finds the element node that is the second element child of nodeHandle.When the direction is XDOM.NEXT.SIBLING.WITH.SAME.NAME, XDOM.PREV.SIBLING.WITH.SAME.NAME, or XDOM.PARENT, this argument is not used. [IN]

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

Parameters Description

XDOMCreateNode Parameters (Continued)



Return Codes


XDOMCreateNode Return Codes




4-50


XDOMEvaluate

Syntax

XDOMEvaluate(xmlHandle, xpathString, nsMap, aValue)


Description

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

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.

XDOMEvaluate Parameters



Return Codes


XDOMEvaluate Return Codes





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.


XDOMEvaluate Parameters (Continued)

4-52


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







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





4-54


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







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.

XDOMInsert Parameters

4-56


Return Codes


XDOMInsert Return Codes





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]

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)



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



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.

XDOMLocate Parameters

4-58


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.

noteHandle Handle to the found node. [OUT]


XDOMLocate Parameters (Continued)



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

4-60


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)



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

4-62


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)



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





4-64


XMAPAppendRec

Syntax

XMAPAppendRec(XMAPhandle, file_name, record)


Description

The XMAPAppendRec function formats the specified record from the UniData 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 UniData file that is being mapped in the U2 XMAP dataset.

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



Return Codes


XMAPAppendRec Return Codes



XML_ERROR An error occurred opening the XML document.

XML_INVALID_HANDLE The XMAP dataset was invalid.

4-66


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



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

XMAPOpen Parameters



Return Codes


XMAPOpen Return Codes



XML_ERROR An error occurred opening the XML document.

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.


XMAPOpen Parameters (Continued)

4-68


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 UniData 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 UniData file that is being mapped in the U2XMAP dataset.

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



Return Codes


XMAPReadNext Return Codes


XML_SUCCESS The XMAPReadNext was executed successfully.

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.

4-70

5Chapter

UniData Replication Enhancements

Enabling and Disabling Replication . . . . . . . . . . . . . 5-4Replication Files with Multiple VOC Pointers . . . . . . . . . 5-5Listing Replication Files . . . . . . . . . . . . . . . . 5-6UniData Command Replication . . . . . . . . . . . . . . 5-8 File-Level Command Replication . . . . . . . . . . . . 5-8 Other Command Replication. . . . . . . . . . . . . . 5-9Writeable Subscriber Files . . . . . . . . . . . . . . . . 5-10Replication Configuration File Changes . . . . . . . . . . . 5-11 LEVEL Phrase . . . . . . . . . . . . . . . . . . 5-11 FILE Phrase . . . . . . . . . . . . . . . . . . . 5-11 EXCLUDED_FILE Phrase . . . . . . . . . . . . . . 5-12 RESERVED_FILE_SPACE Phrase . . . . . . . . . . . 5-12 Account-Level Group Example . . . . . . . . . . . . . 5-13Dual-threaded Subscriber Processing . . . . . . . . . . . . 5-14Compatibility with Previous UniData Releases . . . . . . . . . 5-15 Upgrading to UniData 7.2 . . . . . . . . . . . . . . 5-15UniData Data Replication Restrictions . . . . . . . . . . . . 5-16

Beginning at this release, UniData supports account-level and file-level replication. Account-level replication enables you to replicate all data in an account, as well as file-level operations.

The following commands can now be replicated:

DIR file operations:EDCOPYCLEAR.FILE

File-level commandsCREATE.FILEDELETE.FILECLEAR.FILECNAMESETFILEENABLE.REPLICATION.FILEDISABLE.REPLICATION.FILE

Other commands:BASICCATALOGDELETE.CATALOG

UniData does not support the following commands for account-level replication at this release:

CREATE.INDEXDELETE.INDEXBUILD.INDEXDISABLE.INDEXENABLE.INDEXUPDATE.INDEXRESIZECLEAR.ACCOUNT

5-2

SAVE.LISTCOPY.LISTMERGE.LISTDELETE.LISTCREATE.TRIGGERDELETE.TRIGGER

Note: The commands UniData does not support for replication can be executed on the subscribing system, they are not blocked.

Account-level replication replicates all updates to data to all files in an account, except those defined in the excluded file list. You can define multiple file-level groups in an account, and one account-level group. If a file is defined in a file-level group, UniData replicates updates through the replication group where the file is defined. If you do not explicitly define the file in a group, UniData replicates the updates through the account-level group.

You can create an included file list in an account-level group. You may want to define a file explicitly in an account-level group if the file has a symbolic link or VOC pointer and you want to clearly define the primary replication file, or you want to define the file with special options.

By default, UniData automatically adds the VOC file to the account-level group.


Enabling and Disabling ReplicationThe following file-level commands automatically enable a replication file:

CREATE.FILE – Enables the newly created file and/or its dictionarySETFILE – Enables the new VOC pointer for the data and/or dictionary fileCNAME – Enables the data and dictionary files with the new VOC nameRESIZE – Reregisters the replication file with a new i-no and d-no

The following commands automatically disable the file for replication:

DELETE.FILE – Disables the deleted file and its dictionaryCNAME – Disables the data and/or dictionary file with the old name

5-4

Replication Files with Multiple VOC PointersIf a file has multiple definitions in the VOC file, in the same or different account, UniData loads each VOC item name in different replication file entries. When a udt or tm process updates a record in the file, the process searches for the primary repli-cation file entry in the Replication File Table by the i-no/d-no, beginning from the static replication file entries. If there is no match, UniData searches the dynamic replication file entries. UniData uses the first match for replication, generating a replication log in the associated replication group, and sending the VOC file name to the subscriber for publication. This VOC name is referred to as the primary repli-cation file.

When you issue a DELETE.FILE command that physically deletes the file, UniData disables all replication file entries with the same i-no/d-no. If you delete a VOC pointer that points to the file, or a symbolic link or physical link, UniData only disables the corresponding replication file entry. UniData does not disable other replication file entries pointing to the file. If you disable the primary replication file, UniData uses the next matched file as the primary replication file.

When you enable a replication file, UniData only enables the corresponding VOC file name and account ID, it does not automatically search and enable other VOC file names that point to the same file.

When you replicate a file-level command, UniData uses the corresponding repli-cation file entry for the target file regardless if it is the primary replication file or a secondary replication file. UniData always replicates record-level commands through the primary replication file.

If you have multiple VOC file entries for a replication file, we recommend that you define only one VOC name in the included file list so UniData knows which file name and which system group to use with replication.


Listing Replication FilesUse the LIST.REPLICATION.FILE to list active replication files in your application. This command lists all replication file entries for an account or file you specify.

LIST.REPLICATION.FILE [ALL |DICT |DATA] filename[,subfile] NO.PAGE

If you specify ALL, UniData displays all active replication files in the current account. If the local account is an account-level replication account, this command displays the account as well.

If you specify a file name, UniData displays all replication files contained in the Replication File Table related to that file. If you do not specify ALL or filename, UniData obtains the file names from an active select list, or prompts for input.

LIST.REPLICATION.FILE displays the following information about replicated files:

FTYPE – The type of file. Valid file types are:LF – LF directoryLD – LD directoryDIR – DIR fileDICT – Dictionary fileDATA – Hashed fileACCT – The account-level replication account

FILE NAME – The VOC file name in the Replication File Table. If the replication file is not located in the local account, the LIST.REPLI-CATION.FILE command also lists the path to the file.REPLICATION – The replication definition for the file.

PUBLISHED – The file is publishedSUBSCRIBED – The file is subscribedEXCLUDED – The file is excluded from replicationINACTIVE – The file is included in replication, but is currently disabled

PRIMARY – Whether the file is considered the primary replication file.GROUP – The name of the replication group

5-6

UniData Command ReplicationThis section describes the commands UniData replicates with account-level replication.

File-Level Command ReplicationTo replicate file-level commands, you must publish the target file. If the excluded file list contains that file, or if the file is disabled, UniData does not replicate the file-level command.

If a file-level command creates a new file, and UniData successfully enables the file on the publishing system, UniData replicates the command to the subscriber.

If a file-level command automatically updates a VOC or dictionary file. UniData replicates these updates, whether or not the VOC or dictionary file is published. These updates are also performed on the subscribing system when reexecuting the command.

CREATE.FILE

When you execute the CREATE.FILE command, UniData enables the file for repli-cation. If UniData successfully enables the file as a publishing file, it sends the command itself to the subscribing system for replication. When the subscribing system receives the CREATE.FILE log, the replication writer process applies an exclusive lock to the VOC entry for the file and reexecutes the command.

After the replication writer process creates the file on the subscribing system, it enables the file for subscription. Updates on the file will also be replicated.

If you specify the PARTTBL option with the CREATE.FILE command, UniData does not replicate this option to the subscriber, but uses the default PARTTBL on the subscribing system.

DELETE.FILE

When you execute the DELETE.FILE command, UniData checks if the file is published. If so, UniData sends the command to the subscribing system for replication.


The DELETE.FILE command automatically disables the publication and subscription of the file.

Note: If UDT.OPTIONS 87 is ON on the publishing system, this also will be ON on the subscribing system with the DELETE.FILE log. The replication writer process will delete the remote file.

CNAME

The CNAME command changes both the physical name and VOC entry name for both the data file and its dictionary. The old file name must be an enabled publishing file or the CNAME command will not replicate on the subscribing system.

If you enable the new file as a replication file in a different replication group than the old file, UniData replicates the CNAME command in the group of the original file and does not synchronize it with other operations on the new file.

SETFILE

The SETFILE command creates a file pointer in the VOC for a UniData file. UniData replicates the SETFILE command by reexecuting the command on the subscribing system.

Other Command ReplicationUniData replicates the BASIC command, the CATALOG command, and the DELETE.CATALOG command through the account-level group. If you do not define an account-level group, UniData does not replicate these commands, even if the target file is defined as a replicated file. If you define an account-level group. UniData replicates these commands, even if the target file is not defined as a repli-cated file.

5-8

Writeable Subscriber FilesBefore UniData 7.2, files on the subscribing system were read-only. Now, you can update a file on the subscribing system if you explicitly define it as writeable in the repconfig file. Updates made to a writeable file on the subscribing system are not replicated back to the publishing system.

You can update both record-level and file-level operations on a writeable subscriber file. If a file-level operation updates the VOC or dictionary file, you must specify these files as writable in the repconfig file.


Replication Configuration File ChangesThe following phrase syntax has been added to support account-level replication.

LEVEL PhraseThe LEVEL phrase defines the replication level of a replication group. By default, a replication group is a file-level group.

LEVEL=[ACCOUNT | FILE]

Account-level replication replicates updates to all files in an account, except those defined in the Excluded File phrase. You can define multiple file-level groups in an account, and one account-level group. If a file is defined in a file-level group, UniData replicates updates through the replication group where the file is defined. If you do not explicitly define the file in a group, UniData replicates the updates through the account-level group.

FILE PhraseEach group section can contain multiple file sections. A file section defines a repli-cation object in a replication group, and a FILE phrase defines the fle name.

The FILE Phrase has the following syntax:

FILE=[SUB_WRITEABLE] [DICT | DATA] <filename> [,subfile]

If you specify SUB_WRITEABLE, you can write to the file you specify on the subscribing system. On the publishing system, this does not take effect until system failover.

If you specify DICT, only the dictionary portion of the file is replicated. If you specify DATA, only the DATA portion of the files is replication. Otherwise, UniData replicates both the dictionary and data portion of the file. This behavior is new at UniData 7.2.

If the filename you specify is a multilevel file and you do not specify a subfile name, UniData replicates the multilevel file and all its part files. It does not include newly created part files after UniData starts. This behavior is new at UniData 7.2.

5-10

An account-level group can also have file sections. You may want to define a file explicitly in an account-level group if the file has a symbolic link or VOC pointer and you want to clearly define the primary replication file, or you want to define the file with special options.

By default, UniData automatically adds the VOC file to the account-level group.

Warning: If you define a file in more than one replication group, UniData will use and only one, file definition. The file UniData chooses is arbitrary

EXCLUDED_FILE PhraseThe EXCLUDED_FILE phrase defines an excluded file for a replication account.

EXCLUDED_FILE=[DICT | DATA] filename[,subfile]

RESERVED_FILE_SPACE PhraseThe RESERVED_FILE_SPACE phrase defines the amount of slots to reserve for an account-level group. The default value is 500.

RESERVED_FILE_SPACE=<number of reserved files>

If the RESERVED_FILE_SPACE is full, the CREATE.FILE command will fail with an error similar to the following example:

Replication object table is full: Enable Replication object TEST3 failed.Creating file TEST3 failed.

============>>>> NOTE: CREATE.FILE failed! <<<<<<==============Not - file created but cannot be replicated. Table full = fatal error.

You can reload the Replication File Table and provide fresh reserve slots without stopping UniData by running the ud_repadmin reconfig command.


Account-Level Group ExampleThe following example illustrates an account-level group:

GROUP=SAMPLE_ACCTLEVEL=ACCOUNTACCOUNT=C:\IBM\ud72\demoFILE=SUB_WRITEABLE VOCFILE=STUDENTFILE=CUSTOMEREXCLUDED_FILE=_XML_EXCLUDED_FILE=_EDA.MAP_EXCLUDED_FILE=ENGLISH.MSGDISTRIBUTION=P:DESKTOP_72DISTRIBUTION=IB:DESKTOP2_72#Definition of tunable parametersRESERVED_FILE_SPACE=500N_LOGINFO=5120REP_BUFSZ=163840N_REPWRITER=2RW_IGNORE_ERROR=1RW_REEVALUATE_VF=0RW_SKIP_TRIGGER=1

5-12

Dual-threaded Subscriber ProcessingAt UniData 7.2, the subscriber process is dual-threaded. This enhancement reduces the rate of replication buffer overflow when large amounts of data are received from the publisher in a short period of time.

Prior to UniData 7.2, cross-group transactions may have resulted in performance degradation on the subscribing system, and delaying SubDone responses to the publisher, which could have blocked an RFS checkpoint on the publishing system. The dual-threaded subscriber process reduces TCA overflow for cross-group transactions.

In addition, this enhancement reduces delays encountered during a replication SYNC operation when large amounts of data have been accumulated during a suspension of replication.


Compatibility with Previous UniData ReleasesThis section describes changes made to UniData Data Replication at this release.

Upgrading to UniData 7.2After upgrading to UniData 7.2, you must clear the replication log directory.

You must upgrade both the publishing system and the subscribing system for repli-cation to run correctly.

These changes are required due to the new Protocol=10004.

5-14

UniData Data Replication RestrictionsThis section describes the restrictions in UniData Data Replication at UniData 7.2.

UniData Data Replication does not support sequential file operations.UniData Data Replication does not support account-level operations on the following files:

_HOLD__PH__DEBUG__REPORT__SCREEN__XML__EDAMAP__EDAXMAP_MENUFILE

Account-level replication does not replicate the following operations:CONFIGURE.FILEREBUILD.FILEshfbuildmemresizeconvhashconvmarkconvcodeconvtapeconvdataconvidxconvsecuudfileSETLANG

If you replicate both the data and dictionary portions of a file, they must belong to the same replication group.


UniData Data Replication only keeps the operation sequence within the same replication group. If you replicate an account-level and a file-level operation that updates a file in different replication groups, we do not guarantee that updates will be processed in the same sequence. To keep subscribing and publishing files consistent, you should define all related files in the same replication group.If you are running the Recoverable File System on the publishing system, the CNAME command does not regenerate replication log files for record-level update that occurred prior to executing the CNAME command when restarting UniData after a system crash. The updates to a file before executing the CNAME command may be lost on the subscribing system.UniData Data Replication may apply multiple locks on the subscribing system. If your application is running on the subscribing system and you need to apply the same lock, you should follow the same locking sequence to avoid a deadlock.

5-16

6Chapter

Miscellaneous Enchancements

64-bit Sequential File Access . . . . . . . . . . . . . . . 6-2Support for 64-bit Log Files with The Recoverable File System . . . . 6-4 Backing Up Archive Files . . . . . . . . . . . . . . 6-4 Log File Size Recommendations . . . . . . . . . . . . 6-5Resizing Files Concurrently . . . . . . . . . . . . . . . 6-6 ECL RESIZE Command Enhancements . . . . . . . . . . 6-6 Recovering from a Concurrent Resize Error . . . . . . . . . 6-8 File Tools Enhancements . . . . . . . . . . . . . . . 6-9 Log Files . . . . . . . . . . . . . . . . . . . . 6-9Extensible Administration Tool . . . . . . . . . . . . . . 6-10New Stub Functions for OFS . . . . . . . . . . . . . . . 6-12 activatekey . . . . . . . . . . . . . . . . . . . 6-12 disabledec . . . . . . . . . . . . . . . . . . . 6-12

64-bit Sequential File AccessAt this release, UniData supports sequential file access for 64-bit files. However, since UniData does not support 64-bit integers, you cannot execute specify AT byte.expr if byte.expr exceeds 2,147,483,648 bytes (2GB).

The following commands and objects are affected by this enhancement:

UniBasic

OSOPEN

OSBWRITE (AT byte.expr cannot exceed 2,147,483,648 bytes)

OSCLOSE

OSDELETE

OSBREAD (AT byte.expr cannot exceed 2,147,483,648 bytes)

OPENSEQ

CLOSESEQ

WRITESEQ

WRITESEQF

WEOFSEQ

READSEQ

InterCall

ic_closeseq

ic_openseq

ic_readseq

ic_weofseq

ic_writeseq

6-2

UniObjects for Java

UniSequentialFile object

The UniObjectsToken UVT_CURR of the fileSeek method cannot exceed 2,147,483,648 bytes

UniObjects for .NET

UniSequentialFile method

The UniObjectsToken UVT_CURR of the fileSeek method cannot exceed 2,147,483,648 bytes


Support for 64-bit Log Files with The Recoverable File SystemIf you are using The Recoverable File System, you can now configure your before image log files, after image log files, and archive log files to exceed 2 GB on both conventional file systems and UNIX raw disks. At this release, 64-bit log files are supported on the following platforms:

AIX421AIX5AIX564HPUX11HPUX1164RHLINUX9ISOLARISSOLARIS28SOLARIS29WINDOWS platforms

Before this release, the limit for the blocksize in the logconfig and archconfig config-uration files could not exceed 64K. This limit has been increased to 2 GB. You can now express the Start Block Number and Number of Blocks in these configuration files are 64-bit integers.

Make sure that the file size limitation where UniData is running is large enough to read and write the log files. See the UNIX ulimit command.

Backing Up Archive FilesBecause of changes in internal structures, the mediarec command will not support archive files created before UniData 7.2. Because of this, you must back up your archive files prior to installing The UniData 7.2 Recoverable File System.

6-4

Log File Size RecommendationsWe recommend that you do not configure your before image and after image log files to a very large size for the following reasons:

The larger the size of the log file, the longer it takes for the system to perform crash recovery.The crash recovery process performs a sort in memory to obtain information about the before image and after image log files, and may not be able to allocate the necessary memory if the log files are too large.


Resizing Files ConcurrentlyPrior to the UniData 7.2 release, database administrators had to retain an exclusive lock on a UniData hashed file while it was being resized. Other users could not access the file until the resize operation completed. Now, both static hashed files and dynamic files can be resized while other users concurrently access the file.

File-level update operations are not allowed when a file is being resized. UniData will display an error message similar to the following example to the screen, and will write the error message to the udt.errlog for non-recoverable files, or the sm.log for recoverable files.

Note: Resizing files concurrently is supported on UNIX platforms only.

Tue Jun 12 07:46:38: The file “CUSTOMERS” is being RESIZEd CONCURRENT. CLEAR.FILE failed.

File-level operations not allowed during a concurrent resize include:

CREATE.INDEXDELETE.INDEXCNAMEDELETE.FILECLEAR.FILERESIZE (the same file at the same time)CREATE.TRIGGERDELETE.TRIGGERENCRYPT.FILEDECRYPT.FILEDISABLE.RFS.FILE

ECL RESIZE Command EnhancementsThe following enhancements are available with the ECL RESIZE command at UniData 7.2:

The RESIZE command can now be used with both static and dynamic files.

6-6

You can resize a static file to a dynamic file, or a dynamic file to a static file.You can resize a file online while allowing other users access to the file.

Syntax

RESIZE [DICT] filename [modulo [,block.size.multiplier | -]] [TYPE {0 | 1}] [STATIC |[DYNAMIC [KEYONLY | KEYDATA] [OVERFLOW] [PARTTBL part_tbl]]] [CONCURRENT [CONTINUE | RESTORE]]

Parameters

The following table describes each parameter of the syntax:.


DICT Resizes the dictionary portion of filename.

filename The name of the file to be resized.

modulo The new modulo number to be assigned to the file.

block.size.multiplier An integer between 0 and 16 that UniData uses to determine file size.

TYPE {0 | 1} Hash type for the resized file.

- Resizes the file according to its actual size, thus correcting overflows.

STATIC After resizing, the file is a static hashed file.

DYNAMIC After resizing, the file is a dynamic hashed file.

KEYDATA After resizing, the file is dynamic and the split/merge type is KEYDATA.

KEYONLY After resizing the file is dynamic and the split/merge type is KEYONLY (the default).

OVERFLOW If specified, UniData creates a dynamic file with an overflow file for each dat file. For example, over001 corresponds to dat001, over002 corresponds to dat 002, and so forth. When the file is cleared, UniData maintains this overflow structure.

RESIZE Parameters


Recovering from a Concurrent Resize ErrorIf the concurrent resizing process encounters an error, or the system crashes during the resize operation, complete the following steps to restore the file:

1. Check and repair the physical integrity of the file, if necessary. For nonre-coverable files, use the guide utility to check if the file needs to be repaired. If so, use the fixfile command to repair the file. If the file is a recoverable file, restarting UniData after the system crash should automatically fix both the original file and the temporary copy of the file as it was being resized.

2. Execute the RESIZE CONCURRENT CONTINUE command against the file if you want the resize operation to continue to completion. Execute the RESIZE CONCURRENT RESTORE command against the file if you want to delete the temporary copy of the file and restore the original file before any resize operation took place. If you do not execute either of these options, the RESIZE CONCURRENT operation will fail and display an error message describing the reason for the failure.

PARTTBL,part_tbl After resizing, file is a dynamic file. part_tbl is the path and file name of a previously established part table. RESIZE copies part_tbl into the dynamic file directory. The copy of part_tbl in the dynamic file directory serves as the “per-file” part table for the dynamic file.Note: This option is supported on UniData for UNIX only.

CONCURRENT Resize the file allowing concurrent access from other users.

CONTINUE If the system crashes or RESIZE CONCURRENT encounters an error, continue the resize operation to completion.

RESTORE If the system crashes or RESIZE CONCURRENT encounters an error, delete the temportary copy of the resized file and restore the original file before any resize operation took place.


RESIZE Parameters (Continued)

6-8

File Tools EnhancementsAt this release, the guide utility has been enhanced to display a message indicating that the file is currently being resized. The message includes the number of groups that have been resized.

Log FilesUniData now creates a log file, located in $UDTBIN/resize.log, for the RESIZE and memresize commands that includes the following information:

Time/DateStarted or Completed statusUser name, with TTY if availableFile nameFull path to fileThe characteristics of the file before resize, including modulo, block size, hash type, file type (static or dynamic, keyonly or keydata)The characteristics of the file after resize, including modulo, block size, hash type, file type (static or dynamic, keyonly or keydata)

The resize_cleanup.info Log File

The resize_cleanup.info log file contains information pertaining to the original dynamic file before the concurrent resize operation started. The cleanupd daemon uses the information in this file to delete unneeded files when users no long have the file open. Users should have write permissions to this file.


Extensible Administration ToolIBM UniData 7.2 contains the first GA release of Extensible Administration Tool for UniData (XAdmin), an Eclipse-based interface for administering UniData. This tool allows you to perform the tasks of database administration in an environment that is visual and intuitive.

The full functionality of UniAdmin will be implemented incrementally in XAdmin. In this first release, XAdmin contains a subset of all the functionality available in UniAdmin. You can use it to perform the following tasks, among others:

Add or view UniData accountsUpdate or view UniData configuration parametersView live file input/output activity and lock statistics graphically in perfor-mance monitorsUpdate UniData license information using a wizardDisplay information on UniData users and number of licenses in use

We encourage you to try out the features of XAdmin and provide feedback on this new interface for data server administration. But does this mean XAdmin is just for experimental use? Any task performed in XAdmin is processed as a normal transaction in the development or test environment in which UniData is running. However, UniAdmin has not gone away. While XAdmin is under development and functionality is rolled out in phases, UniAdmin remains fully supported so all functionality can still be accessed and performed through the old tool.

To install XAdmin, choose the Eclipse Based Tools option on the IBM UniData 7.2 client CD image. When installing the Eclipse Based Tools, the program allows you to select the features you want to copy to your computer. In the Select Features dialog box, the Extensible Administration Tool is selected by default. Leave this check box selected to install XAdmin.

After completing the installation, you can start XAdmin by choosing Start > Programs > IBM U2 > IBM U2 Tools > Extensible Administration Tool. This opens a window containing the XAdmin environment. As with all Eclipse tools, the screen is divided into work areas, or panes. Each pane is called a view. The six views you see in the initial arrangement are the default configuration out of the box. You can first work with the default configuration, and then try closing, moving, maximizing, minimizing, and opening views to customize the work areas to meet your needs.

6-10

To get started, go to the U2 Resource view in the upper left corner of the window. The Create a New U2 Server wizard makes it simple for you to define a server. After you have defined a server, the first thing to do is make a connection to it. Double-click the server name to connect to it, and then enter your user name and password.

Notice that the Admin Tasks view in the lower left pane populates with all the tasks you can perform in XAdmin to administer UniData.

XAdmin is currently available for UniData only; in the future, we plan to offer this tool in both U2 data server products.


New Stub Functions for OFSThe following stub functions have been added for OFS at UniData 7.2. You must add these stub functions before executing makeudt. If you do not add these functions, makeudt will fail.

activatekeyint ofs.family_activatekey(dm_hd,key,pass,flag,st)

int dm_hd d_char *key d_char *pass int flag int *st

disabledecint ofs.family_disabledec(dm_hd, fname, fld_list,int flag,st)

int dm_hd d_char *fname d_char *fld_list int flag int *st

6-12

:\ProgMarch

1Administering UniData on Windows NT or Windows 20000

7 Chapter

ram Fi8 2010

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

Deploying Web Services

Exporting Web Services . . . . . . . . . . . . . . . 7-2 Deploying the SOAP Server . . . . . . . . . . . . . . 7-4 Define Security between the Client and the SOAP Server . . . . 7-8 Set Connection Properties . . . . . . . . . . . . . . 7-10 Define UniData Database Connection Security . . . . . . . . 7-13Running and Stopping the SOAP Server . . . . . . . . . . . 7-16Monitoring a Remote SOAP Server . . . . . . . . . . . . . 7-17

les\Adobe\FrameMaker8\UniData 7.2\7.2rebranded\NEWFEATURES\NEWFEATCH07TOC.fm2:01 pm Administering UniData on Windows NT or Windows 2000


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 files? The runsoapserver and stopsoapserver scripts? All 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.

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:



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.

7-3


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. From the directory where you unzipped the file, execute the rundeploytool command.

rundeploytool current_directory target_directory

For example:

rundeploytool . C:\temp\myservice

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.

7-5


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 UniData uses connection pooling with the U2 Web Services Developer. 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, UniData 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.

7-7


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 certification for authentication, select the Need Client Authentication check box.

Click Finish.

7-9


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 For UniData, the service name is udcs.

UniRPC Port NumberEnter the port number of the UniRPC server running on the host in the UniRPC Port Number box.

7-11


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 UniData Database Connection SecurityClick the DB Security tab if you want to define security between the SOAP server and the UniData 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.

7-13


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 certification for authentication, select the Need Client Authentication check box.

Click Next.

For detailed information about SSL, see UniData Security Features.



U2 Web Services Developer deploys the web services you specifed. 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:

7-15


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.

7-17


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:

7-19


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

7-21

unidata 7.2 new features - rocket software · the eda driver api enables you to write your own...

Documents