unidata 7.1 new features - amazon s3s3.amazonaws.com/zanran_storage/ unidata 7.1 new features the...

UniData

UniData 7.1 New Features

Version 7.1September, 2007

ii UniData 7.1 New F

IBM Corporation 555 Bailey Avenue San Jose, CA 95141

Licensed Materials – Property of IBM

© Copyright International Business Machines Corporation 2005, 2007. All rights reserved.

AIX, DB2, DB2 Universal Database, Distributed Relational Database Architecture, NUMA-Q, OS/2, OS/390, and OS/400, IBM Informix®, C-ISAM®, Foundation.2000 ™, IBM Informix® 4GL, IBM Informix® DataBlade® module, Client SDK™, Cloudscape™, Cloudsync™, IBM Informix® Connect, IBM Informix® Driver for JDBC, Dynamic Connect™, IBM Informix® Dynamic Scalable Architecture™ (DSA), IBM Informix® Dynamic Server™, IBM Informix® Enterprise Gateway Manager (Enterprise Gateway Manager), IBM Informix® Extended Parallel Server™, i.Financial Services™, J/Foundation™, MaxConnect™, Object Translator™, Red Brick® Decision Server™, IBM Informix® SE, IBM Informix® SQL, InformiXML™, RedBack®, SystemBuilder™, U2™, UniData®, UniVerse®, wIntegrate® are trademarks or registered trademarks of International Business Machines Corporation.

Java and all Java-based trademarks and logos are trademarks or registered trademarks of Sun Microsystems, Inc. in the United States and other countries.

Windows, Windows NT, and Excel are either registered trademarks or trademarks of Microsoft Corporation in the United States and/or other countries.

UNIX is a registered trademark in the United States and other countries licensed exclusively through X/Open Company Limited.

Other company, product, and service names used in this publication may be trademarks or service marks of others.

This product includes cryptographic software written by Eric Young ([email protected]).

This product includes software written by Tim Hudson ([email protected]).

Documentation Team: Claire Gustafson, Shelley Thompson, Anne Waite

US GOVERNMENT USERS RESTRICTED RIGHTS

Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.

eatures

Table of Contents

C:\ProgSeptem

Table of Contents

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

Chapter 1 External Database AccessExternal Database Access . . . . . . . . . . . . . . . . 1-2The EDA Schema Manager Steps . . . . . . . . . . . . . . 1-3The EDA Schema Manager . . . . . . . . . . . . . . . . 1-4

Create a New UniData Server Connection . . . . . . . . . . 1-5Connect to UniData Server . . . . . . . . . . . . . . 1-7

Defining a Data Source . . . . . . . . . . . . . . . . . 1-10Selecting EDA Schema Files . . . . . . . . . . . . . . . 1-14

Selecting UniData Attributes to Map . . . . . . . . . . . 1-16Selectively Mapping Attributes . . . . . . . . . . . . . 1-30

Verifying the EDA Schema . . . . . . . . . . . . . . . . 1-35Viewing the EDA Schema . . . . . . . . . . . . . . . 1-38

Viewing the DDL Scripts. . . . . . . . . . . . . . . . . 1-39Converting Data . . . . . . . . . . . . . . . . . . . 1-40

Viewing EDA Files . . . . . . . . . . . . . . . . . 1-42Listing and Selecting Data . . . . . . . . . . . . . . . . 1-43

Listing Data Using UniQuery . . . . . . . . . . . . . . 1-43Listing Data Using UniData SQL . . . . . . . . . . . . 1-44

ECL Commands for EDA . . . . . . . . . . . . . . . . 1-45Connecting to DB2 . . . . . . . . . . . . . . . . . 1-45Disconnecting from DB2 . . . . . . . . . . . . . . . 1-46Converting UniData Data to DB2 . . . . . . . . . . . . 1-46VERIFY.EDAMAP . . . . . . . . . . . . . . . . . 1-47LIST.EDAMAP . . . . . . . . . . . . . . . . . . 1-48SAVE.EDAMAP. . . . . . . . . . . . . . . . . . 1-50

EDA Exception Handling . . . . . . . . . . . . . . . . 1-52The EDA_EXCEPTION File . . . . . . . . . . . . . . 1-53

Chapter 2 Connection Pooling for UniObjects .NET and Uniobjects for

ram Files\Adobe\FrameMaker7.0\UniData 7.1C\NEWFEATURES\NEWFEATTOC.fm (bookTOC.template)ber 28, 2007 10:50 am

iv UniD

JavaConnection Pooling . . . . . . . . . . . . . . . . . . 2-2

Connection Pool Size . . . . . . . . . . . . . . . . 2-2Connection Allocation . . . . . . . . . . . . . . . 2-3

Activating Connection Pooling . . . . . . . . . . . . . . 2-4Specifying the Size of the Connection Pool . . . . . . . . . 2-4Creating Multiple Connection Pools . . . . . . . . . . . 2-4

Connection Pooling Code Example for UniObjects for .NET . . . . . 2-6Configuration File Example for UniObjects for .NET . . . . . . . 2-8Program Example for UniObjects for Java . . . . . . . . . . . 2-9UniObjects for Java Configuration File . . . . . . . . . . . . 2-13

Chapter 3 Recoverable File System on Windows PlatformsInstalling RFS . . . . . . . . . . . . . . . . . . . . 3-3New udtconfig Parameters . . . . . . . . . . . . . . . . 3-4Monitoring Performance . . . . . . . . . . . . . . . . 3-5

Chapter 4 UniXML Class for UniObjects for Java and UniObjects for .NETUniXML Class for UniObjects .NET. . . . . . . . . . . . . 4-3

UniXML – Public Instance Properties . . . . . . . . . . . 4-3UniXML – Public Instance Methods . . . . . . . . . . . 4-3UniXML – Protected Instance Methods . . . . . . . . . . 4-5

UniXML Class for UniObjects for Java . . . . . . . . . . . . 4-6Public Methods . . . . . . . . . . . . . . . . . . 4-6

Chapter 5 SSL Support in UniData ClientSupport for Secure Connections . . . . . . . . . . . . . . 5-2

In This Chapter . . . . . . . . . . . . . . . . . . 5-2UCI Configuration Parameters for ODBC and UniOLEDB. . . . . . 5-3

Secure Connection Parameters . . . . . . . . . . . . . 5-3Changing UCI Configuration Parameters . . . . . . . . . . 5-4

UniObjects ConnectionString Parameters . . . . . . . . . . . 5-8About SSL Property Lists . . . . . . . . . . . . . . . . 5-10

Creating and Maintaining SSL Property Lists . . . . . . . . 5-10List Encryption . . . . . . . . . . . . . . . . . . 5-10Loading and Decrypting an SSL Property List . . . . . . . . 5-11SSL Properties . . . . . . . . . . . . . . . . . . 5-11

Using the U2 SSL Configuration Editor . . . . . . . . . . . . 5-19Working with SSL Property Lists . . . . . . . . . . . . 5-19Starting the U2 SSL Configuration Editor . . . . . . . . . 5-19

ata 7.1 New Features

Creating a New SSL Property List . . . . . . . . . . . . . . 5-23Editing an Existing SSL Property List . . . . . . . . . . . . . 5-36Deleting an SSL Property List . . . . . . . . . . . . . . . 5-48Copying an SSL Property List . . . . . . . . . . . . . . . 5-49Renaming an SSL Property List . . . . . . . . . . . . . . . 5-52Using the Trace Feature . . . . . . . . . . . . . . . . . 5-54Using the Console/Problems View . . . . . . . . . . . . . . 5-55

Chapter 6 Transaction Processing with Non-RFS FilesTransaction Processing Commands. . . . . . . . . . . . . . 6-3

Executing TP and Non-TP Transactions . . . . . . . . . . 6-3Starting a Transaction . . . . . . . . . . . . . . . . 6-4Committing a Transaction . . . . . . . . . . . . . . . 6-5Aborting a Transaction . . . . . . . . . . . . . . . . 6-6Testing for an Active Transaction . . . . . . . . . . . . 6-8Transaction Processing Programming Example . . . . . . . . 6-8

Transaction Processing Programming Problems. . . . . . . . . . 6-9Transaction Abort . . . . . . . . . . . . . . . . . 6-9Degraded Performance . . . . . . . . . . . . . . . . 6-13

Chapter 7 Replication EnhancementsMonitoring Replication . . . . . . . . . . . . . . . . . 6-2

Starting the Replication Monitor . . . . . . . . . . . . . 6-4Replication Group Status Table . . . . . . . . . . . . . 6-7

Replication Action Trigger . . . . . . . . . . . . . . . . 6-11Replication Action Trigger Example. . . . . . . . . . . . 6-13

Table of Contents v

1Chapter

External Database Access

External Database Access . . . . . . . . . . . . . . . . 1-2The EDA Schema Manager Steps . . . . . . . . . . . . . 1-3The EDA Schema Manager . . . . . . . . . . . . . . . 1-4 Create a New UniData Server Connection . . . . . . . . . 1-5 Connect to UniData Server . . . . . . . . . . . . . . 1-7Defining a Data Source . . . . . . . . . . . . . . . . . 1-10Selecting EDA Schema Files . . . . . . . . . . . . . . . 1-14 Selecting UniData Attributes to Map . . . . . . . . . . . 1-16 Selectively Mapping Attributes . . . . . . . . . . . . . 1-30Verifying the EDA Schema . . . . . . . . . . . . . . . 1-35 Viewing the EDA Schema . . . . . . . . . . . . . . 1-38Viewing the DDL Scripts . . . . . . . . . . . . . . . . 1-39Converting Data . . . . . . . . . . . . . . . . . . . 1-40 Viewing EDA Files . . . . . . . . . . . . . . . . 1-42Listing and Selecting Data . . . . . . . . . . . . . . . . 1-43 Listing Data Using UniQuery . . . . . . . . . . . . . 1-43 Listing Data Using UniData SQL . . . . . . . . . . . . 1-44ECL Commands for EDA . . . . . . . . . . . . . . . . 1-45 Connecting to DB2. . . . . . . . . . . . . . . . . 1-45 Disconnecting from DB2 . . . . . . . . . . . . . . . 1-46 Converting UniData Data to DB2 . . . . . . . . . . . . 1-46 VERIFY.EDAMAP . . . . . . . . . . . . . . . . 1-47 LIST.EDAMAP. . . . . . . . . . . . . . . . . . 1-48 SAVE.EDAMAP . . . . . . . . . . . . . . . . . 1-50EDA Exception Handling . . . . . . . . . . . . . . . . 1-52 The EDA_EXCEPTION File . . . . . . . . . . . . . 1-53

External Database AccessExternal 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).

You must create an EDA Map Schema to define the translation between UniData and the external database model, which may differ from the UniData model. Additionally, the UniData dictionary record does not fully describe the data it defines. For example, the UniData dictionary record does not define the data type.

In order to use EDA, you must have the DB2 client installed on the machine where you are running UniData. In addition, you must be able to access the DB2 server where you want the data to reside using that DB2 client.

For detailed information about EDA, see External Database Access (EDA).

External Database Access 1-2

The EDA Schema Manager StepsThe conversion of UniData files to DB2 tables and views is shown in the following diagram:

The EDA Schema Manager performs the following steps when converting UniData files to the DB2 database:

1. The EDA Schema Processor receives information from the UniData Dictionary file for the data file you are converting and other user input.

2. From this information, the EDA Schema Processor creates an EDA Schema. This EDA Schema is a record in the _EDAMAP_ file.

3. Optionally, you can verify the EDA Schema.4. The conversion process uses the EDA Schema record and the UniData

physical file to create tables and views in the DB2 database.5. The UniData physical file is replaced by an EDA file in the UniData

account. The original data file is saved under filename.edasave.

1-3 UniData 7.1 New Features

The EDA Schema ManagerUse the EDA Schema Manager to create a mapping file, called EDA Schema, for a UniData file you are converting to the DB2 database. You then convert UniData data to DB2 using this mapping file.

To access the EDA Schema Manager, from the Start menu, select Programs, then select IBM U2, then select UniData Tools, then click EDA Tool. The EDA Schema Manager appears, as shown in the following example:

The EDA Schema Manager 1-4

Create a New UniData Server ConnectionTo create a new UniData server connection, right-click U2 Servers, then click New U2 Server. A dialog box similar to the following example appears:

Enter Database Name

In the Name box, enter a unique identifier for the new server.

Enter Host Name

In the Host box, enter the network name of the host computer where the UniData database resides, or the IP address.

Select the Database

Select the type of database where the data resides. Valid choices are UniData or UniVerse.


If you want to define the protocol type, RPC port number, RPC service name, or the login account, click Advanced. A dialog box similar to the following example appears:

Protocol Type

In the Protocol Type box, choose the type of communication you are using the server. You can choose Default, TCP/IP, or Lan Manager. The default is TCP/IP.

RPC Port Number

In the RPC Port # box, enter the port number of the UniRPC server running on the host. The default port number is 31438.

RPC Service Name

In the RPC Service Name box, enter the name of the RPC service on your system. For UniData, this is normally udcs.


Login Account

In the Login Account box, enter the name of the account to which you want to log on when accessing UniData.

Click Finish to establish the UniData server. The new server appears in the U2 Servers area of the EDA Schema Manager, as shown in the following example:

Connect to UniData ServerTo connect to the UniData Server, right-click the server name, then click Connect.


When you connect to the server, the Connect to U2 Server dialog box appears, as shown in the following example:

In the User ID box, enter the User ID for the machine where UniData is running, then enter the corresponding password in the Password box, then click Finish.


The Accounts and existing Data Source definitions appear in the U2 Server area, as shown in the following example:


Defining a Data SourceYou must define a data source pointing to the DB2 database to which you want to connect.

To define a new data source, connect to your UniData server, right-click Data Sources, then click New EDA Data Source. The Create a New EDA Data Source dialog box appears, as shown in the following example:

In the Enter Data Source Name box, enter a unique name for the DB2 data source, then click Finish.

Defining a Data Source 1-10

A data source information dialog box appears in the right pane of the EDA Schema Manager window, as shown in the following example:

In the External DB Name box, enter the name of the DB2 database to which you are connecting.

In the Driver box, enter the type of driver. At this release, UniData supports only the DB2-1NF driver.


Click Add. The EDA Data Source Connection dialog box appears, as shown in the following example:

In the Login User ID box, enter the user ID on the DB2 server.

In the Password box, enter the password corresponding to the User ID. Enter the password again in the Re-enter Password box.

If you want to maintain the connection to the DB2 server after a DB2 transaction commits, select YES in the Hold Flag box. If you want to disconnect from the DB2 server after the transaction commits, select NO in this box.

Note: If you do not use UniBasic transactions, each UniData database operation, such as a READ or WRITE, corresponds to a DB2 transaction.

In the Qualified Users box, enter the UniData user IDs of users who can access the DB2 server from the UniData account using the DB2 Login User ID you specify. Separate the users by a “|” symbol. If all UniData users can access the DB2 account, enter an asterisk (“*”).

Defining a Data Source 1-12

The following example shows a completed EDA Data Source dialog box:

To test the connection to the DB2 instance, click Test. If the connection is successful, a message similar to the following example appears:

From the File menu, click Save to save your data source definition, or click the Save icon.


Selecting EDA Schema FilesFrom the EDA Schema Manager, expand Accounts, expand the UniData account where the files you want to convert reside, right-click the EDA Schema Files, then click New EDA Map Schema. The Create New EDA Map Schema dialog box appears, as shown in the following example:

Selecting EDA Schema Files 1-14

In the Map Name box, enter a unique name for the EDA schema. Select EDA Schema for the Map Format, then click Next. The Source U2 file dialog box appears, as shown in the following example:

In the file list, highlight the UniData file for which you are creating a schema.

If you want to map each field in the UniData file, click Full Column Mapping. If you want to select the fields in the UniData file for the schema, click Selective Column Mapping.

Note: If you select Full Column Mapping, Unidata only maps D-type attributes. You must map virtual attributes manually.


In addition, you cannot map unassociated multivalued or multi-subvalued virtual attributes. You also cannot map associations that contain only virtual attributes.

In the Using Data Source box, select the DB2 data source for the EDA schema.

The EDA Map Schema dialog box appears, as shown in the following example:

Selecting UniData Attributes to MapEach UniData dictionary record appears in the U2 File Dictionary portion of the window. A red arrow next to the dictionary item indicates that the dictionary record has been mapped in the EDA Schema. Those dictionary items that have been mapped appear in the EDA Map Schema portion of the window.


View Attribute Details

To view the details of a mapped attribute, click the attribute you want to view from the EDA Map Schema portion of the dialog box. For example, the following window appears if you click the DIRECTOR attribute:

The Attribute Details area of the screen displays information about the attribute you selected.

The Name box displays the name of the mapped attribute.


The Type box displays the type of attributes. Valid types at this release of UniData are:

DATA – any value allowed by the data type you specifyEXPRESSION – used for virtual attributes only. Enter the SQL expression for the virtual attribute in the Expr Body box, such as FNAME CONCAT ‘ ‘ CONCAT LNAMEID DATA – the primary key in the DB2 tableNOT NULL DATA – specifies that the DB2 column cannot contain the null valueSCALAR FUNCTION – used to define a scalar function to execute an equivalent virtual attribute on the DB2 database. For information about creating a scalar function, see “Scalar Function Example” on page 19.TABLE FUNCTION – used to define a table function For information about creating a table function, see “Table Function Example” on page 24.TRANS – used for virtual attributes containing a TRANS clause only. If you specify TRANS, you must also specify Reference and ParametersUNIQUE DATA – specifies that values in the DB2 column must be unique

The Data Type box displays the data type for the mapped attribute. The EDA Schema Manager automatically converts the data type based on the dictionary record. If an application attempts to insert or update a DB2 attribute with a value that does not match the data type you define, the EDA system rejects the operation.The Reference box applies to a virtual attribute This value should be the name of the column the TRANS function references in the DB2 table, or the reference for a scalar or table function. The Expr Body box applies to virtual attributes that contain a user-defined function or expression. Use the Expr Body box to enter the equivalent SQL statement for the expression or function.The Indexed box indicates if you want to create an index on the mapped DB2 attribute. If you want to specify the name of the DB2 index, enter the following in the Index box:REMOTE [DB2_indexname]If you do not specify the DB2 index name, the EDA process generates one.


The Parameters box specifies the attribute or expression in the function that returns the record ID in the table you are referencing in DB2.

Scalar Function Example

Assume you have the following virtual attribute defined for the STUDENT file in your UniData database:

:AE DICT STUDENT UPCASE.LNAMETop of "UPCASE.LNAME" in "DICT STUDENT", 6 lines, 25 characters.001: V002: UPCASE(LNAME)003:004:005: 30L006: S

This virtual attribute converts the student’s last name to uppercase.

To convert this virtual attribute to a scalar function using the EDA Tool, drag UPCASE.LNAME from the U2 File Dictionary pane under STUDENT in the EDA Map Schema pane, as shown in the following example:

In the Attribute Details portion of the window, change the Type to SCALAR FUNCTION.

Define the data type for the output in the Data Type box.


In the Reference box, enter the DB2 function and data type for the value you are passing to the function. In this example, the DB2 system function corresponding to the UniData UPCASE function is UCASE, which resides in the SYSFUN Schema in the DB2 database. Enter the following formula in the Reference box:

SYSFUN.UCASE(VARCHAR(30))

In the Parameters box, click the plus sign (“+”) and enter the field to pass to the scalar function. The Attribute Details should now look like the following example:

The following example illustrates the output from UniData when you execute this scalar function:

:LIST STUDENT UPCASE.LNAMELIST STUDENT UPCASE.LNAME 10:57:37 Mar 14 2005 1STUDENT... .............................

424325656 MARTIN414446545 OFFENBACH978766676 MULLER221345665 MILLER291222021 SMITH5 records listed


The next example illustrates a user-defined scalar function. Assume you have the following UniData virtual attribute defined in the dictionary of the STUDENT file:

001: V002: TRANS('COURSES',COURSE_NBR,'TEACHER','X')003:004: Teacher005: 10L006: MS007: CGA

This virtual attribute executes a translate from the STUDENT file to the COURSES file and returns TEACHER.

To convert this virtual attribute to a scalar function using the EDA Tool, drag TEACHER from the U2 File Dictionary pane under the COURSES node of STUDENT in the EDA Map Schema pane, as shown in the following example:


Click TEACHER in the EDA Map Schema portion of the window to define the Attribute Details for this function. The following example illustrates the details of the TEACHER function:

In the Attribute Details portion of the window, change the Type to SCALAR FUNCTION.

Define the data type for the output in the Data Type box.

Because this function is not a DB2 system function, you must define the schema and function name where you want to store the user-defined function in the DB2 external database. In the Reference box, enter the name and location where you want to store the function, as well as the data type for the value you are passing to the function. In this example, the function will be named GET_TEACHER in the STUDENT2 Schema.

In the Expr Body box, enter the expression body for the scalar function, as shown in the following example:

F1:BEGIN ATOMIC RETURN SELECT DISTINCT TEACHER FROM COURSES.COURSES AS B WHERE B.ID=COURSE_NBR; END

Note: For information about creating DB2 user-defined functions, see the IBM DB2 documentation.


In the Parameters box, click the plus sign (“+”) and enter the field to pass to the scalar function. In this example, COURSE_NBR is passed to the scalar function.

The following example illustrates output from the TEACHER scalar function:

LIST STUDENT SEMESTER COURSE_NBR TEACHER 15:21:17 Mar 14 2005 1STUDENT... Term Crs # Teacher...

221345665 FA93 EG110 Carnes MA220 Otis PY100 Masters SP94 EG140 Aaron EG240 Carnes MA221 Otis291222021 SP94 FA100 Fried414446545 FA93 CS104 Aaron MA101 Otis FA100 Fried SP94 CS105 Gibson MA102 Otis PY100 Masters424325656 SP94 PY100 Masters PE100 Fisher978766676 FA93 FA120 Fried FA230 Carnes HY101 Otis SP94 FA121 Carnes FA231 Fried

Table Function Example

UniData allows you to use the DB2 table function concept to evaluate multiple virtual attributes at the same time. In some cases, you may be able to map more than one virtual attribute with one DB2 user-defined table function.


Assume you create a monthly report containing the student names, semesters, course names, and credit hours. To create this report from UniData, you use the following virtual attributes for course name and credit hours:

:AE DICT STUDENT COURSE_NAME001: I002: TRANS('COURSES',COURSE_NBR,'NAME','X')003:004: Course Name005: 25L006: MS007: CGA

:AE DICT STUDENT COURSE_CREDITS001: V002: TRANS('COURSES',COURSE_NBR,'CREDITS','X')003:004: Credits005: 5R006: MS007: CGA

To map these virtual attributes, drag each one from the U2 File Dictionary pane to the CGA_MS node in the EDA Map Schema pane, as shown in the following example:

Although you map COURSE_NAME and COURSE_CREDITS separately, DB2 allows you to create one function for use with multiple attributes. You have to define the EDA Map Schema for both virtual attributes, but you only have to define the function once.

The following example illustrates how you would use a DB2 table function in order to evaluate both COURSE_NAME and COURSE_CREDITS on the DB2 database.


First, let’s map the COURSE_NAME virtual attribute:.

In the Attribute Details portion of the window, change the Type to TABLE FUNCTION.

In the Data Type box, enter the data type for the output of the attribute you specified in the Name box.

In the Reference box, enter the DB2 Schema name, the name of user-defined function you are defining in the Expr Body box, the data type for the input value, and the DB2 function attribute name, as shown in the following example:

STUDENT2.GET_COURSE(VARCHAR(5))/NAME

In this example. the user-defined function will be named GET_COURSE and reside in the STUDENT2 schema in the DB2 database. The data type of the input parameter is VARCHAR(5), and you are using the output parameter NAME.

In the Expr Body box, enter the table function body. In this example, the function is defined as:

F1:BEGIN ATOMIC RETURN SELECT B.NAME, B.CREDITS FROM COURSES.COURSES AS B WHERE B.ID=COURSE_NBR; END


In the Parameters box, click the plus sign (“+”) to define the parameter to pass to the table function and the output parameters you want to return. For output param-eters, you specify OUTPUT, the name of the attribute to return, and the data type. In this example, the output parameters are defined as:

OUTPUT NAME VARCHAR(50)OUTPUT CREDITS VARCHAR(10)

The following example shows the DDL scripts UniData creates for this table function:

CREATE FUNCTION STUDENT3,GET_COURSE(COURSE_NBR VARCHAR(5)) RETURNS TABLE(NAME VARCHAR(50),CREDITS VARCHAR(10)) F1:BEGIN ATOMIC RETURN SELECT B.NAME,B.CREDITS FROM COURSES.COURSES AS B WHERE B.ID=COURSE_NBR; END

Next, let’s map the COURSE_CREDITS virtual attribute.

Click the COURSE_CREDITS attribute. The following example illustrates the Attribute Details for this attribute:

In the Attribute Details portion of the window, change the Type to TABLE FUNCTION.

In the Data Type box, enter the data type for the output of the attribute you specified in the Name box.


In the Reference box, enter the DB2 Schema name, the name of user-defined function you previously defined in the COURSE_NAME table function (GET_COURSE), the data type for the input value, and the DB2 function attribute name, as shown in the following example:

STUDENT2.GET_COURSE(VARCHAR(5))/CREDITS

In this example. the user-defined function GET_COURSE resides in the STUDENT2 schema in the DB2 database. The data type of the input parameter is VARCHAR(5), and you are using the output parameter CREDITS.

Since you previously defined the GET_COURSE function, you do not need to enter data in the Expr Body.

In the Parameters box, click the plus sign (“+”) to define the parameter to pass to the table function. You do not need to define the output parameters since they were previously defined in the GET_COURSE function.

You can now create the monthly report listing the student names, semesters, course names, and credit hours. Since you defined COURSE_NAME and COURSE_CREDITS using the same DB2 table function, DB2 only needs to evaluate the function once, improving performance.

LIST STUDENT NAME SEMESTER COURSE_NAME COURSE_CREDITS 14:40:18 MSTUDENT... NAME........... Term Course Name.............. Hours

221345665 BW FA93 Engineering Principles 5 Calculus- I 5 Introduction to Psycholog 3 y SP94 Fluid Mechanics 3 Circut Theory 3 Calculus - II 5291222021 FA SP94 Visual Thinking 3414446545 PY FA93 Database Design 3 Math Principals 3 Visual Thinking 3 SP94 Database Design 3 Algebra 3 Introduction to Psycholog 3 y424325656 EG SP94 Introduction to Psycholog 3 y Golf - I 3978766676 PY FA93 Finger Painting 5 Photography Principals 3


Selectively Mapping AttributesIf you want to selectively map UniData attributes to DB2, click Selective Column Mapping in the Create New EDA Map Schema dialog box. A window similar to the following example appears in the right pane of the EDA Schema Manager:

The only UniData attribute that the EDA system automatically maps is @ID. To select a UniData attribute to map, click the attribute in the U2 File Dictionary portion of the window, drag it to the EDA Map Schema portion of the window, and drop it under the appropriate file.

Warning: Be careful to drop attributes appropriately according to their singlevalued or multivalued definition to ensure that multivalued and multi-subvalued attributes are correctly mapped to DB2 tables. If you are not sure of the proper structure, use Full Column Mapping instead of Selective Mapping, then delete the attributes you do not want to map in the EDA Map Schema window.


The following example illustrates the appearance of the window after the DIRECTOR attribute has been dragged to the EDA Map Schema portion of the window. Notice that a red arrow appears next to the attribute in the U2 File Dictionary portion of the window, indicating the attribute has been mapped.

Attribute Details

In the Attribute Details portion of the window, define the mapping details for the attribute you selected.

Note: You can change the name, type, data type, formatting, Database name, Namespace, and Data source. Namespace refers to the DB2 schema name where the conversion process will create the corresponding DB2 tables and views.

The Name attribute is the name of the column in the resulting DB2 table.In the Type box, select the type of attribute.In the Data Type box, enter the data type for the attribute. In this case, the data type is VARCHAR.


The Reference box is used for V-type attributes that contain a TRANS clause. Enter the name of the DB2 table TRANS clause reference in this box.For example, if you are mapping the COURSE_HOURS attribute from the STUDENTS file, drag the attribute under CGA_MS, as shown in the fol-lowing example:

As you can see in the Mapped U2 Fields portion of the window, this attribute contains a TRANS function to the COURSES file. In the Reference box, enter the D2 table and column where the EDA COURSES file was mapped, in this case, COURSES.COURSES/CREDITS.


In the Parameters box, specify the attribute or expression in the TRANS function that returns the record ID in the table you are refer-encing in DB2. For example, the record ID for COURSE_HOURS is COURSE_NBR. Click the plus sign (“+”) in the Parameters portion of the window. Enter COURSE_NBR in the Parameter box, as shown in the following example:


If the attribute is an expression, enter the SQL expression in the Expr Body box. For example, the NAME attribute in the CLIENTS file concatenates the first name, space, and last name attributes, In the expression box, enter the corresponding SQL statement for this attribute, as shown in the following example:

In the Formatting box, select the appropriate format for the attribute.The Index box is not supported at this release of UniData.


Verifying the EDA SchemaAfter you have created an EDA Schema, you can verify the EDA Schema. To verify the EDA Schema, click the Verify icon on the toolbar, as shown in the following example:

Verify icon


A dialog box similar to the following example appears:

To verify the EDA Schema, click the type of verification to execute. Valid options are:

Syntax – Verifies the syntax of the SQL statements to create the DB2 tables is correct.Metadata – Verifies that all the metadata required to create the DB2 tables exists.

Verifying the EDA Schema 1-34

Data – Verifies that the UniData data meets the requirements for the DB2 tables. You can select one of the following options when verifying your data:

All records – analyzes each record in the UniData data fileSpecified records – you can enter specific record IDs to analyze. Separate each record ID with a right parentheses (}).First n records – the system verfies the first n records you specify.Every n-th record – the system verfies every n-th record you specify.

Verification Example

The following example shows a listing from the UniData STUDENT file:

LIST STUDENT ALL 16:35:46 Feb 24 2005 1STUDENT..... Last Name...... First Name Major Minor Advisor. Term Crs # GD.

521-81-4564 SMITH Harry CH PSYCH Carnes FA93 CS130 AIATRY

CS100 B PY100 B SP94 CS131 B CS101 B PE220 A 424-32-5656 Martin Sally PY EG Fried SP94 PY100 C PE100 C 414-44-6545 Offenbach Karl CS PY Otis FA93 CS104 D MA101 C FA100 C SP94 CS105 B MA102 C PY100 C 978-76-6676 Muller Gerhardt FA PY Carnes FA93 FA120 A FA230 C HY101 C SP94 FA121 A FA231 B HY102 I 221-34-5665 Miller Susan EG BW Otis FA93 EG110 C MA220 B PY100 B SP94 EG140 B EG240 B MA221 B 291-22-2021 Smith jojo CS FA Eades SP94 FA100 B


Notice that the Minor attribute for Record ID 521-81-4564 exceeds the specified length of 8 characters. When you verify the data the the EDA Map Schema, the following error message appears:

In C:\IBM\ud71\sys\CTLG\e\EDAMAPSUB at line 2056 EDA_write_tuple error, id = “521814564”In C:IBM\ud71\sys\CTLG\e\EDAMAPSUB at line 2056 EDA DB2 Driver: [IBM] [CLI Driver] CLI0109E String data right truncation, SQLSTATE=220015 records passed data verification.1 records failed on data verification.

Fix the incorrect data in the records before converting the file to an EDA file. If you do not correct the data, the record will not be converted, and will appear in the EDA_EXCEPTION file. For more information and the EDA_EXCEPTION file, see “EDA Exception Handling” on page 52.

If the verification succeeds, “Successful” appears in the dialog box. If an error occurs, the error appears in the dialog box.

Viewing the EDA SchemaIf you want to view the EDA schema, click Show Schema. The schema appears in the dialog box, as shown in the following example:

Verifying the EDA Schema 1-36

Viewing the DDL ScriptsTo view the DDL script that UniData will use to generate the data on DB2, click the DDL Scripts icon on the toolbar, as shown in the following example:

From the Get DDL Scripts dialog box, click Get DDL Scripts appear in the window, as shown in the following example:

DDL Scripts Icon


Converting DataTo convert data from Unidata to DB2, click the Convert Data icon, as shown in the following example:

Convert Icon

Converting Data 1-38

A dialog box similar to the following example appears:

Click Force if you want to drop existing tables on the external database before creating new ones.

Click Verbose to display detailed messages and the DDL scripts during the conversion process.

Click EDA Convert. If the conversion is successful, UniData reports the number of records converted to DB2. If the conversion is not successful, error messages are reported in the window.


Viewing EDA FilesTo see which files have been converted from UniData to DB2, from the EDA Schema Manager, click the plus sign next to EDA Files, as shown in the following example:

You can also determine if a file has been converted to DB2 by executing the FILE.STAT command at the ECL prompt, as shown in the following example:

UniData Release 7.1 Build: (3082)(c) Copyright IBM Corporation 2005.All rights reserved.

Current UniData home is C:\IBM\ud71\.Current working directory is C:\IBM\ud71\edatest.:FILE.STAT COURSESCOURSES is an EDA type file, FILE.STAT does not apply.

Converting Data 1-40

Listing and Selecting DataYou can use UniQuery, UniData SQL, and UniBasic to access the data on the DB2 server.

Listing Data Using UniQueryYou can use the UniQuery LIST command to view the converted data on the DB2 server, as shown in the following example:

:LIST COURSES ALLLIST COURSES ALL 15:49:53 Jan 25 2005 1COURSES... Course Name.............. Credits Teacher...

FA100 Visual Thinking 3 FriedMA101 Math Principals 3 OtisMA102 Algebra 3 OtisPY140 Abnornal Psychology 5 MastersCS100 Intro to Computer Science 3 GibsonFA120 Finger Painting 5 FriedCS101 Intro to Computer Science 4 GibsonFA121 Watercorlors 3 CarnesCS104 Database Design 3 AaronCS105 Database Design 3 GibsonMA220 Calculus- I 5 OtisMA221 Calculus - II 5 OtisFA230 Photography Principals 3 CarnesFA231 Photography Practicum 3 FriedCS130 Intro to Operating 5 James SystemsEG110 Engineering Principles 5 CarnesCS131 Intro to Operating 5 Aaron SystemsHY101 Western Civilization 3 Otis


Listing Data Using UniData SQLYou can use the UniData SQL SELECT command to view the converted data on the DB2 server, as shown in the following example:

:SQL SELECT * FROM COURSES;:SQL SELECT * FROM COURSES;Page 1COURSES Course Name Credi Teacher---------- ------------------------- ----- ----------FA100 Visual Thinking 3 FriedMA101 Math Principals 3 OtisMA102 Algebra 3 OtisPY140 Abnornal Psychology 5 MastersCS100 Intro to Computer Science 3 GibsonFA120 Finger Painting 5 FriedCS101 Intro to Computer Science 4 GibsonFA121 Watercorlors 3 CarnesCS104 Database Design 3 AaronCS105 Database Design 3 GibsonMA220 Calculus- I 5 OtisMA221 Calculus - II 5 OtisFA230 Photography Principals 3 CarnesFA231 Photography Practicum 3 FriedCS130 Intro to Operating 5 James SystemsEG110 Engineering Principles 5 CarnesCS131 Intro to Operating 5 Aaron SystemsHY101 Western Civilization 3 Otis

Listing and Selecting Data 1-42

ECL Commands for EDAThis section describes ECL commands you can use to connect to DB2 and to convert UniData data to DB2, to verify your EDA Schema, to list your EDA Schema, and to save your EDA Schema.

Connecting to DB2Use the EDA.CONNECT command to connect your EDA system to the DB2 data source. You may want to use this command if you want to connect using a log on ID and password different from the default.

If you issue the EDA.CONNECT command, UniData maintains the connection until you issue the EDA.DISCONNECT command.

Syntax

EDA.CONNECT datasource [WITH logon_name [, password]

Parameters

The following table describes each parameter of the syntax.

Parameter Description

datasource The name of the data source to which you are connecting. The datasource must exist in the EDA_DATASOURCE file.

WITH logon_name, password

The logon name on the DB2 data source. If you do not specify logon_name, UniData searches the EDA_DATASOURCE file for a qualified user. If you specify logon_name without password, UniData searches the Connection Password file and connects with logon_name and that password. If you specify both logon_name and password, UniData uses both the make the connection.

EDA.CONNECT Parameters


Disconnecting from DB2Use the EDA.DISCONNECT command to disconnect from the DB2 data source.

Syntax

EDA.DISCONNECT datasource

where datasource is the DB2 data source from which you want to disconnect.

Converting UniData Data to DB2Use the EDA.CONVERT command to convert UniData data to the DB2 database based on an EDA Schema. The conversion results in an EDA Object Set on the DB2 database. An EDA file replaces the original UniData file in the UniData database.

If the UniData file you are converting is an EDA file, the conversion process removes the file and creates the new EDA file. If the file exists but is not an EDA file, the conversion process renames the file as <filename>.edasave and creates the new EDA file.

The conversion process copies data, trigger, and index information to the new EDA file.

Syntax

EDA.CONVERT {[XMAP] eda_schema | EDA.FILE [DICT] eda_file | DEFAULT.MAP} [DATA.SOURCE data_source] [OBJECT.SET [name_space.]primary_table] [FILE.NAME target_file] [FORCE | VERBOSE]

ECL Commands for EDA 1-44

Parameters


VERIFY.EDAMAPThe VERIFY.EDAMAP command verifies the EDA schema.

Syntax

VERIFY.EDAMAP {[XMAP] eda_schema | EDA.FILE [DICT] eda_file | DEFAULT.MAP} [DATA.SOURCE data_source] [OBJECT.SET [name_space.]primary_table] [FILE.NAME target_file [METADATA]


eda_schema Specifies the name of the EDA schema to use for the conversion. The schema resides either in the _EDAMAP_ or _EDAXMAP_ file.

eda_file Specifies the name of the EDA file from which UniData extracts the EDA schema. If you specify FILE.NAME target_file, UniData uses the schema to convert target_file, UniData remaps eda_file.

DEFAULT.MAP Specifies only to map the primary key (@ID) when converting a UniData file to EDA.

data_source Specifies the data source name to use for the conversion.

primary_table Specifies the name of the primary table, containing singlevalued attributes, to use for the conversion. If you also specify name_space, UniData uses it as the DB2 schema name for the target DB2 table/view set.

target_file Specifies the name of the UniData file to convert. If you also specify eda_schema, target_file overrides the name of the UniData file contained in eda_schema. If you specify eda_file, UniData extracts the EDA schema from eda_file and uses it to convert target_file to EDA.

FORCE Specifies that all existing DB2 tables, views, indexes and user-defined functions are dropped prior to remapping the file.

VERBOSE Displays the DB2 Data Definition Language (DDL) used in the conversion process.

EDA.CONVERT Parameters


Parameters


LIST.EDAMAPThe LIST.EDAMAP command displays the EDA Schema you specify.

Syntax

LIST.EDAMAP {[XMAP] eda_schema | EDA.FILE [DICT] eda_file | DEFAULT.MAP} [DATA.SOURCE data_source] [OBJECT.SET [name_space.]primary_table] [FILE.NAME target_file] [XMAP | OBJECT.TREE | DLL]


eda_schema Specifies the name of the EDA schema to verify.

eda_file Specifies the name of the EDA file whose schema is to be extracted and verified. If you specify FILE.NAME target_file, target_name replaces the UniData file name in the schema UniData verifies.

DEFAULT.MAP Specifies to only verify the primary key (@ID) mapping, irrespective of the attributes actually mapped of the schema you specify.

data_source Specifies the data source name to use when verifying the schema.

primary_table Specifies the name of the primary table, containing only singl-evalued attributes, to use when verifying the schema. If you also specify name_space, UniData uses it as the DB2 schema name.

target_file Specifies the name of the UniData file to use when verifying the schema.

METADATA Connects to the DB2 database and verifies the metadata on that database.

VERIFY.EDAMAP Parameters


Parameters


SAVE.EDAMAPThe SAVE.EDAMAP command saves the EDA schema in a schema file in either the EDAMAP or EDAXMAP format.


eda_schema Specifies the name of the EDA schema to display.

eda_file Specifies the name of the EDA file whose schema is to be extracted and displayed. If you specify FILE.NAME target_file, target_name replaces the UniData file name in the schema UniData displays.

DEFAULT.MAP Specifies to only display the primary key (@ID), irrespective of the attributes actually mapped of the schema you specify.

data_source Specifies the data source name to use when displaying the schema.

primary_table Specifies the name of the primary table, containing only singl-evalued attributes, to use when displaying the schema. If you also specify name_space, UniData uses it for Name Space (DB2 Schema Name) in the display.

target_file Specifies the name of the UniData file to use when displaying the schema.

XMAP Specifies to display the EDA schema in XML format.

OBJECT.TREE Specifies to display the logical tree structure of the DB2 table and view.

DDL Specifies to display the DB2 Data Definition Language (DDL) statements used in the conversion process.

LIST.EDAMAP Parameters


Syntax

SAVE.EDAMAP {[XMAP] eda_schema | EDA.FILE [DICT] eda_file | DEFAULT.MAP} [DATA.SOURCE data_source] [OBJECT.SET [name_space.]primary_table] [FILE.NAME target_file] TO [XMAP] <schema_name>

Parameters



eda_schema Specifies the name of the EDA schema to save.

eda_file Specifies the name of the EDA file whose schema is to be saved. If you specify FILE.NAME target_file, target_name replaces the UniData file name in the schema UniData displays.

DEFAULT.MAP Specifies to only save the primary key (@ID) mapping, irrespective of the attributes actually mapped of the schema you specify.

data_source Specifies the data source name to use when saving the schema.

primary_table Specifies the name of the primary table, containing only singlevalued attributes to use when saving the schema. If you also specify name_space, UniData uses it for Name Space (DB2 Schema Name).

target_file Specifies the name of the UniData file to use when saving the schema.

TO Defines where to store the Map Schema, and the format in which to save it. If you specify XMAP, UniData saves the Map Schema in the EDAXMAP format. If you do not specify this parameter, UniData saves the map schema in the EDAMAP format.

schema_name The record ID of the EDA Schema.

SAVE.EDAMAP Parameters


EDA Exception HandlingExceptions can occur when an INSERT, DELETE, or UPDATE operation fails on the external database tables, or when UniData cannot convert a record to the external database tables.

Note: IBM recommends that you verify data and correct any exceptions prior to converting your data to an external database. For more information about data verification, see “Verifying the EDA Schema” on page 35.

Following are the EDA exceptions that can occur:

Inserting or updating a record with the field length longer than the length defined in the EDA table.Inserting or updating a record with an incorrect data type value that the system cannot automatically convert to the data type defined in the EDA table.Inserting or updating a multivalued or multi-subvalued attribute to a singl-evalued attribute, or storing a multi-subvalued attribute to a multivalued attribute.Inserting or updating a record containing an unmapped field when UNMAPFIELD has been disabled in the EDA Map Schema.The operation violates defined constraints.

When UniData detects an exception, the following events occur:

If you are converting data, the conversion process loads data to the EDA file after it generates the metadata.UniData inserts or updates data to the EDA file at runtime.UniData deletes the EDA file record at runtime.

You can turn exception processing on and off with EDA.EXCEPTION command.

Syntax

EDA.EXCEPTION [ON | OFF]


The EDA_EXCEPTION FileUniData records exceptions occuring during the conversion process or an INSERT, UPDATE, or DELETE operation in the EDA_EXCEPTION file.

The EDA_EXCEPTION file is a multilevel file, with each subfile relating to one EDA data source. The name of the subfile is EDA_datasource. The EDA_EXCEPTION file resides in /udthome/sys on UniData for UNIX and \udthome\sys on UniData for Windows Platforms.

The following table describes each attribute of the EDA_EXCEPTION file.

Location Attribute Name Description

0 @ID The ID of the exception record. The ID concatenates the process ID, timestamp, and a sequential number.

1 ACCOUNT The full path to the account where the data record resides.

2 FILE_NAME The name of the EDA file where the exception happened.

3 FULL_PATH The full path of the EDA file.

4 UID The user ID of the user generating the exception.

5 DATE The date the exception occurrred.

6 TIME The time the exception occurred.

7 ERROR_MSG The error message returned from the external database.

8 OPERATION The operation causing the exception. Valid values are EDA.CONVERT, UPDATE, INSERT, or DELETE.

9-13 Reserved for future enhancements

14 - n REC_START The data record causing the exception.

EDA_EXCEPTION File Attributes

EDA Exception Handling 1-50

Example

In the following example, one record from the UniData STUDENT file failed be converted to DB2:

In C:\IBM\ud71\sys\CTLG\e\EDAMAPSUB at line 2056 EDA_write_tuple error, id = “521814564”In C:IBM\ud71\sys\CTLG\e\EDAMAPSUB at line 2056 EDA DB2 Driver: [IBM] [CLI Driver] CLI0109E String data right truncation, SQLSTATE=220015 records passed data verification.1 records failed on data verification.

The next example lists the record in the EDA_EXCEPTION file corresponding the conversion failure above:

LIST EDA_EXCEPTION,EDA_silver ALL 14:45:03 Feb 25 2005 1EDA_EXCEPTION 1356-1109367719-1ACCOUNT PATH C:\IBM\ud71\edatestEDA VOC NAME STUDENTEDA FILE PATH C:\IBM\ud71\edatest\STUDENTUSER NAME AdministratorsEXCEPTION DATE 25 Feb 2005EXCEPTION TIME 14:41:59EDB MESSAGE EDA DB2 Driver: [IBM][CLI Driver] CLI0109E String data right truncation. SQLSTATE=22001

EXCEPTION OP CONVERTRECORD @ID 521814564

1 record listed


2Chapter

Connection Pooling for UniObjects .NET and Uniobjects for Java

Connection Pooling . . . . . . . . . . . . . . . . . . 2-2 Connection Pool Size . . . . . . . . . . . . . . . . 2-2 Connection Allocation . . . . . . . . . . . . . . . 2-3Activating Connection Pooling . . . . . . . . . . . . . . 2-4 Specifying the Size of the Connection Pool . . . . . . . . . 2-4 Creating Multiple Connection Pools . . . . . . . . . . . 2-4Connection Pooling Code Example for UniObjects for .NET . . . . . 2-6Configuration File Example for UniObjects for .NET . . . . . . . 2-8Program Example for UniObjects for Java . . . . . . . . . . . 2-9UniObjects for Java Configuration File . . . . . . . . . . . . 2-13

Connection PoolingUniData 7.1 supports connection pooling with UniObjects for Java and UniObjects for .NET.

The term connection pooling refers to the technology that pools permanent connec-tions 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.

You can activate connection pooling in your program, or activate it through a config-uration file.

Connection Pool SizeYou can set the minimum and maximum size of the connection pool either in your program or through a configuration file. 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.

License Considerations

The actual size of a connection pool depends on the pooling licenses available on the server. For example, if you set a connection pool to a minimum size of 2 and a maximum size of 100, and you have 16 licenses available, the maximum connection pool size will be 16. If you only have 1 license available, UniData does not create the connection pool at all, since the minimum size of 2 cannot be met.

Connection Pooling 2-2

Connection AllocationOnce UniData allocates a pooled connection to a thread, the connection remains exclusively attached to that thread until it is explicitly freed by the thread.

UniData does not “clean up” the pooled connection before allocating it to a user thread with the same credentials. For example, UDT.OPTIONS settings, unnamed common, environment variables, and so forth remain from previous use.


Activating Connection PoolingTo activate connection pooling, use the UniObjects.UOPooling statement in your program, as shown in the following example.,

UniObjects.UOPooling = true;

Specifying the Size of the Connection PoolTo specify the size of the connection pool, use UniObjects.MinPoolSize to define the minimum number of connections, and the UniObjects.MaxPoolSize to define the maximum number of connections, as shown in the following example:

UniObjects.MinPoolSize = 1;UniObjects.MaxPoolSize = 10;

If you do not specify the minimum and maximum number of connections, UniData defaults to 1 for the minimum and 10 for the maximum.

Creating Multiple Connection PoolsYou can create as many connection pools as you like by issuing multiple UniOb-jects.OpenSession commands in your program. You must specify different credentials for each connection pool.

UniObjects.OpenSession(server_name, logon_name, password,account,service_name)



server_name The name of the server to which you are connecting.

logon_name The logon name of the user connecting to the server.

UniObjects.OpenSession Parameters

Activating Connection Pooling 2-4

When you close a session using connection pooling, UniData does not close the connection, it makes the connection available in the connection pool.

password The password corresponding to the logon_name.

account The account on the server to which you are connecting.

service_name This parameter is optional. The name of the rpc service. If you do not specify service_name, UniData defaults to defcs. If you do specify service_name, the service name must exist in the unirpcservices file.


UniObjects.OpenSession Parameters (continued)


Connection Pooling Code Example for UniObjects for .NETThe following example illustrates using connection pooling in a program:

using System;using IBMU2.UODOTNET;using System.Threading;

namespace CPTest{

class CPTest{

[STAThread]static void Main(string[] args){

UniSession us1=null;try{

UniObjects.UOPooling = true;UniObjects.MinPoolSize = 1;UniObjects.MaxPoolSize = 10;us1 =

UniObjects.OpenSession("localhost","username","password","demo","udcs");UniCommand cmd = us1.CreateUniCommand();cmd.Command="SSELECT STATES";cmd.Execute();string response_str = cmd.Response;Console.WriteLine(" Response from UniCommand

:"+response_str);UniSelectList sl = us1.CreateUniSelectList(0);while (!sl.LastRecordRead){

string s = sl.Next();if (s != ""){

Console.WriteLine(" Record ID : "+s);}

}}catch(Exception e){

if(us1 != null && us1.IsActive){

UniObjects.CloseSession(us1);us1= null;

}Console.WriteLine("");Console.WriteLine(Thread.CurrentThread.Name +" : Connection

failed in Test Program : " + e.Message +e.StackTrace);

Console.WriteLine("===============================================================================");

Console.WriteLine("============================================================================");

}

Connection Pooling Code Example for UniObjects for .NET 2-6

finally{

if(us1 != null && us1.IsActive){

Console.WriteLine("");Console.WriteLine(Thread.CurrentThread.Name +" :

Connection Passed in Test Program");



UniObjects.CloseSession(us1);}

} }

}}


Configuration File Example for UniObjects for .NETThe following example illustrates a configuration file for connection pooling. This configuration file is named either app.config or web.config.

<?xml version=”1.0” encoding=”utf-8” ?> - <configuration> - <UO.NET> - <General> <add key=”SocketTimeOut” value=”300000” /> </General> - <ConnectionPooling>

<add key=”ConnectionPoolingOn” value=”1” /><add key=”MinimumPoolSize” value=”1” /><add key=”MaximumPoolSize” value=”16” /> <add key=”IdleRemoveThreshold” value=”300000” /><add key=”IdleRemoveExecInterval” value=”6000” /><add key=”OpenSessionTimeout” value=”30000” />

</ConnectionPooling> - <PerformanceMonitor>

<add key=”BusyConnectionCounter” value=”0” /> </PerformanceMonitor> </UO.NET> - -<system.diagnostics> + <switches> - <trace autoflush=”true” indentsize=”4”> - <listeners>

<add name=”myListener” type=”System.Diagnostics.TextWriterTraceListener” initializeData=”c:\temp\myListener.log” />

</listeners> </trace> </system.diagnostics> </configuration>

Configuration File Example for UniObjects for .NET 2-8

Program Example for UniObjects for JavaThe following example illustrates using connection pooling in a program for UniObjects for Java:

/* * Created on Jun 15, 2005 * * To change the template for this generated file go to * Window>Preferences>Java>Code Generation>Code and Comments */package asjava.uniCPTest;import java.io.IOException;import java.util.Date;import asjava.uniclientlibs.*;import asjava.uniobjects.*;/** * @author nikk * * To change the template for this generated type comment go to * Window>Preferences>Java>Code Generation>Code and Comments */public class CPTest {

CPTest() {};static Thread[] threads = null;static int m_NumberOfThreads = 0;static String numberOfThreads;static String _hostName;static String _userName;static String _passWord;static String _accountPath;static String _dataSourceType = "Unknown";static boolean goodResponse = false;static String response = null;static String _minPoolSize;static String _maxPoolSize;

public static void main(String args[]) throws IOException, Throwable {if (_hostName == null) {

_hostName = inputString("Host Name:");}if (_userName == null) {

_userName = inputString("User Name:");}if (_passWord == null) {

_passWord = inputString("User Password:");}if (_dataSourceType.equals("Unknown")) {

goodResponse = false;while (goodResponse == false) {

response =inputString("Is Server UniVerse" + " or UniData (V/D):");

if (response.equalsIgnoreCase("V")) {_dataSourceType = "UNIVERSE";goodResponse = true;

} else if (response.equalsIgnoreCase("D")) {


_dataSourceType = "UNIDATA";goodResponse = true;

} else {System.out.println("... Enter V or D");

}}

}if (_accountPath == null) {

_accountPath = inputString("Account Path:");}if (_minPoolSize == null) {

_minPoolSize = inputString("Min Pool Size:");}if (_maxPoolSize == null) {

_maxPoolSize = inputString("Max Pool Size:");}if (numberOfThreads == null) {

numberOfThreads =inputString("Number of Simultaneous Connections : ");

}m_NumberOfThreads = Integer.parseInt(numberOfThreads);long lStartTime = new Date().getTime();ConcurrentTest2();for (int i = 0; i < m_NumberOfThreads; i++) {

threads[i].join();}// Console.WriteLine("Program Finished" + DateTime.Now);long ldiff = (new Date().getTime() - lStartTime);System.out.println("Total Time : " + ldiff + " Milliseconds");System.in.read();

}public static String inputString(String msg) throws IOException {

String userInput;byte bArray[] = new byte[128];int bytesRead;System.out.print(msg);bytesRead = System.in.read(bArray);userInput = new String(bArray, 0, bytesRead);// remove trailing CR/LF and any other leading or trailing white// spaceuserInput = userInput.trim();return (userInput);

}private static void ConcurrentTest2() {

int nIndex = m_NumberOfThreads;threads = new Thread[nIndex];for (int i = 0; i < nIndex; i++) {

Thread t = new Thread(new ThreadStart());threads[i] = t;

}for (int i = 0; i < nIndex; i++) {

threads[i].setName("MyThreadProc" + (i + 1));threads[i].start();

}}static class ThreadStart implements Runnable {

UniSession us1 = null;UniJava j = null;public void run() {

try {

Program Example for UniObjects for Java 2-10

// UniJava.setIdleRemoveThreshold(20000);// UniJava.setIdleRemoveExecInterval(20000);j = new UniJava();// you can comment out below lines and set the Connection

Pooling using // Configuration file called "uoj.properties". This way you

do not have to // change the code. Put "uoj.properties" file in current

working directory.// Installation contains "uoj.properties" file.UniJava.setUOPooling(true);Integer minSize = Integer.decode(_minPoolSize);Integer maxSize = Integer.decode(_maxPoolSize);UniJava.setMinPoolSize(minSize.intValue());UniJava.setMaxPoolSize(maxSize.intValue());// it will create trace file (uoj_trace.log)in current

working directoryUniJava.setPoolingDebug(true);us1 = j.openSession();us1.setHostName(_hostName);us1.setUserName(_userName);us1.setPassword(_passWord);us1.setAccountPath(_accountPath);if (_dataSourceType.equals("UNIDATA")) {

us1.setConnectionString("udcs");} else {

us1.setConnectionString("uvcs");}us1.connect();UniCommand cmd = us1.command();cmd.setCommand("SSELECT STATES");cmd.exec();String s = cmd.response();System.out.println(" Response from UniCommand :" + s);UniSelectList sl = us1.selectList(0);try {

String sFM = us1.getMarkCharacter(UniTokens.FM);int bb = 0;

} catch (UniConnectionException e1) {// TODO Auto-generated catch blocke1.printStackTrace();

}while (!sl.isLastRecordRead()) {

UniString s2 = sl.next();if(!s2.equals("")){

System.out.println(" Record ID : " + s2);}

}} catch (UniSessionException ex) {

if (us1 != null && us1.isActive()) {

try {j.closeSession(us1);

} catch (UniSessionException e) {// TODO Auto-generated catch blocke.printStackTrace();

}us1 = null;

}ex.printStackTrace();


System.out.println(ex.getMessage());} catch (UniCommandException e) {

// TODO Auto-generated catch blocke.printStackTrace();

} catch (UniSelectListException e) {// TODO Auto-generated catch blocke.printStackTrace();

} finally {if (us1 != null && us1.isActive()) {

System.out.println("");System.out.println(

Thread.currentThread().getName()+ " : Connection Passed in Test Program");

System.out.println(

"============================================================================");

System.out.println(

"============================================================================");

try {j.closeSession(us1);

} catch (UniSessionException e) {// TODO Auto-generated catch blocke.printStackTrace();

}}

Program Example for UniObjects for Java 2-12

UniObjects for Java Configuration FileYou can set parameters for connection pooling in a the uoj.properties configuration file residing on the client in the current directory. The following example illustrates the uoj.properties file:

ConnectionPoolingOn=1PoolingDebug=1MinimumPoolSize=1MaximumPoolSize=16IdleRemoveThreshold=300000IdleRemoveExecInterval=60000OpenSessionTimeOut=30000

The following table describes each parameter in the uoj.properties configuration file:


ConnectionPoolingOn When this value is set to 1, the connection is drawn from the appropriate pool, or, if necessary, created and added to the appropriate pool. The default value is 0.

PoolingDebug When this value is set to 1, UniObjects for Java creates the uoj_trace.log file in the current directory for use in debugging and tracing.

MinimumPoolSize The minimum number of connections maintained in the connection pool.

MaximumPoolSize The maximum number of connections in the connection pool.

IdleRemoveThreshold Determines the amount of time, in milliseconds, one session can remain idle in the connection pool.

IdleRemoveExecInterval The thread execution interval time, in milliseconds. During this interval, UniObjects for Java removes idle sessions in the connection pool.

OpenSessionTimeOut How much time UniObjects for Java waits before timing out to get a session from the connection pool. Expressed in milliseconds.

uoj.properties Parameters


3Chapter

Recoverable File System on Windows Platforms

Installing RFS. . . . . . . . . . . . . . . . . . . . 3-3New udtconfig Parameters . . . . . . . . . . . . . . . . 3-4Monitoring Performance . . . . . . . . . . . . . . . . 3-5

Beginning at this release, UniData supports The Recoverable File System on windows platforms.

Hardware and software failures, power loss, fire, or natural disasters can disrupt processing by causing loss of data consistency or loss of entire data files. The Recov-erable File System (RFS) includes before image logging, after image logging, archiving, and failure recovery. You can enable these functions to protect recoverable files from loss of data due to system crashes and media failures. UniData allows you to create files as recoverable, or convert existing nonrecoverable files to recoverable files.,

This chapter details differences between RFS on UNIX and RFS on Windows Platforms. For detailed information about RFS, see Administering the Recoverable File System on Windows Platforms.

3-2

Installing RFSWhen you install UniData on Windows Platforms, RFS appears as a new component in the Select Components dialog box, as shown in the following example.

When you select RFS, UniData sets the SB_FLAG to 1 in the udtconfig file, activating RFS. In addition, the installation process creates sample logconfig, arch_backup.bat, and arch_restore.bat files in the $UDTHOME\include directory.

The logconfig file is a minimum configuration, intended only to enable UniData to start with RFS activated. You must edit this file to specify the size of your log files.

The arch_backup.bat and arch_restore.bat files use the DOS COPY command to backup and restore files.

The UniData 7.1 installation process executes the cntl_install command to create after image and before image log files in the $UDTHOME\log directory, as well as the $UDTHOME\log\log_overflow_directory for overflow log files.


New udtconfig ParametersOn UniData for Windows platforms, a new udtconfig parameter, UDT_TM_IPC, is added to specify how the udt and tm processes communicate.

On UniData for UNIX, the udt and tm processes communicate using message queues. Since message queues are not available on Windows platforms, UniData provides three options for the communication between the udt and tm processes:

UDT_TM_IPC=1 – UniData uses its own message queues to communicate between the udt and tm processes. If you change the value of the N_PGQ or N_TMQ udtconfig parameters, you must also change the value of the MSGMNI configuration parameter. The value of MSGMNI should be 12+N_PGQ+N_TMQ.UDT_TM_IPC=2 – UniData uses named pipes as the communication mechanism between the udt and tm processes. Each udt process creates two named pipes, one for the udt process to write and the tm process to read, and one for the tm process to write and the udt process to read.UDT_TM_IPC=3 – UniData uses memory-mapped files and events to communicate between the udt and tm processes. Each udt process creates 2K memory-mapped files when it starts.

The default value for the UDT_TM_IPC udtconfig parameter is 3.

New udtconfig Parameters 3-4

Monitoring PerformanceYou can monitor performance of RFS using UniAdmin or the sysmon utility.

To access the RFS monitor from UniAdmin, connect to the server, click Perfor-mance Monitor, then click RFS Monitor. A window similar to the following example appears.

Click Run to start the Performance Monitor.


4Chapter

UniXML Class for UniObjects for Java and UniObjects for .NET

UniXML Class for UniObjects .NET . . . . . . . . . . . . 4-3 UniXML – Public Instance Properties . . . . . . . . . . . 4-3 UniXML – Public Instance Methods . . . . . . . . . . . 4-3 UniXML – Protected Instance Methods . . . . . . . . . . 4-5UniXML Class for UniObjects for Java. . . . . . . . . . . . 4-6 Public Methods . . . . . . . . . . . . . . . . . . 4-6

At this release, a new class, UniXML, has been created for UniObjects for Java and UniObjects for .NET. This class defines several public methods you can use to associate an XML document and its associated XML schema with UniData data files residing on the server.

For UniObjects for .NET only, the UniXML class provides a Dataset type for the result set. As a Dataset, a document can easily be transformed and viewed from XML into a relational table, such as the .NET Dataset model.


UniXML Class for UniObjects .NETThe UniXML class represents an XML representation of UniData data. Using this class, you can create XML documents and XML Schema documents from UniQuery or UniData SQL, or directly from a data file. UniData also provides functions to generate new data, modify data, or generate XML from the UniData database using the XMAP file.

UniXML – Public Instance PropertiesThis section describes the public instance properties you can use with UniXML objects.

public int Errcode {get;}

This property gets a UniXML error code.

public string Errmsg {get;}

This property gets a UniXML error message.

public string XMLString {get; set;}

This property gets or sets an XML document as a string type.

public string XSDString {get; set;}

This property gets or sets an XML schema as a string type.

UniXML – Public Instance MethodsThis section describes the public methods you can use the UniXML objects.

UniXML Class for UniObjects .NET 4-3

public void GenerateXML(string cmd);

This method uses the UniQuery LIST command or the UniData SQL SELECT command to get an XML document from the UniData server. If you only supply a command, UniObjects for .NET sets the option to an empty string, checks the result, and reports an error if one occurs.

public void GenerateXML(string cmd, string options);

This method uses the UniQuery LIST command or the UniData SELECT command to get an XML document from the UniData server. You can specify options separated by @FM, and option values separated by @VM.

public void GenerateXMLUsingXmap(string xmapname);

This method uses an existing XMAP file on the server to generate an XML document from UniData data. The relationship between an XML document and a UniData file is described in the XMAP file. The XML document is returned as a string.

public DataSet GetDataSet();

This method returns a DataSet using m_Xmlstr and m_Xsdstr if one exists.

public void UpdateDataUsingXmap(string xmapname);

This method writes to a UniData file residing on the server using an existing XMAP file and the m_Xmlstr residing on the client. The XMAP file is stored in the UniData account in the _XML_ file.

public void UpdateDataUsingXmap(string xmapname, string xmlname);

This method writes a UniData file residing on the server using the XMAP file residing on the server and an XML document residing on the server.


UniXML – Protected Instance MethodsThis section describes the protected instance methods you can use with the UniXML object.

protected override void Dispose (pool disposing)

This method is inherited from UniRoot. It overrides the Dispose() method.

protected Finalize()

This method is inherited from UniRoot. It allows an object to attempt to free resources and perform other cleanup operations before the object is reclaimed by garbage collection.

protected object MemberwiseClone()

This method is inherited from Object. It creates a shallow copy of the current object.

UniXML Class for UniObjects .NET 4-5

UniXML Class for UniObjects for JavaThe UniXML class represents an XML representation of UniData data. Using this class, you can create XML documents and XML Schema documents from UniQuery or UniData SQL, or directly from a data file. UniData also provides functions to generate new data, modify data, or generate XML from the UniData database using the XMAP file.

The following table describes the private strings available with the UniXML class:

Following are public methods used to get and set the private string variables:

getXMLsetXMLgetXsdsetXsdgetErrmsggetErrcode

Public MethodsThis section describes the public methods available with the UniXML class.

Private String Description

private string m_Xsdstr String type to store XML schema

private string m_Xmlstr String type variable to store XML document

private string m_Errstr Error message related to generated error code

private int m_Errorcode Error Code

Private Strings for UniXML


public void generateXML(string command) throws UniXMLException

command is any UniQuery LIST or UniData SQL SELECT command not containing any XML-related keywords. UniObjects stores the resulting XML schema and XML document in the private variables m_Xmlstr and m_Xsdstr.

public void generateXML(string command; string options) throws UniXMLException

This method executes a UniQuery or UniData SQL command, allowing you to pass options to XMLExecute(). You can separate each option by a space. The key and value pair can use “=” as well as @FM and @VM.

public void generateXMLUsingXmap(string xmapname) throws UniXMLException

This method uses the XMAP residing on the server to generate an XML document and stores the result in m_Xmlstr.

public void updateDataUsingXmap(string xmapname) throws UniXMLException

This method updates a file residing in the UniData database using the XMAP located in the _XML_ directory in the UniData account. It uses the contents of the m_Xmlstr variable as the data.

public void UpdateDataUsingXmap(string, xmapname, string xmlname) throws UniXMLException

This method updates a file residing in the UniData database using the XMAP located in the _XML_ directory in the UniData account. It uses an XML document residing on the server as data.

UniXML Class for UniObjects for Java 4-7

5Chapter

SSL Support in UniData Client

Support for Secure Connections . . . . . . . . . . . . . . 5-2 In This Chapter . . . . . . . . . . . . . . . . . . 5-2UCI Configuration Parameters for ODBC and UniOLEDB . . . . . 5-3 Secure Connection Parameters . . . . . . . . . . . . . 5-3 Changing UCI Configuration Parameters . . . . . . . . . . 5-4UniObjects ConnectionString Parameters . . . . . . . . . . . 5-8About SSL Property Lists . . . . . . . . . . . . . . . . 5-10 Creating and Maintaining SSL Property Lists . . . . . . . . 5-10 List Encryption . . . . . . . . . . . . . . . . . . 5-10 Loading and Decrypting an SSL Property List . . . . . . . . 5-11 SSL Properties . . . . . . . . . . . . . . . . . . 5-11Using the U2 SSL Configuration Editor . . . . . . . . . . . 5-19 Working with SSL Property Lists . . . . . . . . . . . . 5-19 Starting the U2 SSL Configuration Editor . . . . . . . . . 5-19Creating a New SSL Property List . . . . . . . . . . . . . 5-23Editing an Existing SSL Property List . . . . . . . . . . . . 5-36Deleting an SSL Property List . . . . . . . . . . . . . . 5-48Copying an SSL Property List . . . . . . . . . . . . . . 5-49Renaming an SSL Property List . . . . . . . . . . . . . . 5-52Using the Trace Feature . . . . . . . . . . . . . . . . 5-54Using the Console/Problems View . . . . . . . . . . . . . 5-55

C:\Program Files\Adobe\FrameMaker7.0\UniData

Support for Secure ConnectionsAt version 7.1, UniData supports the ability of client applications to make secure connections to the database server through Secure Sockets Layer (SSL). SSL is a transport layer protocol that provides a secure channel between two communicating programs over which application data can be transmitted securely. It is the most widely implemented security protocol on the World Wide Web.

SSL provides for server authentication, encryption, and message integrity. It can also support client authentication.

UniData uses CallHTTP and the Sockets API. As a security protocol implemented with both of these APIs, SSL enables commercial applications to securely process sensitive data, such as credit card transactions.

In This ChapterThis chapter contains the following topics related to secure connections:

Secure Connection Parameters

UniData 7.1 contains new parameters to support a client application’s secure connection to the UniData database server:

UCI Configuration Parameters for ODBC and UniOLEDBUniObjects ConnectionString Parameters

SSL Property Lists

One of the new parameters specifies the SSL property list to be used for a secure connection. The property list defines the characteristics of the secure connection. This version of the product introduces the U2 SSL Configuration Editor, a graphical user interface (GUI) tool for creating and maintaining SSL property lists.

About SSL Property ListsUsing the U2 SSL Configuration Editor

This chapter assumes that users who want to use SSL have a basic knowledge of public key cryptography.

5-2

C:\Program Files\Adobe\FrameMaker7.0\UniData 7.1C\NEWFEATURES\NEWFEATCH05.fm9/28/07

UCI Configuration Parameters for ODBC and UniOLEDBClient applications can use UniData ODBC or UniOLEDB to access UniData data sources through entries in the UCI configuration file (uci.config) on the client machine. The uci.config file contains connection parameters needed to route requests to the UCI server.

When ODBC or UniOLEDB attempts to connect to a data source, UniData ODBC or UniOLEDB reads the UCI configuration file to determine the connection parameters. In this version of UniData, three new UCI configuration parameters have been implemented to enable a client application to make a secure connection to the UniData database.

Secure Connection ParametersThe first new UCI configuration parameter indicates whether an application requires a secure connection. If so, two other parameters provide the SSL property list and password to be used. These parameters are detailed in the following table.

Parameter Description Default

SECUREMODE Indicates whether the application requires a secure connection for exchange of data with the database server:True – Secure connectionFalse – Nonsecure connection

False

Configuration Parameters



Changing UCI Configuration ParametersIf the client application requires a secure connection to the database server, you can enable the connection by using either of the following methods:

Adding Secure Session Parameters in the uci.config FileSetting Secure Session Input Variables in SQLSetConnectOption

SSLPROPERTYLIST The name of the SSL property list to be used to verify properties of the secure connection.A value for this option applies only if the value of the SECUREMODE option is True.If SECUREMODE is True and you do not specify a value for SSLPROPERTYLIST, the default SSL property list in the Registry HKEY_LOCAL_MACHINE/SOFTWARE/IBM/UniClient/SPL/myspl is used.For further information on property lists, see “About SSL Property Lists.” For instructions on creating and maintaining property lists, see “Using the U2 SSL Configuration Editor.”

see Description

SSLPROPERTYPASSWORD The password for the specified SSL property list.A value for this option applies only if the value of the SECUREMODE option is True.The password is used to derive an internal decryption key to decrypt the list. If a password is not specified, an internal default decryption key is used.

internal default decryption key

Parameter Description Default

Configuration Parameters (Continued)

5-4


Adding Secure Session Parameters in the uci.config File

The UCI Config Editor tool has been enhanced to accept three new parameters for secure connections. To enable a secure connection, you can use the UCI Config Editor to add the secure connection parameters in the uci.config file as follows:

[ODBC DATA SOURCES]<localud>DBMSTYPE = UNIDATANETWORK = TCP/IPSERVICE = udserverHOST = localhost

SECUREMODE = TrueSSLPROPERTYLIST = mylistSSLPROPERTYPASSWORD = mypassword

For information about the UCI Config Editor, see the Administrative Supplement for Client APIs.

Setting Secure Session Input Variables in SQLSetConnectOption

As an alternative, you can set values for the secure session input variables in SQLSetConnectOption. The SQLSetConnectOption enables an application to control the behavior of a connection. The SECURE_MODE, SSL_PROPERTY_LIST, and SSL_PROPERTY_PASSWORD variables set values for a secure connection, as detailed below.

Syntax

RETCODE SQLSetConnectOption (hdbc, fOption, vParam, szParam)

Input Variables

The following table describes the input variables.

Type Argument Description

HDBC hdbc Connection handle.

SQLSetConnectOption Input Variables



szParam Values for Secure Connections

The szParam values for secure connections are as follows:

UWORD fOption Option to be set.

UDWORD vParam A 32-bit value associated with fOption when fOption is SQL_EMPTY_NULL, SQL_TXN_ISOLATION, SQL_DATA_MODEL.

UCHAR * szParam Text value associated with fOption when fOption is SECURE_MODE, SQL_OS_UID, SQL_OS_PWD, SQL_LIC_DEV_SUBKEY, any of the SQL_UVNLS options, SSL_PROPERTY_LIST, or SSL_PROPERTY_PASSWORD.

If fOption is... szParam is...

SECURE_MODE A value indicating whether the application requires a secure connection for exchange of data with the database server: True or False.

SSL_PROPERTY_LIST The name of the SSL property list to be used to verify properties of the secure connection.A value for this option applies only if the value of the SECURE_MODE option is True.If SECURE_MODE is True and you do not specify a value for SSL_PROPERTY_LIST, the default SSL property list in the Registry <UniClient>/SPL/myspl is used, where <UniClient> is defined in the following Registry key:HKEY_LOCAL_MACHINE/SOFTWARE/IBM/ UniClient

szParam Values

Type Argument Description

SQLSetConnectOption Input Variables (Continued)

5-6


SSL_PROPERTY_PASSWORD The password for the specified SSL property list.A value for this option applies only if the value of the SECURE_MODE option is True.The password is used to derive an internal decryption key to decrypt the list. If a password is not specified, an internal default decryption key is used.

If fOption is... szParam is...

szParam Values (Continued)



UniObjects ConnectionString ParametersThe UniObjects session object properties include a ConnectionString property. In previous versions, the ConnectionString property was used only to specify the server process to be used for the session. It now provides a second set of parameters to specify a secure connection.

If you want to connect to a server other than the one specified by the DatabaseType property, enter the name of the server process (such as defcs, udcs, or uvcs).If you do not specify a server process in the ConnectionString property, the server specified in the DatabaseType property is used.If the client application does not require a secure connection to the database server, secure connection parameters are not required. If the client application requires a secure connection to the database server, enter values for the following parameters:SecureMode=[True | False]

whereTrue specifies a secure session.False specifies a nonsecure session.For a secure session, this component is required. If you do not enter a value for the SecureMode parameter, the default value of False is assumed and any values specified for the SSLPropertyList and SSLPropertyPassword parameters are ignored.

5-8


SSLPropertyList=list-name

wherelist-name is the name of the SSL property list to be used to validate properties of the secure connection.

A value for this parameter applies only if SecureMode=True. If SecureMode=True and you do not specify a value for SSLPropertyList, the default SSL property list in the Registry <UniClient>/SPL/myspl is used,where<UniClient> is defined by the following Registry key: HKEY_LOCAL_MACHINE/SOFTWARE/IBM/UniClient

SSLPropertyPassword=password-string

wherepassword-string is the password for the specified SSL property list.A value for this parameter applies only if SecureMode=True. The password is used to derive an internal decryption key to decrypt the list. If a password is not specified, an internal default decryption key is used.

Use a colon as a separator between values. The following example shows server process and secure connection parameters in the ConnectionString property:

udcs;SecureMode=True;SSLPropertyList=myList;SSLPropertyPassword=myPassword



About SSL Property ListsAn SSL property list is an ASCII text file that stores the properties for a secure connection. These properties define the characteristics and behaviors of the secure connection.

Creating and Maintaining SSL Property ListsAlthough the property list is an ASCII text file, you should never edit it directly. UniData 7.1 provides the U2 SSL Configuration Editor for use in creating, editing, or deleting an SSL property list. Using this tool ensures that the list is properly saved to (or deleted from) the Windows Registry. For detailed instructions, see “Using the U2 SSL Configuration Editor.”

List EncryptionAn SSL property list may contain sensitive information such as the password to a private key or the location of a certificate authority (CA) certificate. For this reason, it is saved in encrypted form to the Windows Registry at:

HKEY_LOCAL_MACHINE/SOFTWARE/IBM/UniDK/SPL

The U2 SSL Configuration Editor uses an algorithm developed by IBM to encrypt the list.

If you do not assign your own password to the list, the IBM algorithm uses a an internal default password to generate the encryption key for the list. Because the internal default password is fixed, the IBM algorithm always produces the same encryption key from this password. Consequently, anyone who uses the U2 SSL Configuration Editor can access and read the contents of your SSL property list.

For increased security, we strongly recommend that you assign your own password to the SSL property list. In this case, the same IBM algorithm uses your unique password as the seed for generating an encryption key. The resulting encryption key is unique, so only users who know the password can access the list and read its contents.

5-10


Loading and Decrypting an SSL Property ListBefore the SSL handshake takes place, the SSL property list must be loaded into memory and decrypted. After the list has been decrypted, it is supplied in plain text form to a function that handles the SSL handshake.

Alternatively, the program can assemble the property list on demand in memory, eliminating the need to create a property list in advance.

When the property list is in decrypted form (only internally in UniData), each property is stored on a separate line in the file, as shown below:

propertyName=propertyValue

SSL PropertiesThis section describes each property supported in the SSL_PROPERTY_LIST to define the characteristics and behaviors of a secure connection.

SSLVersion={SSLv3 | TLSv1}

Optional. Default is SSLv3.

This property specifies the preferred protocol version.

Version Description

SSLv3 This is most widely used protocol.

TLSv1 This is the newer protocol. Most newer applications support it, but some older applications may not.

Protocol Versions



CertificateStoreType={U2 | Windows}

Optional. Default is U2.

This property specifies the type of certificate stores to be used for all certificates issued for the secure connection.

CACertificate=<cert-path>[;<cert-path>...]

Each property value string can contain multiple CA certificate paths, with paths separated by a semicolon (;) as shown above. Specifying multiple CACertificate properties is allowed.

U2 certificate store type

<cert-path> is the path of the certificate file that is used as a CA certificate. The format of the certificate can be either PEM or DER. (However, see the CertificatePath property for additional information on how U2 loads certificates when performing the SSL handshake.) With the U2 type, if a CA certificate chain is required, you have the choice of specifying multiple CACertificate properties, or, for PEM-format certificates, concatenating the certificate files into one single file (using OS-level editor or command line) and specifying the concatenated file once.

Value Description

U2 All certificates specified in this file are PEM or DER–format OS-level files.

Windows All certificates specified in this file are looked up from the native Windows certificate store. Generally, a CA certificate is looked up from Windows CA and ROOT stores, while MyCertificate is looked up from MY stores.In Microsoft’s terminology, these certificate stores are system stores: a collection of physical certificate stores that reside in the Windows Registry. UniData looks up these stores from both of the following Registry locations:n CERT_SYSTEM_STORE_CURRENT_USER

n CERT_SYSTEM_STORE_LOCAL_MACHINE

Certificate Store Types

5-12


Windows certificate store type

Specify the same “friendly name” or “Common name” that is used for the certificate in the certificate store. With the Windows type, specify only one certificate, which should be the most immediate CA certificate (the one used directly to sign the certificate to which authentication is to be performed).

A certificate chain is automatically established and used in an SSL session. Note that the above description is based on the assumption that a correct and complete trust relationship exists in the Windows certificate store for the certificate involved. If a complete chain cannot be formed, an error is reported. This also applies to other certificate-related properties described below.

MyCertificate=<cert-path>

Optional for client SSL property list; default is none. Required for server SSL property list.

U2 certificate store type

Note that if you specify this property, you must also specify the MyPrivateKey and PrivateKeyPassword properties. The format of the certificate can be either PEM or DER.

Windows certificate store type

Specify the same “friendly name” or “Common name” that is used for the certificate in the certificate store. Note that when you import a Windows store type certificate to the MY store, you must associate an exportable private key with it by selecting the Exportable private key check box.

See also ClientAuthentication (below).

MyPrivateKey=<key-path>

Applicable to U2 certificate store type only. Required if you entered a value in My Certificate.

This property specifies the path for the file that contains the private key associated with MyCertificate. The format of the key file can be either PEM or DER.



When an SSL property list is created, the private key is loaded into memory and validated against its corresponding certificate (My Certificate). If it passes validation, the key is stored with the SSL property list. This validation feature is designed to enhance the security and protection of the user’s private key.

After the SSL property list has been created, you do not need to keep the private key file on your hard disk. You can store the key file safely on offline media until the next time you want to edit the SSL property list.


PrivateKeyPassword=<pass-phrase>

Applicable to U2 certificate store type only. Required if you specified a value for MyCertificate.

This property specifies the password for the private key file.


CRL=<cert-path>

Optional. Default is none. Specifying multiple CRL properties is allowed.

This property specifies the Certificate Revocation List (CRL) to be used for this secure connection.

The CRL is a special certificate published by certificate authority (CA); it contains the serial numbers of certificates revoked by CA. If an incoming server certificate is specified, it is checked against the CRL to verify that it has not been revoked before other verification is performed.

The format of the CRL can be PEM or DER.

AuthenticationDepth=<level>

Optional. Default is 5.

This property determines the level at which to stop UniData’s verification process in authentication processing. The default setting of 5 is a sufficient depth in most cases. If you set the depth for fewer levels of authentication than actually employed for the certificate, the certificate will not pass authentication.

CipherSuite=<cipher-suite-string>

5-14


Optional. Default is all ciphers supported by the OpenSSL open source library.

This property specifies a suite of ciphers to be used in a specific order in the SSL handshake.

For further details, see the description of addCipherSuite() in the UniBasic Extensions manual.

TrustedPeerName=<trusted-peer-name-string>

Optional. Default is none. Specifying multiple TrustedPeerName properties is allowed.

<trusted-peer-name-string> is in the format of<peer-name>[;<peer-name>[;<peer-name>]...]

This property tells UniData that it needs to perform additional checking in authenticating the incoming certificate. If you do not specify TrustedPeerName, the incoming certificate is considered valid when the CA certificate has verified it. However, if you specify TrustedPeerName, a further check is performed to verify that the incoming certificate’s SubjectAltName extension or CommonName subject field matches one of the specified TrustedPeerName.

TrustedPeerName can be either a fully specified name (such as [email protected]) or a wildcard name. Two wildcard characters are supported:

For example, %@us.xyz.com matches both [email protected] and [email protected], while [email protected] matches [email protected] only.

AuthenticationStrength=[STRICT | GENEROUS]

Optional. Default is STRICT.

STRICT authentication requires the following:

The incoming server certificate is a well-formed X.509 certificate.A valid CA certificate exists and verifies the incoming server certificate.Peer name checking (if specified) is performed.

GENEROUS authentication requires only the following:

% Match any character strings

_ Match one character



The incoming server certificate is a well-formed X.509 certificate.Peer name checking (if specified) is performed.

Note: GENEROUS authentication is not highly secure. We recommend using it in test environments only.

CertificatePath=[DEFAULT | RELATIVE | PATH=<path> | ENV=<env-var>]

Applicable to U2 certificate store type only. Optional. Default is PATH:C:/IBM/UniDK/certs.

When you specify a certificate by the CACertificate, MyCertificate, or CRL property, the value for that property is registered internally. When loading the certificate into memory to establish an SSL connection, UniData uses this registered path by default to retrieve the certificate.

The CertificatePath property allows you to specify different locations in which to search the certificates. Note that this property applies to all certificates specified in the file.

Four options are available:

Option Description

DEFAULT Specifies the above-described behavior. This option is the default.

RELATIVE UniData looks for the certificate in the current directory under which the client process is running.

PATH:<path> <path> is a user-specified path for loading certificates specified in this SSL property list. It can be either an absolute path or a relative path.The default path is C:\IBM\UniDK\certs. With this path, the behavior is the same as that of the DEFAULT option.

ENV:<env-var> <env-var> is an environment variable name. With this option, the client process uses the value of the environment variable as the path to load the certificates. Note that UniData looks up the environment variable for a client process only once when the first SSL connection is made and its value is cached for later reference by that process.

CertificatePath Options

5-16


ClientAuthentication=[TRUE | FALSE]

Optional. Default is FALSE.

This property should be specified for a server SSL property list only.

If the value is TRUE, the SSL server using this property list requires client authentication during the SSL handshake. It asks the client to send its certificate.

If TRUE, UniData treats the SSL property list as a server property list. Consequently, you must also specify MyCertificate, MyPrivateKey (for the U2 certificate store type only), PrivateKeyPassword, and CACertificate or the SSL property list will not be created.

RandomFileLocation=<directory-path>

Optional. Default is “.” (the current directory).

This property specifies the directory in which the client stores random data for the use of SSL operations. The directory should be specfied as an absolute path (for example, D:\mysys\work). The directory must currently exist and be writeable.

By default, random data is stored in the directory in which a client process runs. If you want to control where the random data is stored (for example, to limit users’ access to the random data by storing it in a directory that has restricted permissions), you should use this property to specify the desired directory.

The random data file named U2SSL.rnd is created in the specified directory.



Using the U2 SSL Configuration EditorThe U2 SSL Configuration Editor is a graphical user interface (GUI) tool for creating and managing SSL property lists.

Working with SSL Property ListsUse the U2 SSL Configuration Editor to create, edit, delete, copy, or rename an SSL property list. Using the tool ensures that the list is properly saved to (or deleted from) the Registry.

Starting the U2 SSL Configuration EditorThe U2 SSL Configuration Editor program files are placed in a subfolder under the Programs folder when you install UniData. This section explains how to navigate to the tool and start it. It also describes the layout of the U2 SSL Configuration Editor window.

5-18


To start the U2 SSL Configuration Editor:From the Start menu, choose Programs ä IBM U2 ä UniData Tools ä SSL Config Editor. The U2 SSL Configuration Editor window appears.

Components of this window are described below.Main Menu

At the top of the U2 SSL Configuration Editor window are four menus:

Menu Description

File Options for opening, closing, saving, printing, and performing other tasks for managing SSL property lists.

U2 SSL Configuration Editor Main Menu



Shortcut Toolbar

Under the main menu is a toolbar with shortcuts for the most common tasks. Roll the mouse over a shortcut tool to see a brief description of the task.

Edit Options for performing standard Windows file edit actions, including undo, redo, cut, copy, paste, and delete.

Window Options for controlling the view and navigation of panes in the U2 SSL Configuration Editor window.

Help Options for accessing help.

Menu Description

U2 SSL Configuration Editor Main Menu (Continued)

5-20


Panes

The U2 SSL Configuration Editor window is divided into three panes:

From the main window, you can perform the following tasks to manage SSL property lists:

Creating a New SSL Property ListEditing an Existing SSL Property ListDeleting an SSL Property ListCopying an SSL Property ListRenaming an SSL Property ListUsing the Trace FeatureUsing the Console/Problems View

Pane Usage

U2 SSL Property Explorer (left)

Use this pane to view the directory structure of SSL property lists and copy, rename, or delete existing SSL property lists.

Editor view (upper right)

This pane contains a Welcome tab with information about using the U2 SSL Configuration Editor.

Console/Problems view (lower right)

This pane contains two tabs:Console for viewing error and informational messages and a log of transactions performed in Trace mode.Problems for details on any problems encountered while creating, editing, deleting, or performing other operations on an SSL property list.

U2 SSL Configuration Editor: Main Window Panes



Creating a New SSL Property ListThis section takes you through the process of creating an SSL property list, defining all the properties of a secure connection.

The Create a New U2 SSL Property List dialog box provides a form for entering these properties, helping you input the required information. The requirements are based on whether the SSL property list is for the use of a client or a server, and on the certificate store type.

The properties are grouped on three pages of the dialog box. The instructions for creating a new SSL property list are broken down into tasks, with one task for each page of the dialog box:

Task 1: Assign name, password, SSL version, and store type to property listTask 2: Specify certificates, private key and password, certificate revocation list, and cipher suitesTask 3: Specify authentication properties

5-22


Task 1: Assign name, password, SSL version, and store type to property list

1. In the U2 SSL Configuration Editor window, select File ä New. The Create a New SSL Property List dialog box appears.

On the SSL Property List Name, Password, SSL Version, and Store Type page of this dialog box, you define the basic properties of the SSL property list.

2. In the Property list name box, enter a unique name for the SSL property list to be created.



3. Optional. We strongly recommend that you establish a password for the SSL property list. An IBM algorithm is applied to your password to derive a unique encryption key for the list. To access a password-protected list, users must enter the password as the key to decrypt the list and view its plaintext contents. If you do not assign a password to the list, the algorithm uses a fixed internal default password to generate the encryption key. The key produced in this manner never varies and anyone who uses the U2 SSL Configuration Editor can access the list and view its contents.In the Password box, enter a password for the SSL property list. There are no limitations on length or restrictions on characters allowed; however, the length of the password and randomness of the characters contribute to its relative security. Use a password that is difficult to guess and share it only with users who need to access the list.

4. If you entered a password for the SSL property list, you must verify the password. In the Re-enter password box, type the same password again.

5. UniData supports SSL version 3 and TLS version 1. Under SSL version, select the version of the protocol to be used for this secure connection:

Option Description

SSLv3 This is the default setting. It is the most widely used protocol.

TLSv1 This is the newer protocol. Most newer applications support it, but some older applications may not.

SSL Versions

5-24


6. Under Certificate store type, select the type of certificate stores to be used for all certificates issued for this secure connection:

Option Description

U2 This is the default setting. Use this setting if all certificates that apply to this secure connection are PEM or DER format OS-level files.

Windows All certificates for this connection are looked up from the native Windows certificate store. Generally, a CA certificate is looked up from Windows CA and ROOT stores, while My Certificate is looked up from MY stores.In Microsoft’s terminology, these certificate stores are system stores: a collection of physical certificate stores that reside in the Windows Registry. UniData looks up these stores from both of the following Registry locations:n CERT_SYSTEM_STORE_CURRENT_USER

n CERT_SYSTEM_STORE_LOCAL_MACHINE

Certificate Store Type



7. Choose one of the following actions:To discard your entries and cancel the process of creating an SSL property list, click Cancel.Otherwise, to continue defining properties of the new SSL property list, click Next.The Certificates, Private Key and Password, CRL, and Cipher Suites page of the Create a New SSL Property List dialog box appears.

On this page of the dialog box, you specify the path of a certificate, set the private key and password if applicable, specify the path of the certificate revocation list (CRL), and specify cipher suites to be used in the handshake.

5-26


Task 2: Specify certificates, private key and password, certificate revocation list, and cipher suites

1. If applicable, in the CA certificate box, enter the path of the file to contain a certificate authority (CA) certificate for this secure connection, or click Browse to find the path. See specifics for the certificate store type below.U2 certificate store type:

Specify the path of the certificate file that is used as a CA certificate. The format of the certificate can be either PEM or DER. With the U2 type, you can specify multiple certificate paths, separating each with a semicolon (;).If a CA certificate chain is required, you have the choice of specifying multiple certificate files in the CA certificate box, or, for PEM-format certificates, concatenating the certificate files into one single file (using OS-level editor or command line) and specifying the concatenated file once.Windows certificate store type:

Specify the same “friendly name” or “Common name” that is used for the certificate in the certificate store. With the Windows type, specify only one certificate, generally the most immediate CA certificate (the one used directly to sign the certificate to which authentication is to be performed).A certificate chain is automatically established and used in an SSL session. Note that the above description is based on the assumption that a correct and complete trust relationship exists in the Windows certificate store for the certificate involved. If a complete chain cannot be formed, an error is reported. This also applies to other certificate-related properties.

2. Optional for a client SSL property list; required for a server SSL property list. In the My Certificate box, enter the path for your certificate for this secure connection, or click Browse to find the path. See specifics for the certificate store type below.U2 certificate store type:

Note that if you specify a path in My Certificate for a server SSL property list, you must also enter values for Private key and Private key password. The format of the certificate can be either PEM or DER.



Windows certificate store type:

Specify the same “friendly name” or “Common name” that is used for the certificate in the certificate store. Note that when you import a Windows store type certificate into the MY store, you must associate an exportable private key with it by selecting the Exportable private key check box.

3. Applicable to the U2 certificate store type only. Required if you entered a value in My Certificate.In the Private key box, enter the path for the file that contains the private key associated with My Certificate, or click Browse to find the path. The format of the key file can be either PEM or DER.When an SSL property list is created, the private key is loaded into memory and validated against its corresponding certificate (My Certificate). If it passes validation, the key is stored with the SSL property list. This validation feature is designed to enhance the security and protection of the user’s private key.After the SSL property list has been created, you do not need to keep the private key file on your hard drive. You can store the key file safely on external media until the next time you want to modify properties of the SSL property list.

4. Applicable to the U2 certificate store type only. Required if you entered a value in My Certificate.In the Private key password box, enter the password for the private key file.

5. Optional. In the CRL box, enter the path of a certificate revocation list (CRL) to be used for this secure connection, or click Browse to find the path. You can specify multiple CRL paths, separating each with a semicolon (;).The CRL is a special certificate published by the certificate authority (CA), containing the serial numbers of certificates that the CA has revoked. If an incoming server certificate is specified, it is checked against the CRL to verify that the certificate has not been revoked before other verification is performed.The format of the CRL can be either PEM or DER.

5-28


6. Optional. In the Cipher Suites box, specify a suite of ciphers to be used in a specific order in the SSL handshake. If you make no entry, the default of all ciphers supported by the OpenSSL open source library applies.For further details, see the description of addCipherSuite() in the UniBasic Extensions manual.

7. Choose one of the following actions:To return to the previous page of the dialog box, click Back.To discard your entries and cancel the process of creating an SSL property list, click Cancel.Otherwise, to continue defining properties of the new SSL property list, click Next.



The Authentication Properties page of the Create a New SSL Prop-erty List dialog box appears.

On this page of the dialog box, you specify properties related to peer authentication for the secure connection.

5-30


Task 3: Specify authentication properties1. Optional. In the Trusted peers box, enter the name of a trusted peer as

detailed below. This property tells UniData that additional checking needs to be performed in authenticating the incoming certificate. If you leave this box blank, the incoming certificate is considered valid when the CA certificate has verified it. However, if you specify a trusted peer name, a further check is performed to verify that the incoming certificate’s SubjectAltName extension or CommonName subject field matches that of the trusted peer.The trusted peer name can be either a fully specified name (such as [email protected]) or a wildcard name. Two wildcard characters are supported:

For example, %@us.xyz.com matches both [email protected] and [email protected], while [email protected] matches [email protected] only.You can enter the names of multiple trusted peers, separating each with a semicolon (;).

2. Optional. In the Random file location box, enter the absolute path of the directory in which UniData stores random data for the use of SSL opera-tions, or click Browse to find the path. For example, D:\mysys\work is an absolute path. The directory must currently exist and be writable. The default is “.” (the current directory).By default, random data is stored in the directory in which a client process runs. If you want to control where the random data is stored (for example, to limit users’ access to the random data by storing it in a directory that has restricted permissions), use this property to specify the desired directory.When the SSL property list is created, the random data file named U2SSL.rnd is created in the directory specified here.

3. Optional. In the Authentication depth list, select the level at which to stop UniData’s verification process in authentication processing. The default setting is 5, which is a sufficient depth in most cases. If you set the authen-tication depth for fewer levels of authentication than actually employed for the certificate, the certificate will not pass authentication.

% Match any character string




4. Applicable to a server SSL property list only. Optional.Under Client authentication, if the SSL server using this property list requires client authentication during the SSL handshake, select the Require client authentication check box. A server that requires client authentication asks the client to send its certificate as an additional security measure.If you select this check box, UniData treats the SSL property list as a server property list. For a server property list, you must also specify these properties:

CA certificateMy CertificatePrivate key (U2 certificate store type only)Private key password (U2 certificate store type only)

If you leave a required property blank, the U2 SSL Configuration Editor issues an error message after you click Finish, and redisplays the first page on which you to need to enter missing information.

5. Optional. Under Authentication strength, select the appropriate option for this secure connection.

Option Description

Strict This is the default setting. Strict authentication requires that the following conditions be met:n The incoming server certificate is a well-formed X.509

certificate.

n A valid CA certificate exists and verifies the incoming server certificate.

n Peer name checking (if specified) is performed.

Generous Generous authentication requires only that the incoming server certificate is a well-formed X.509 certificate.

Note: Generous authentication is not highly secure. We recommend using it in test environments only.

Authentication Strength

5-32


6. Applicable to U2 certificate store type only. Optional.When you specify a certificate by the CA certificate, My Certificate, or CRL property, the value for that property is registered internally. When the certificate is loaded into memory to establish an SSL connection, UniData uses this registered path by default to retrieve the certificate.The Certificate path property allows you to specify different locations in which to search the certificates. Note that this property applies to all certificates in the file.Under Certificate path, select one of the following options:

Option Description

Default Specifies the above-described behavior.

Relative UniData looks for the certificate in the current directory under which the client process is running.

Path Enter the path for loading certificates specified in this property list, or click Browse to find the path. This can be either an absolute path or a relative path.The default path is C:\IBM\UniDK\certs. With this path, the behavior is the same as that of the Default option.

Environment Variable Enter an environment variable name. With this option, the value of the environment variable is used as the path in which to load the certificates. Note that UniData looks up the environment variable for a client process only the first time the process makes an SSL connection; the value of the environment variable is cached for later reference by that process.

Certificate Path Options



7. Choose one of the following actions:To return to the previous page of the dialog box, click Back.To discard your entries and cancel the process of creating an SSL property list, click Cancel.Otherwise, to finish entry of properties and create the SSL property list, click Finish.The U2 SSL Configuration Editor tool checks your entries to ensure that you have input all required properties. The requirements are based on whether this is a client or server SSL property list, and on the selected certificate store type.If you left a required property blank or entered conflicting or inconsistent values in related properties, when you click Finish the U2 SSL Configuration Editor issues an error message and redisplays the first page on which you to need to enter information.If the tool finds no errors, the program creates the new SSL property list, saving it in encrypted form to the Windows Registry at:HKEY_LOCAL_MACHINE/SOFTWARE/IBM/UniDK/SPL

5-34


Editing an Existing SSL Property ListThis section takes you through the process of editing an existing SSL property list, changing the properties of a secure connection.

To edit an existing SSL property list:1. In the U2 SSL Configuration Editor window, open the U2 SSL Property

Explorer pane if it is not already displayed. To open this pane, choose Window ä Show View ä U2 SSL Property Explorer.

2. In the U2 SSL Property Explorer pane, double-click the name of the SSL property list to be edited. The Property List Password dialog box appears.

3. If the selected SSL property list has an associated password, enter the password and click OK. Otherwise, if the property list has no associated password, leave the box blank and click OK.

Note: If the SSL property list does not have an associated password, you can rename the list and enter a password during this process. For instructions, see “Renaming an SSL Property List” on page 5-52.

The SSL property list opens in the Editor view in the upper right pane of the U2 SSL Configuration Editor window.

The Editor view is split into two components: the Property List on the left side and the Property Editor on the right.



4. In the Property List, select the line containing a property value to be changed. The Property Editor displays information for the selected property.

The following table provides information on changing the value of each SSL property. This table lists properties in the order in which they appear in the Property List on the left side of the Editor view.

Element Description

Property Display only. This box contains the name of the property as it is stored in the U2 SSL Configuration Editor program. Property names cannot be changed.

Description Provides guidelines and tips for setting the value of this property.

Value Initially displays the current value of the property. In this box, you can change the value of the selected property.

Property Editor

Property Value

SSLVersion UniData supports SSL version 3 and TLS version 1. Select the version of the protocol to be used for this secure connection:n SSLv3 – This is the default setting. It is the most

widely used protocol.

n TLSv1 – This is the newer protocol. Most newer applications support it, but some older applications may not.

To apply this change, click OK.

Editing Property Values

5-36


CertificateStoreType Select the type of certificate stores to be used for all certificates issued for this secure connection.n U2 – This is the default setting. Use this setting if

all certificates that apply to this secure connection are PEM or DER format OS-level files.

n Windows – All certificates for this connection are looked up from the native Windows certificate store. Generally, a CA certificate is looked up from Windows CA and ROOT stores, while My Certificate is looked up from MY stores.

In Microsoft’s terminology, these certificate stores are system stores: a collection of physical certificate stores that reside in the Windows Registry. UniData looks up these stores from both of the following Registry locations:CERT_SYSTEM_STORE_CURRENT_USERCERT_SYSTEM_STORE_LOCAL_MACHINE


Property Value

Editing Property Values (Continued)



CACertificate Enter the path of the file to contain a certificate authority (CA) certificate for this secure connection, or click Browse to find the path. See specifics for the certificate store type below.

U2 certificate store type:

Specify the path of the certificate file that is used as a CA certificate. The format of the certificate can be either PEM or DER. With the U2 type, you can specify multiple certificate paths, separating each with a semicolon (;).If a CA certificate chain is required, you have the choice of specifying multiple certificate files, or, for PEM-format certificates, concatenating the certificate files into one single file (using OS-level editor or command line) and specifying the concatenated file once.

Windows certificate store type:Specify the same “friendly name” or “Common name” that is used for the certificate in the certificate store. With the Windows type, specify only one certificate path, generally the most immediate CA certificate (the one used directly to sign the certificate to which authentication is to be performed).A certificate chain is automatically established and used in an SSL session. Note that the above description is based on the assumption that a correct and complete trust relationship exists in the Windows certificate store for the certificate involved. If a complete chain cannot be formed, an error is reported. This also applies to other certificate-related properties.To apply this change, click OK.

Property Value


5-38


MyCertificate Optional for a client SSL property list; required for a server SSL property list. Enter the path for your certificate for this secure connection, or click Browse to find the path. See specifics for the certificate store type below.

U2 certificate store type:Note that if you specify a path in MyCertificate for a server SSL property list, you must also enter values for MyPrivateKey and PrivateKeyPassword. The format of the certificate can be either PEM or DER.

Windows certificate store type:Specify the same “friendly name” or “Common name” that is used for the certificate in the certificate store. Note that when you import a Windows store type certificate into the MY store, you must associate an exportable private key with it by selecting the Exportable private key check box.To apply this change, click OK.

MyPrivateKey Applicable to the U2 certificate store type only. Required if you entered a value in MyCertificate.Enter the path for the file that contains the private key associated with My Certificate, or click Browse to find the path. The format of the key file can be either PEM or DER.When an SSL property list is created, the private key is loaded into memory and validated against its corresponding certificate (My Certificate). If it passes validation, the key is stored with the SSL property list. This validation feature is designed to enhance the security and protection of the user’s private key.After the SSL property list has been created, you do not need to keep the private key file in memory. You can store the key file safely on media until the next time you want to modify properties of the SSL property listTo apply this change, click OK.

Property Value




PrivateKeyPassword Applicable to the U2 certificate store type only. Required if you entered a value in MyCertificate.Enter the password for the private key file.To apply this change, click OK.

TrustedPeerName Optional. Enter the name of a trusted peer as detailed below. This property tells UniData that additional checking needs to be performed in authenticating the incoming certificate. If you leave this box blank, the incoming certificate is considered valid when the CA certificate has verified it. However, if you specify a trusted peer name, a further check is performed to verify that the incoming certificate’s SubjectAltName extension or CommonName subject field matches that of the trusted peer.The trusted peer name can be either a fully specified name (such as [email protected]) or a wildcard name. Two wildcard characters are supported:

% Match any character string


For example, %@us.xyz.com matches both [email protected] and [email protected], while [email protected] matches [email protected] only.You can enter the names of multiple trusted peers, separating each with a semicolon (;).To apply this change, click OK.

Property Value


5-40


AuthenticationStrength Optional. Select the appropriate authentication strength option for this secure connection:n STRICT – This is the default setting. Strict

authentication requires that the following conditions be met:

– The incoming server certificate is a well-formed X.509 certificate.– A valid CA certificate exists and verifies the incoming server certificate.– Peer name checking (if specified) is performed.

n GENEROUS – This strength requires only that the incoming server certificate is a well-formed X.509 certificate. Note that generous authentication is not highly secure. We recommend its use in test environments only.


Property Value




CertificatePath Applicable to U2 certificate store type only. Optional.When you specify a certificate by the CACertificate, MyCertificate, or CRL property, the value for that property is registered internally. When the certificate is loaded into memory to establish an SSL connection, UniData uses this registered path by default to retrieve the certificate.The CertificatePath property allows you to specify different locations in which to search the certificates. Note that this property applies to all certificates in the file. Select one of the following options:n DEFAULT – Specifies the above-described

behavior.

n RELATIVE – UniData looks for the certificate in the current directory under which the client process is running.

n ENV – Enter an environment variable name. With this option, the value of the environment variable is used as the path in which to load the certificates. Note that UniData looks up the environment variable for a client process only the first time the process makes an SSL connection; the value of the environment variable is cached for later reference by that process.

n PATH – Enter the path for loading certificates specified in this property file, or click Browse to find the path. This can be either an absolute path or a relative path. The default path is C:\IBM\UniDK\certs. With this path, the behavior is the same as that of the Default option.


CipherSuite Optional. Specify a suite of ciphers to be used in a specific order in the SSL handshake. If you make no entry, the default of all ciphers supported by the OpenSSL open source library applies.To apply this change, click OK.

Property Value


5-42


AuthenticationDepth Optional. Enter the level at which to stop UniData’s verification process in authentication processing. The default setting is 5, which is a sufficient depth in most cases. If you specify a depth with fewer levels of authentication than actually employed for the certificate, the certificate will not pass authentication.To apply this change, click OK.

CRL Optional. Enter the path of a certificate revocation list (CRL) to be used for this secure connection, or click Browse to find the path. You can specify multiple CRL paths, separating each with a semicolon (;).The CRL is a special certificate published by the certificate authority (CA), containing the serial numbers of certificates that the CA has revoked. If an incoming server certificate is specified, it is checked against the CRL to verify that the certificate has not been revoked before other verification is performed.The format of the CRL can be either PEM or DER.To apply this change, click OK.

Property Value




ClientAuthentication Applicable to a server SSL property list only. Select the appropriate option for this secure connection:n true – Use this setting if the SSL server using this

property list requires client authentication during the SSL handshake. A server that requires client authentication asks the client to send its certificate as an additional security measure.

If you select true, UniData treats the SSL property list as a server property list. For a server property list, you must also specify these properties:– CACertificate– MyCertificate– MyPrivateKey (U2 certificate store type only)– PrivateKeyPassword (U2 certificate store type only)If you leave a required property blank, the U2 SSL Configuration Editor issues an error message after you click Finish, and redisplays the first page on which you to need to enter missing information.

n false – Use this setting if the SSL server does not require client authentication.


Property Value


5-44


5. When you have finished making changes to the properties in this SSL property list, take one of the following actions:

To save your changes to the list, click the Save button in the Property List panel.To save your changes as a new SSL property list, click the Save As button in the Property List panel. The Property List Name and Password dialog box appears. Enter a unique name for the new list, enter a password, and re-enter the password. Click OK.

RandomFileLocation Optional. Enter the absolute path of the directory in which UniData stores random data for the use of SSL operations, or click Browse to find the path. For example, D:\mysys\work is an absolute path. The directory must currently exist and be writable. The default is “.” (the current directory).By default, random data is stored in the directory in which a client process runs. If you want to control where the random data is stored (for example, to limit users’ access to the random data by storing it in a directory that has restricted permissions), use this property to specify the desired directory.When the SSL property list is created, the random data file named U2SSL.rnd is created in the directory specified here.To apply this change, click OK.

Property Value




Deleting an SSL Property ListThis section shows you how to delete an SSL property list. It is important that you use the U2 SSL Configuration Editor to perform this task so the file is properly deleted from the Windows Registry.

To delete an SSL property list:1. In the U2 SSL Configuration Editor window, open the U2 SSL Property


2. In the U2 SSL Property Explorer pane, select the SSL property list to be deleted.

3. Click the X button. The Property List Password dialog box appears.4. If the selected SSL property list has an associated password, enter the

password and click OK. Otherwise, if the property list has no associated password, leave the box blank and click OK.

5. The Please Confirm dialog box appears. The message states that you are about to delete an SSL property list and requests your confirmation to proceed.If you want to cancel the deletion, click Cancel.Otherwise, if you want to complete the procedure and delete the SSL prop-erty list, click OK. The SSL property list is deleted from the Registry.

5-46


Copying an SSL Property ListThis section details the steps for copying an SSL property list. The copy function allows you to create a new list from an existing list.

You can use this function for two different purposes:

Create a list that is similar to the original – When you have a new list, you can edit its properties, specifying the characteristics of a secure connection that is similar to the connection defined by the original list.Rename an existing list and assign it a password – If an existing list has no password or you want to change its password, you can use this function to rename the list and assign a new password. You can then delete the original list if it is no longer needed.

Do not copy an SSL property list by any method other than the U2 SSL Configuration Editor. You must use this tool so the list is entered properly in the Registry.

To copy an SSL property list:1. In the U2 SSL Configuration Editor window, open the U2 SSL Property


2. In the U2 SSL Property Explorer pane, right-click the SSL property list to be copied.

3. Select the Copy option.The Property List Password dialog box appears.



4. To continue with the copy procedure,If the SSL property list to be copied has an associated password, enter the password and click OK.If the property list has no associated password, leave the box blank and click OK.The Console displays the message “List ‘listname’ has been copied successfully.”

Otherwise, to cancel the copy procedure, click Cancel.5. The next task is to paste the copied list in the folder. In the U2 SSL Property

Explorer pane, right-click the U2 SSL Property Lists folder.6. Select the Paste option. The Property List Name and Password dialog

box appears.

7. In the Enter name for new property list box, the system-generated name for the new list is highlighted. Enter a unique name for the new list.

8. Optional. In the Enter password for property list box, assign a password to the new list. To increase the level of security, we strongly recommend that you establish a password for the SSL property list.

9. If you entered a password for the SSL property list, you must verify the password. In the Re-enter password box, type the same password again.

5-48


10. Take one of the following actions:To paste the new list into the selected folder, click OK.The Console displays the message “New list has been created successfully.”To cancel the paste procedure, click Cancel.



Renaming an SSL Property ListThis section provides instructions for renaming an SSL property list. The rename function allows you to change the name of an existing list by overwriting the old name.

Do not rename an SSL property list by any method other than the U2 SSL Configuration Editor. You must use this tool so the list is entered properly in the Registry.

To rename an SSL property list:1. In the U2 SSL Configuration Editor window, open the U2 SSL Property


2. In the U2 SSL Property Explorer pane, right-click the SSL property list to be renamed.

3. Select the Rename option.The Property List Name and Password dialog box appears.

4. In the Enter name for new property list box, enter a unique name for the list.

5-50


5. To continue with the rename procedure,If the SSL property list to be renamed has an associated password, enter the password and click OK.If the property list has no associated password, leave the box blank and click OK.The Console displays the message “List ‘old_listname’ has been renamed to ‘new_listname’.”

Otherwise, to cancel the rename procedure, click Cancel.



Using the Trace FeatureThe U2 SSL Configuration Editor provides a Trace feature for recording all operations performed through the tool on SSL property lists. The events of these operations are written to a file named U2SSLConfig.log and also displayed in the Console pane.

You can use the log to track activity on the lists and to troubleshoot any problems that may arise when performing operations on the lists.

The log is located by default in your C:\temp folder. If you have no \temp folder, the log is written to the \tmp folder. If no \tmp folder exists, the program creates a \temp folder. The file name for the log cannot be changed.

When you initially open the U2 SSL Configuration Editor, Trace mode is turned off by default. This section contains instructions for turning Trace mode on and off.

To use the Trace feature:1. In the U2 SSL Configuration Editor window, choose File.2. If the Trace option is not check-marked, select it.

When Trace mode is active, the Trace option is preceded by a check mark on the menu.

3. With Trace mode turned on, perform operations on SSL property lists as you normally would. The events of these operations are recorded in the log.

4. To turn off Trace mode, choose File ä Trace.5. Navigate to the folder containing the log and open the file to view its

contents.

5-52


Using the Console/Problems ViewThe lower right pane of the U2 SSL Configuration Editor window provides two views that help you manage the tasks performed on SSL property lists:

Console for viewing error/informational messages and a log of transactions performed in Trace mode.Problems for details on any problems encountered while creating, editing, deleting, or performing other transactions on SSL property lists.

You can switch back and forth from Console view to Problems view, or close and open a view as needed.

To use the Console view:1. In the U2 SSL Configuration Editor window, open the Console view if it

is not already displayed. To open this view, choose Window ä Show View ä Console..

2. Optional. If you want to keep a log of transactions performed on SSL property lists, turn on Trace mode. If you need instructions, see “Using the Trace Feature” on page 5-54.

3. Perform transactions on SSL property lists as you normally would. Messages and results from these transactions are displayed in the Console.If Trace mode is active, a log of transactions is displayed in the Console.



4. To close this view, click X on the Console tab.

To use the Problems view:1. In the U2 SSL Configuration Editor window, open the Problems view if

it is not already displayed. To open this view, choose Window ä Show View ä Problems.

2. Perform transactions on SSL property lists as you normally would. The details of any problems encountered are displayed in the Problems view.

3. To close this view, click X on the Problems tab.

Column Description

Description A description of a problem encountered while performing transactions on an SSL property list. Each problem is listed on a separate line.

Resource The name of the file that stores messages regarding the problem.

<MSG_PRBL_HOLDER> The folder that contains the file with messages about the problem.

Location The path of the message file for the problem.

Details in Problems View

5-54

6Chapter

Transaction Processing with Non-RFS Files

Transaction Processing Commands . . . . . . . . . . . . . 6-3 Executing TP and Non-TP Transactions . . . . . . . . . . 6-3 Starting a Transaction . . . . . . . . . . . . . . . . 6-4 Committing a Transaction . . . . . . . . . . . . . . 6-5 Aborting a Transaction . . . . . . . . . . . . . . . 6-6 Testing for an Active Transaction . . . . . . . . . . . . 6-8 Transaction Processing Programming Example . . . . . . . . 6-8Transaction Processing Programming Problems . . . . . . . . . 6-9 Transaction Abort . . . . . . . . . . . . . . . . . 6-9 Degraded Performance . . . . . . . . . . . . . . . 6-13


Prior to this release, UniData supported Transaction Processing (TP) only when the Recoverable File System (RFS) or Journaling was enabled. Beginning at UniData 7.1, Transaction Processing is supported without RFS or Journaling enabled.

Warning: Although you can use Transaction Processing without enabling RFS, we do not guarantee the consistency of your data if you do not turn on RFS. Without RFS, UniData does not support all the ACID properties (Atomicity, Consistency, Isolation, and Durability). In the majority of cases, TRANSACTION COMMIT completes successfully. However, if the system crashes during the commit, some writes in a transaction containing multiple records could fail, causing data inconsistency. In addition, if you use the NO.DUPS option with indexing without RFS, the TRANS-ACTION COMMIT will fail if UniData encounters a duplicate record, but some updates may have already been written to the database. Without RFS, UniData has no way to “rollback” a transaction that encountered a problem during the commit operation, causing data inconsistency.

For nonrecoverable files, you can turn Transaction Processing on or off by changing the value of the LB_FLAG udtconfig parameter. If you set the value of LB_FLAG to 0, Transaction Processing is off for nonrecoverable files and TP semantics are ignored. If you set the value to 1, Transaction Processing is on.

Note: If RFS in on, the LB_FLAG has no effect on recoverable files. You cannot turn off transaction processing for recoverable files if RFS is enabled.

This chapter introduces the UniBasic transaction processing commands. For infor-mation about the basic concepts on which transaction processing is based and about using UniData locks to ensure database consistency, see Developing UniBasic Applications.



Transaction Processing CommandsThe following UniBasic commands and the variable @TRANSACTION let you create UniBasic programs with transaction processing safeguards:

TRANSACTION STARTTRANSACTION COMMITTRANSACTION ABORT@TRANSACTION

Warning: When including WRITE statements within a transaction, you must code an ON ERROR clause that takes appropriate action to notify the user and stop the trans-action. If the transaction is not aborted by the ON ERROR clause, processing continues, and the transaction commits inappropriately.

Executing TP and Non-TP TransactionsIBM recommends that you NOT execute at the same time applications that perform transactions and those that do not. If both types of applications make updates to the same UniData file at the same time, indexes based on virtual fields might not be updated, and the only notification you will receive will be a warning recorded in the sm.log file.

The following demonstrates a scenario that results in indexes based on virtual fields not being updated because TP and non-TP applications are running simultaneously:

1. The TP application initiates a transaction by executing the UniBasic TRANSACTION START command or by executing any UniData SQL transaction-initiating command.

2. The TP transaction writes a new record to a recoverable file. (The write is held pending the transaction commit.)

3. The non-TP application executes a write, creating a record with the same @ID as the one created in Step 2.

6-3


4. When the TP transaction commits, UniData discovers that the record now exists, so it changes its insert operation to an update. However, virtual fields are resolved and their index entries are created when a write is executed within a transaction, not when the transaction is committed. Because the operation has become an update rather than insert, no new alternate key index entry is made for the new record.

Starting a TransactionUse the UniBasic TRANSACTION START command to initiate a transaction.

Syntax:

TRANSACTION START {THEN statement(s) | ELSE statement(s)}

The UniBasic TRANSACTION START command initiates a new transaction and temporarily stores all updates until a the transaction is committed or aborted. You must specify a THEN or an ELSE clause, but can specify both.

Note: UniBasic does not support nested transactions. When UniData encounters a nested transaction, the ELSE clause executes.

STATUS Function Values

After you execute TRANSACTION START, the STATUS function returns one of the values described in the following table.

For information about the UniBasic STATUS function, see the UniBasic Commands Reference.

Value Description

0 Successful transaction start.

1 Indicates a nested start.

errno Indicates an error message.

STATUS Values



Example

In the following example, the TRANSACTION START command starts the trans-action process:

TRANSACTION START ELSE IF STATUS() = 1 THEN DISPLAY "A Transaction had already been started, NESTED Transactions" DISPLAY "are NOT Allowed. (Contact System Administrator)" INPUT PAUSE,1_ END ELSE END

Committing a TransactionUse the UniBasic TRANSACTION COMMIT command to commit a transaction.

Syntax:

TRANSACTION COMMIT {THEN statement(s) | ELSE statement(s)}

The UniBasic TRANSACTION COMMIT command concludes the active trans-action. UniData writes all pending updates to the appropriate files. You must specify a THEN or an ELSE clause, or both. If a TRANSACTION COMMIT statement executes in the absence of an active transaction, UniData executes the ELSE clause.

Successful Commit

UniData performs the following steps during a transaction commit:

1. Disables the break key.2. Writes all updates.3. Releases all records locked by this process.4. Executes the THEN clause, if included.5. Enables the break key.

Unsuccessful Commit

If the transaction cannot commit and the ELSE clause executes, UniData performs the following steps:

6-5


1. Aborts the transaction without writing records.2. Releases all records locked inside the transaction.

STATUS Function Values

After you execute TRANSACTION COMMIT, the STATUS function returns one of the values described in the following table.

Example

In the following example, the TRANSACTION COMMIT command ends the trans-action process and writes the new record to the database:

TRANSACTION COMMIT ELSE IF STATUS() = 1 THEN DISPLAY "The TRANSACTION was not started" END ELSE DISPLAY "The TRANSACTION could not be committed." END

Aborting a TransactionUse the UniBasic TRANSACTION ABORT command to abort active transactions.

Syntax:

TRANSACTION ABORT

The UniBasic TRANSACTION ABORT command cancels the active transaction, discarding the pending writes. As a result, none of the updates associated with the transaction occur.

In addition to encountering a TRANSACTION ABORT statement, a transaction could abort due to any of several conditions, including:

Value Description

0 Transaction committed.

1 Transaction not started.

3 Transaction cannot commit.

STATUS Values



A program finishes before a transaction commit is issued (STOP or END).The program CHAINs to another program.An error terminates the program before a transaction commit is issued.A user breaks out of the program before a transaction commit is issued. This can be prevented programmatically by disabling the interrupt key during the transaction by executing the ECL command PTERM -BREAK OFF.The user running the program is logged out, or the process is killed before a transaction commit is issued.

The system handles these abort conditions in the same way it does TRANSACTION ABORT.

Note: You should be aware of these various abort conditions and control the resulting action from within the program where possible and appropriate. For example, if no ON ERROR clause is included in a write statement and the write fails, the program aborts, terminating the transaction.

Example

In the following example, the transaction process aborts if var is 10:

TRANSACTION STARTTHEN PRINT "Transaction started."ELSE PRINT "Transaction start failed, STATUS = ":STATUS(); STOP

READU var FROM file.var, record1var += 2IF var = 10 THEN TRANSACTION ABORT; GOTO ERR:WRITE var TO file.var, record1

TRANSACTION COMMITTHEN PRINT "Transaction committed."ELSE PRINT "Transaction Aborted, STATUS = ":STATUS(); STOP

6-7


Testing for an Active TransactionThe variable @TRANSACTION lets you test for an active transaction. The following table describes the possible values for @TRANSACTION.

Transaction Processing Programming ExampleThe following program segment illustrates Transaction Processing. Note that the WRITE commands are enclosed in a transaction, and that both or neither are committed.

WRITE_RECORD: * The record(s) have been updated. Make sure that if the RECOVERABLE* FILE System is operational that either BOTH records are updated, or that* None are (using Transaction processing commands).

TRANSACTION START ELSE IF STATUS() = 1 THEN DISPLAY "A Transaction had already been started, NESTED Transactions" DISPLAY "are NOT Allowed. (Contact System Administrator)" INPUT PAUSE,1_ END ELSE END

WRITE CLIENT.REC ON CLIENT_FILE,CLIENT_NUMBER WRITE ORDER.REC ON ORDERS_FILE,ORDER_NUMBER

TRANSACTION COMMIT ELSE IF STATUS() = 1 THEN DISPLAY "The TRANSACTION was not started" END ELSE DISPLAY "The TRANSACTION could not be committed." END

END RETURN

Value Description

1 A transaction is active.

0 A transaction is not active.

@TRANSACTION Values



Transaction Processing Programming ProblemsProgramming problems could, in some cases, degrade performance and, in other cases, cause UniData to abort transactions. This section points out some of these problems and suggests ways of overcoming them. Many problems are caused or compounded by improper use of UniData locks. For more information about UniData locks, see Developing UniBasic Applications.

Transaction AbortThe following problems cause UniData to abort transactions:

DeadlocksWhen two or more programs are waiting for each other to release records, UniData aborts one of the transactions to unlock its records and remove the deadlock. You can reduce the likelihood of deadlocks occurring by impos-ing a protocol on the order data items can be updated. For example, the protocol might let programs lock record B only after locking record A. If all programs on the system follow this protocol, deadlocks will be avoided.Upgrading LocksIf two users share a lock on a record, and one or both tries to upgrade to a U lock, one user receives the upgraded lock, and UniData aborts the other transaction. Execute the LOCKED clause in the locking statement to abort the transaction, but not the program.Nested Transactions UniData does not support nested transactions. A TRANSACTION START within another active transaction executes the ELSE clause, if specified, and aborts the transaction if none is specified. Use the @TRANSACTION vari-able to find out if a transaction is active before calling an external subroutine.Called Programs and Subroutines If a you start a transaction within a called program or subroutine, and the subroutine stops abnormally, UniData could return control to the calling program with the transaction still active. To avoid this, include the ON.ABORT clause in the subroutine to stop program execution in the event of a problem affecting a subroutine.

6-9


Transaction Processing Limitations UniData does not support transaction processing outside of UniBasic and UniData SQL. Although you can include EXECUTE statements within a transaction, you cannot execute any of the following types of operations with the EXECUTE:

UniData SQL (use EXECUTESQL)UEntry/UReportFile-level operations on recoverable files (for example, the UniBasic CLEARFILE commands and the following ECL commands: CLEAR.FILE, DELETE.FILE, RESIZE, CREATE.FILE, CREATE.INDEX, BUILD.INDEX, DELETE.INDEX, CNAME).

If UDT.OPTION 35 is on when you issue an EXECUTE statement, UniData creates a new user and processes it independently from the original UniBa-sic program, causing unpredictable results in TP. Make sure UDT.OPTION 35 is off when using TP.



Examples

Recovering from a deadlock – In this example, a deadlock results because two programs are waiting for each other to release the same record (steps 3 and 4). UniBasic aborts Transaction 2 to break the deadlock when this transaction tries to upgrade to an exclusive lock. However, the LOCKED clause (LOCKED TRANS-ACTION ABORT) in the RECORDLOCKU statement tells UniBasic to abort the transaction only, thus preventing the program from aborting.

Step Transaction 1 Transaction 2

1 TRAN1: TRANSACTION START THEN PRINT "Transaction started." READL var1 FROM file.var, record1 ELSE PRINT "File not found."

TRAN2: TRANSACTION START THEN PRINT "Transaction started."

2 READL var1 FROM file.var, record1 ELSE PRINT "File not found."

3 RECORDLOCKU var1 LOCKED TRANSACTION ABORT; GOSUB TRAN1

4 var += 2 WRITE var TO file.var, record1 TRANSACTION COMMIT THEN PRINT "Transaction committed."

RECORDLOCKU var1 LOCKED TRANSACTION ABORT; GOTO TRAN2 var += 2 WRITE var TO file.var, record1 TRANSACTION COMMIT THEN PRINT "Transaction committed."

Avoiding Program Abort on Deadlock

6-11


Nested transactions – The next three examples demonstrate creating and avoiding nested transactions. In this first program segment, the main routine starts a trans-action, and then calls a subroutine that contains a TRANSACTION START. This always results in an aborted transaction because transactions cannot be nested.

TRANSACTION START ELSE PRINT "Transaction error.";STOPREADU var FROM file.var, record1 ELSE PRINT "File not found."IF var = "" THEN CALL SUBRZWRITE var TO file.var, record1

TRANSACTION COMMIT ELSE PRINT "Transaction aborted."

SUBROUTINE SUBRZTRANSACTION START ELSE PRINT "Transaction error.";STOP

READU var1 FROM file.var, record2 ELSE PRINT "File not found."var1 += 2WRITE var1 TO file.var, record2


The next program segment avoids the problem demonstrated in the previous example. The subroutine tests @TRANSACTION for an active transaction before starting its own transaction.

TRANSACTION START ELSE PRINT "Transaction error.";STOPREADU var FROM file.var, record1IF var = "" THEN CALL SUBRZWRITE var TO file.var, record1


SUBROUTINE SUBRZIF @TRANSACTION = 1 THEN RETURNTRANSACTION START ELSE PRINT "Transaction error.";STOP

READU var1 FROM file.var, record2var1 += 2WRITE var1 TO file.var, record2


In the following program, the subroutine tests for an active transaction with @TRANSACTION before an EXECUTE statement:

TRANSACTION STARTELSE PRINT "Transaction not started."; STOP

READU var FROM file.var, record1IF var = "" THEN CALL SUBRZWRITE var TO file.var, record1


SUBROUTINE SUBRZIF @TRANSACTION = 0 THEN EXECUTE "CLEAR.FILE file.var" ELSE

RETURNRETURN



Degraded PerformanceThis section discusses causes and solutions of degraded performance.

Locked Records If you lock records within a transaction, those records remain locked until you commit or abort the transaction. If your program performs a number of operations, especially requesting user input, you increase the waiting period for other users trying to access these records. To avoid this problem, put input statements before the TRANSACTION START. If you must include requests for user interaction within a transaction, include the WAITING clause in the INPUT statement to time out if the user does not respond in a reasonable amount of time. Long Transactions Performing a number of operations inside a transaction also contributes to performance degradation. By minimizing the number of operations in the transaction, you can improve performance.

Note: Protecting data by locking records and using transaction processing can contribute to reduced efficiency and system performance.

Example

In the following example, the INPUT times out after five minutes if the user does not respond:

READU var FROM file.var, record1 ELSE PRINT "File not found."INPUT var WAITING 300TRANSACTION START ELSE PRINT "Transaction not started." STOP

WRITE var TO file.var, record1TRANSACTION COMMIT ELSE PRINT "Transaction aborted."

6-13

7Chapter

Replication Enhancements

Monitoring Replication . . . . . . . . . . . . . . . . . 7-2 Starting the Replication Monitor . . . . . . . . . . . . 7-4 Replication Group Status Table . . . . . . . . . . . . . 7-7Replication Action Trigger. . . . . . . . . . . . . . . . 7-11 Replication Action Trigger Example . . . . . . . . . . . 7-13


Monitoring ReplicationUniData provides a tool to monitor UniData Data Replication.

The Replication Monitoring tool monitors connection status, data transferring, and whether or not the publisher and subscriber systems are synchronized.

To access the Replication Monitoring tool, from UniAdmin, double-click Repli-cation, then click Monitor Replications. The Replication Monitoring window appears, as shown in the following example:

7-2


The Replication Monitor can monitor two types of replications:

Publishing Replication – the data replication from the local system to a remote subscribing system, including all replication groups involved. A publishing system can have more than one Publishing Replication defined. Subscribing Replication – the data replication from a remote publishing system to the local system, including all replication groups involved. A subscribing system can have more than one Subscribing Replication defined.

Replication Name

Each UniData Replication is assigned a unique name on one system, consisting of the replication type and the remote system name. A replication type can be one of the following:

ImmediateStandby ImmediateRealtimeStandby RealtimeDeferred

Choose the name of the replication you want to monitor from the Replications box.

Note: If a replication has failed over, it still belongs to the same Replication as it did before the failover, but the name changes.

Refreshing Interval

You can define how often to refresh the Replication Monitor. The defaul interval is 3 seconds. Choose the number of seconds to refresh the monitor in the Interval in seconds box.



Starting the Replication MonitorTo start the Replication Monitor, click Start. A window similar to the following example appears:

Replication Status

The Replication Status indicates whether the publisher and subscriber are connected. The status can be one of the following:

Green – The Publisher and subscriber are connected for all groups involved in the Replication.Yellow – At least one of the replication groups has been suspended by an administrator.Red – At least one the replication groups has terminated abnormally.

7-4


Sync Status

The Sync status indicates whether the subscribing database is synchronized with the publishing database. The status can be one of the following:

Green – The pubishing and subscribing databases are synchronized.Yellow – There are pending updates that have not been applied to the subscribing database.

Packet Received

The number of packets received from the other party of the Replication. Types of packets include data packets, confirmation packets, heartbeat packets and other control packets. Monitoring this information indicates whether the physical connection between the publishing database and the subscribing database is satisfactory. This number is cumulative from the last time UniData was started or UniData Replication was reconfigured.

Packet Sent

The number of packets that have been sent to the other party of the Replication. Types of packets include data packets, confirmation packets, heartbeat packets and other control packets. Monitoring this information indicates whether the physical connection between the publishing database and the subscribing database is satis-factory. This number is cumulative from the last time UniData was started or UniData Replication was reconfigured.

Subscriber Received

The number of data records that have been received from the other party of the repli-cation. This number is cumulative from the last time UniData was started or UniData Replication was reconfigured.

Note: When monitoring a publishing replication this number may be out of date if the Replication Status is not green.



Subscriber Committed

The number of data records that have been committed on the subscribing database. This number is cumulative from the last time UniData was started or UniData Repli-cation was reconfigured.

Note: When monitoring a publishing replication this number may be out of date if the Replication Status is not green.

Publisher Committed

The number of data records that have been committed on the publishing database. This number is cumulative from the last time UniData was started or UniData Replication was reconfigured.

TP Total

The sum of all transactions committed in the replication groups on the local system. This number is cumulative from the last time UniData was started or UniData Replication was reconfigured.

CGTPs Resolved

The sum of all transactions committed across more than one replication group on the local system. This number is cumulative from the last time UniData was started or UniData Replication was reconfigured.

7-6


Replication Group Status TableThe Replication Group Status table displays the current status of each

replication group belonging to the Replication you specify.

The following information is displayed in the Replication Group Status table:

Group Name – The name of the replication group.Conn. Status – The connection status between the publishing system and the subscribing system in the group. The status can be one of the following:

Green – The publisher and subscriber are connected in this group.Yellow – The Replication group has been suspended by an administrator.Red – The Replication group has terminated abnormally.



In-Sync – Inicates whether the subscribing files are synchronized with the publishing files in the group. The In-Sync status can be one of the following:

Green – The publishing and subscribing databases are synchronized.Yellow – There are pending updates in this Replication Group that have not been applied to the subscribing database.

Rep. Status – The current Replication Group status. The status can be one of the following on the publishing system:

REP_RUNNING – The replication is running.REP_SYNCING – The replication is performing synchronization.REP_SUSPENDED – The replication is suspended.REP_DO_SUSPEND – The replication is in the process of suspending.REP_EXIT – The replication is suspended due to an abnormal termination.

The status can be one of the following on the subscribing system:SUB_STOP – The replication is stopped.SUB_EXIT – The subscribing system has exited abnormally.SUB_SHUTDOWN – Replication on the subscribing system has been shut down.SUB_RUNNING – Replication on the subscribing system is running.SUB_DO_RECONFIG – A reconfiguration process is occurring on the subscribing system.SUB_DO_SUSPEND – Replication is suspended on the subscribing system.SUB_SYNCING – Replication is performing synchronization on the subscribing system.SUB_RESYNCING – Replication is performing resynchronization on the subscribing system.SUB_DO_FAILOVER – The subscribing system is performing a failover.

7-8


Changed By – The event or reason that caused the Replication status to change. If the status changed due to an exception, this column displays the error category and error code. A detailed error string is available in the tooltips. The following list describes the valid events or reasons can cause a change in the Replication status:

PUB_STARTUP – The publishing system started.SYS_STARTUP – The UniData system started.AUTO_SYNC – Replication is automatically resuming.PUB_REQUEST – A request was sent from the publishing system, or an event occurred on the publishing system resulting in a change of status. SUB_REQUEST – A request was sent from the subscribing system, or an event occurred on the subscribing system resulting in a change of status.DBA_ORDER – The system administrator issued a request resulting in a change of status.RECONFIG – Replication is reconfiguring. FAILOVER – A failover has occurred.CM_REQUEST – When running the Recoverable File System, the CM daemon is unable to finish a checkpoint until all standby subscribing systems have received the replication log generated before a checkpoint begins. If this does not happen in the configurable timeframe, the CM daemon requests the repmanager process to suspend the replication.SCHEDULED – The repmanager process can only schedule a SYNC command for DEFERRED replication.SYNCDONE – A sychronization process succeeded.REMOTE_REQ – A subsribing system can request to execute a SYNC command on the publishing system. CGTP_SUSPEND – Cross-group transaction processing is suspended.

#Recv’d – The number of packets received in the group. Monitoring this number indicates if the physical connection between the publishing system and subscribing system is satisfactory.



#Sent – The number of packets sent in the group. Monitoring this number indicates if the physical connection between the publishing system and subscribing system is satisfactory. This number is cumulative from the last time UniData was started or UniData Replication was reconfigured.Data Replicated – The total amount of data, in bytes, replicated in the group. On a publishing system this field represents the total amount of data sent out. On a subscribing system, this field represents the total amount of data received from the publishing system.This number is cumulative from the last time UniData was started or UniData Replication was reconfigured. SubGot – The Log Sequential Number of the latest replication log received by the subscribing system. This number is cumulative from the last time UniData was started or UniData Replication was reconfigured.SubDone – The Log Sequential Number of the latest replication log committed to the subscribing database. This number is cumulative from the last time UniData was started or UniData Replication was reconfigured.PubDone – The Log Sequential Number of the latest replication log committed to the publishing database. This number is cumulative from the last time UniData was started or UniData Replication was reconfigured.#TP – The number of transactions resolved in this group, including cross-group transactions. This number is cumulative from the last time UniData was started or UniData Replication was reconfigured.

.

7-10


Replication Action TriggerA replication action trigger allows you to define an action to take should replication abnormally terminate, making the Replication Status Indicator Red. The repmanager process initializes the action defined in the trigger whenever it receives a replication exception notice.

The replication action trigger is a shell script on UNIX platforms, or a batch program on Windows platforms. Define the full path to the trigger using the EXCEPTION_ACTION clause in the repsys file. For example, if you define a repli-cation action trigger as UDRepExceptionAction.sh in the /usr/ud71 directory, set the EXCEPTION_ACTION clause as:

EXCEPTION_ACTION=/usr/ud71/UDRepExceptionAction.sh

UniData Data Replication passes parameters to the replication action trigger through environment variables. You can use the following environment variables in the repli-cation action trigger program:

UNIREP_REMOTESYS – the remote system name of the Replication. UNIREP_REPTYPE defines the type of Replication. UNIREP_GRPNAME – the replication group name where the exception occurred.UNIREP_ERRCODE – the exception error code.UNIREP_ERRSTRING – the exception error string.

If a Replication contains multiple replication groups, UniData Data Replication treats the interruption of each group as a separate event, and executes the trigger for that group. If a single group belongs to multiple Replications, each interruption of the Replication triggers the replicaton action trigger to run. UNIREP_REMOTESYS and UNIREP_REPTYPE define the Replication where the exception occurred.

IBM recommends using the replication action trigger to automatically ping or email the system administrator to advise that an exception occurred. We do not recommend using it to automatically failover to a standby system.

Note that the replication action trigger only executes if an unexpected event that suspends UniData Data Replication occurs. If a system administrator executes a command that suspends UniData Data Replication, the replication action trigger is not invoked.



When the replication action trigger is executed, the repmanager process writes a message similar to the following example in the rm.log:

Execute Replication Exception Action program <program_path>

7-12


Replication Action Trigger ExampleThe following example illustrations a replication action trigger shell script:

#!/bin/sh

## Define Replication Status Code that returned by ud_repadmin report command## Publishing group Status CodesPUB_STOP=1 #/* group is normally stopped */PUB_EXIT=2 #/* group has quit abnormally.*/PUB_SHUTDOWN=3 #/* group is doing shutdown */PUB_RUNNING=4 #/* group is in running mode */PUB_DO_RECONFIG=5 #/* group is doing reconfigure */PUB_DO_FAILOVER=7 #/* group is doing failover */# Publishing Replication Status CodesREP_RUNNING=11 #/* replication is in running mode */REP_SUSPENDED=12 #/* replication is in suspension mode */REP_SYNCING=13 #/* replication is in syncing mode */REP_DO_SUSPEND=14 #/* replication is doing suspend */REP_DO_SYNC=15 #/* replication is doing sync */REP_EXIT=16 #/* replication exit */# Subscribing Replication/group status codes.SUB_STOP=21 #/* group is normally stopped */SUB_EXIT=22 #/* group has quit abnormally.*/SUB_SHUTDOWN=23 #/* group is doing shutdown */SUB_RUNNING=24 #/* replication is in running mode */SUB_DO_RECONFIG=25 #/* group is doing reconfigure */SUB_DO_SUSPEND=27 #/* replication is suspending */SUB_SYNCING=28 #/* replication is doing sync */SUB_DO_FAILOVER=29 #/* group is doing failover */SUB_RESYNCING=30 #/* group is doing re-syncing */

# Defines Replication GroupsREP_GROUPS="rwtest1 rwtest2 rwtest3"

# Show exception time echo dstring=`date`echo "UniData Replication Exception called at:"$dstring echo "UDTBIN=$UDTBIN"

# Show environment variables passed from replication systemecho "UNIREP_REMOTESYS="$UNIREP_REMOTESYS echo "UNIREP_REPTYPE="$UNIREP_REPTYPE echo "UNIREP_GRPNAME="$UNIREP_GRPNAME echo "UNIREP_ERRCODE="$UNIREP_ERRCODE echo "UNIREP_ERRSTRING="$UNIREP_ERRSTRING

# Now Paging to DBA#sendmail ...

# Now Check all groups are suspended.# Using ud_repadmin REPORT command on each of the groups# We will support ud_repadmin REPORT -XML on 7.2. DBA can use this # command to get an formatted report for all groups.all_suspended=0try=0



while [ $all_suspended = 0 -o $try -gt 10 ]do

sleep 5all_suspended=1for grpname in $REP_GROUPSdo

if [ $all_suspended ] then

# Run ud_repadmin report commandcmd="$UDTBIN/ud_repadmin REPORT GROUP $grpname DISTRIB

$UNIREP_REMOTESYS"echo "Now running:"$cmd $cmd returncode=$?echo "returncode=$returncode"if [ $returncode -gt 30 ]#report command failedthen

echo "Report command failed, exit."exit 2

elif [ $returncode = $REP_SUSPENDED -o $returncode = $SUB_STOP -o $returncode = $SUB_EXIT ]

thenecho "Group $grpname is suspended."

elseall_suspended=0

fifi

donetry = `expr $try + 1`

done

# Try automatically sync and resumesleep 60cmd="$UDTBIN/ud_repadmin sync -wait -verbose $UNIREP_REMOTESYS"echo "Now running:"$cmd $cmd echo "Return code="$?

exit 0

7-14

unidata 7.1 new features - amazon s3s3.amazonaws.com/zanran_storage/ unidata 7.1 new features the...

Documents