U2 Extensible Administration December 2015 DBT-DEC2015-XA ... · U2 Extensible Administration Tool User Guide Version Dec2015 December 2015 DBT-DEC2015-XA-AM-01

U2 Extensible AdministrationTool

User Guide

Version Dec2015

December 2015DBT-DEC2015-XA-AM-01

2

NoticesEdition

Publication date: December 2015Book number: DBT-DEC2015-XA-AM-01Product version: Version Dec2015

Copyright© Rocket Software, Inc. or its affiliates 2005-2015. All Rights Reserved.

Trademarks

Rocket is a registered trademark of Rocket Software, Inc. For a list of Rocket registered trademarks goto: www.rocketsoftware.com/about/legal. All other products or services mentioned in this documentmay be covered by the trademarks, service marks, or product names of their respective owners.

Examples

This information might contain examples of data and reports. The examples include the names ofindividuals, companies, brands, and products. All of these names are fictitious and any similarity tothe names and addresses used by an actual business enterprise is entirely coincidental.

License agreement

This software and the associated documentation are proprietary and confidential to Rocket Software,Inc. or its affiliates, are furnished under license, and may be used and copied only in accordance withthe terms of such license.

Note: This product may contain encryption technology. Many countries prohibit or restrict theuse, import, or export of encryption technologies, and current use, import, and export regulationsshould be followed when exporting this product.

http://www.rocketsoftware.com/about/legal

3

Corporate informationRocket Software, Inc. develops enterprise infrastructure products in four key areas: storage, networks,and compliance; database servers and tools; business information and analytics; and applicationdevelopment, integration, and modernization.

Website: www.rocketsoftware.com

Rocket Global Headquarters77 4th Avenue, Suite 100Waltham, MA 02451-1468USA

To contact Rocket Software by telephone for any reason, including obtaining pre-sales informationand technical support, use one of the following telephone numbers.

Country Toll-free telephone number

United States 1-855-577-4323Australia 1-800-823-405Belgium 0800-266-65Canada 1-855-577-4323China 800-720-1170France 08-05-08-05-62Germany 0800-180-0882Italy 800-878-295Japan 0800-170-5464Netherlands 0-800-022-2961New Zealand 0800-003210South Africa 0-800-980-818United Kingdom 0800-520-0439

Contacting Technical Support

The Rocket Customer Portal is the primary method of obtaining support. If you have currentsupport and maintenance agreements with Rocket Software, you can access the Rocket CustomerPortal and report a problem, download an update, or find answers to in the U2 Knowledgebase.To log in to the Rocket Customer Portal or to request a Rocket Customer Portal account, go towww.rocketsoftware.com/support.

In addition to using the Rocket Customer Portal to obtain support, you can send an email [email protected] or use one of the following telephone numbers.

Country Telephone number

North America +1 800 729 3553United Kingdom/France +44 (0) 800 773 771 or +44 (0) 20 8867 3691Europe/Africa +44 (0) 20 8867 3692Australia +1 800 707 703 or +61 (0) 29412 5450New Zealand +0800 505 515

http://www.rocketsoftware.com

http://www.rocketsoftware.com/support

mailto:[email protected]

4

Contents

Notices................................................................................................................................................................................... 2

Corporate information......................................................................................................................................................... 3

Chapter 1: Getting started................................................................................................................................................... 8Welcome to XAdmin help.........................................................................................................................................8Installing and updating the DBTools using the Eclipse Update Manager.............................................................8XTOOLSUB................................................................................................................................................................. 8

Installing XTOOLSUB for UniData on Windows.......................................................................................... 9Installing XTOOLSUB for UniVerse on Windows....................................................................................... 10Installing XTOOLSUB for UNIX/Linux for UniData.................................................................................... 11Installing XTOOLSUB for UNIX/Linux on UniVerse....................................................................................11Installing XTOOLSUB on Windows............................................................................................................ 12

Chapter 2: XAdmin overview..............................................................................................................................................14Starting XAdmin...................................................................................................................................................... 14XAdmin workspace................................................................................................................................................. 14Establishing server connections............................................................................................................................ 16

U2 server definitions.................................................................................................................................. 16Creating U2 server definitions................................................................................................................... 16

Viewing or editing advanced settings of a U2 server definition.......................................................................... 17Specifying a command to run on connection.......................................................................................... 18

Setting up SSL settings for a U2 server definition............................................................................................... 18Editing U2 server definitions..................................................................................................................................19Importing an existing U2 server definition........................................................................................................... 19Connecting to U2 servers.......................................................................................................................................20Disconnecting from U2 servers..............................................................................................................................20Deleting U2 server definitions............................................................................................................................... 20

Chapter 3: Administering U2 accounts............................................................................................................................. 21U2 accounts overview............................................................................................................................................ 21Initiating Accounts tasks........................................................................................................................................ 21Adding or viewing U2 accounts............................................................................................................................. 21Creating a U2 account............................................................................................................................................21

Chapter 4: Managing disk space........................................................................................................................................23Disk space usage.................................................................................................................................................... 23Initiating disk space tasks......................................................................................................................................23Viewing disk space usage.......................................................................................................................................23

Chapter 5: Managing Secure Sockets Layer (SSL)............................................................................................................25Secure Sockets Layer (SSL) technology................................................................................................................25Initiating SSL tasks................................................................................................................................................. 25Setting up and managing SSL............................................................................................................................... 25Generating certificate signing requests................................................................................................................ 26

Starting the Generate Certificate Signing Request wizard...................................................................... 26Specifying a file and algorithm for the CSR..............................................................................................26Defining properties of the CSR.................................................................................................................. 26Selecting a key pair option........................................................................................................................ 27Supplying key pair parameters................................................................................................................. 27Entering a password for the private key file............................................................................................ 28Verifying the status of generating the certificate.....................................................................................28

Generating SSL certificates....................................................................................................................................29Starting the Generate SSL Certificate wizard........................................................................................... 29Specifying a certificate file name.............................................................................................................. 29

Contents

5

Setting the validity period for a new certificate.......................................................................................30Selecting a certificate type........................................................................................................................ 30Optional: Defining certificate extensions..................................................................................................31

Selecting required files to generate a certificate................................................................................................. 31Selecting the private key file of the CSR...................................................................................................31Selecting the signing certificate file and private key file......................................................................... 32Entering the password for the private key file......................................................................................... 32

Creating security context records......................................................................................................................... 33Starting the Security Context Record wizard........................................................................................... 33Specifying the record ID and protocol...................................................................................................... 33Selecting server or client usage................................................................................................................ 34Setting authentication properties............................................................................................................. 34

Setting server authentication properties......................................................................................34Setting client authentication properties.......................................................................................35Adding trusted peer names........................................................................................................... 36

Selecting the certificate path rule.............................................................................................................36Associating certificates to the security context........................................................................................37

Associating server/client certificates to a security context......................................................... 37Associating a server certificate to a security context...................................................................38Optional: Associating a client certificate to a security context................................................... 38Selecting the private key file for the server or client certificate..................................................39Optional: Associating CA certificates to a security context record..............................................39

Selecting or generating a random file...................................................................................................... 40Optional: Generating a random file.............................................................................................. 40Adding seed source files................................................................................................................ 41

Optional: Specifying ciphers...................................................................................................................... 41Optional: Specifying a certificate revocation list..................................................................................... 41Setting a password for the SCR.................................................................................................................42Verifying the status of generating the SCR............................................................................................... 42

Configuring SSL for U2 servers.............................................................................................................................. 42

Chapter 6: Managing Automatic Data Encryption............................................................................................................43Automatic data encryption (ADE) operations.......................................................................................................43Initiating data encryption tasks............................................................................................................................ 43Administering data encryption.............................................................................................................................. 43Managing encryption keys..................................................................................................................................... 44

Opening the Keys tool................................................................................................................................44Creating encryption keys........................................................................................................................... 44Viewing encryption key details..................................................................................................................44Deleting encryption keys............................................................................................................................45

Chapter 7: Managing the credential wallet...................................................................................................................... 46U2 servers token-based authentication................................................................................................................46Overview of IdM and token-based authentication...............................................................................................46Token-based authentication..................................................................................................................................47

Authentication token..................................................................................................................................47Credential mapping record....................................................................................................................................47

Credential wallet.........................................................................................................................................48Adding a mapping record.......................................................................................................................... 48Sending the token to the U2 Server..........................................................................................................50

Chapter 8: Managing licenses............................................................................................................................................ 51Updating license information................................................................................................................................ 51Obtaining an authorization code.......................................................................................................................... 52Configuring Account-based licenses..................................................................................................................... 52

Chapter 9: Managing U2 Data Replication........................................................................................................................53Managing U2 Data Replication.............................................................................................................................. 53

Contents

6

Defining replication systems..................................................................................................................................54Adding a publishing group.....................................................................................................................................55Adding a subscribing group................................................................................................................................... 57Optional: Changing a replication group definition.............................................................................................. 58Verifying the account defaults...............................................................................................................................58Starting replication.................................................................................................................................................59Replication disablement........................................................................................................................................ 60Replication pacing.................................................................................................................................................. 60Diagnosis utility...................................................................................................................................................... 61Replication recovery log........................................................................................................................................ 61Monitoring replication............................................................................................................................................61

The Replication Status Monitor tab.......................................................................................................... 64

Chapter 10: Managing Locks in UniVerse..........................................................................................................................69File and record locks.............................................................................................................................................. 69Group locks............................................................................................................................................................. 70Clearing locks..........................................................................................................................................................71

To clear a file or record lock......................................................................................................................71To clear a group lock................................................................................................................................. 71To clear all locks.........................................................................................................................................71

Chapter 11: Managing Locks in UniData...........................................................................................................................72File/Record Locks tab.............................................................................................................................................72System Resource Locks tab................................................................................................................................... 73Lock Waiting Queue tab.........................................................................................................................................74Clearing a lock........................................................................................................................................................ 75Managing Deadlocks in UniVerse.......................................................................................................................... 75

Chapter 12: Managing Deadlocks in UniVerse.................................................................................................................. 76Starting and stopping the deadlock manager..................................................................................................... 76Using the uvdlockd command...............................................................................................................................77Resolving deadlocks automatically.......................................................................................................................77

Chapter 13: Managing Windows Telnet Sessions............................................................................................................. 78Modifying the telnet session parameters..............................................................................................................79

Changing the telnet session port number................................................................................................ 79Defining the user policy............................................................................................................................. 79Setting the telnet connection parameters................................................................................................79Setting keep alive parameters...................................................................................................................80Specify logon banner................................................................................................................................. 80

Administering UniVerse users................................................................................................................................ 80Adding a new UniVerse user...................................................................................................................... 81

Add a UniVerse domain user......................................................................................................... 82Adding a local machine user......................................................................................................... 82

Configuring UniData user profiles......................................................................................................................... 83Default user profile.....................................................................................................................................83Specify default shell................................................................................................................................... 84Specify startup directory............................................................................................................................84Specify arguments...................................................................................................................................... 84Specify UDTHOME.......................................................................................................................................84Determine ANSI version............................................................................................................................. 84Determine how to map characters........................................................................................................... 85Prompt for working directory....................................................................................................................85Customizing user profiles...........................................................................................................................85

Generated profiles.......................................................................................................................... 86

Chapter 14: UniVerse file utilities...................................................................................................................................... 89Administering UniVerse files.................................................................................................................................. 89

Listing files in a UniVerse account............................................................................................................ 89

Contents

7

View file properties.....................................................................................................................................90Base information............................................................................................................................ 91Header information........................................................................................................................ 91National Language Support (NLS) information............................................................................92Transaction logging information...................................................................................................93Indexes information....................................................................................................................... 94Backup and replication information............................................................................................. 95

View file statistics....................................................................................................................................... 96File information.............................................................................................................................. 97File statistics................................................................................................................................... 97

Running file diagnostics.............................................................................................................................98Determine diagnostic level............................................................................................................ 98Specify types of error report..........................................................................................................99Specify output location..................................................................................................................99Diagnostics test...............................................................................................................................99Viewing errors............................................................................................................................... 100

Repairing damaged files.......................................................................................................................... 100Determine diagnostic level.......................................................................................................... 101Specify types of error report........................................................................................................101Specify output location................................................................................................................101Rerun repair program...................................................................................................................102Exit the program...........................................................................................................................102

Chapter 15: Administering UniData Files........................................................................................................................ 103Administering the Checkover file tool.................................................................................................................103Administering the Convcode file tool..................................................................................................................104Administering the Convdata file tool.................................................................................................................. 105Administering the Convidx file tool.....................................................................................................................106Administering the Convmark file tool................................................................................................................. 107Administering the Dumpgroup file tool.............................................................................................................. 109Administering the Filever file tool....................................................................................................................... 110Administering the Fixfile file tool........................................................................................................................ 110Administering the Guide file tool........................................................................................................................ 112Administering the Memresize file tool................................................................................................................ 114Administering the Shfbuild file tool.................................................................................................................... 116Administering the Udfile file tool........................................................................................................................ 117

Chapter 16: Monitoring system activity in UniVerse...................................................................................................... 119Listing active UniVerse processes and jobs........................................................................................................ 119

Interactive users....................................................................................................................................... 120Background processes............................................................................................................................. 120

Listing UniVerse jobs with PORT.STATUS........................................................................................................... 120Terminating a process..........................................................................................................................................120

To terminate a user process.................................................................................................................... 121To terminate a background process....................................................................................................... 121

Chapter 17: Monitoring system activity in UniData....................................................................................................... 122Listing active UniData processes and jobs......................................................................................................... 122

8

Chapter 1: Getting started

Welcome to XAdmin helpThe help provides conceptual, task-based, and reference information about XAdmin.

You can search for a word or phrase in these help topics by selecting the Search tab and entering yoursearch topic. To narrow the search results to an exact phrase, enclose the phrase within quotationmarks, for example, “dictionary files.”

Additional resources

For additional information about U2 products, training, and technical resources go to http://www.rocketsoftware.com/brand/rocket-u2.

Installing and updating the DBTools using the EclipseUpdate Manager

You can update and install any of the U2 DBTools using the Update Manager in Eclipse.

Find the latest information about updates for U2 DBTools at http://updates.rocketsoftware.com/u2.

Procedure

1. Launch any U2 DBTools or base Eclipse installations (beginning with Galileo) on your computer.2. From the Eclipse Help menu, select Help → Install New Software.3. Click Add, enter a name for the site, such as U2 Update Site, and in the Work with field enter

http://updates.rocketsoftware.com/u2. Click OK.4. Allow the repository to load and then expand the tree for U2 DBTools. Select the updates that you

want to apply. You can also choose to install any other U2 DBTools into your existing workspace.5. Click Next and follow the installation wizard to complete the installation of updates.6. Updates will take effect the next time an updated tool is launched.

Note: Only tools that are installed through separate InstallShield installations will appear onthe Start menu. Tools installed using the Eclipse Update Manager are installed as individualperspectives in a single Eclipse instance. You can access the different perspectives by selectingWindow → Open Perspective and then selecting the appropriate tool.

Note: You can check for updates to the DBTools by selecting Help → Check for Updates. To usethis option, you must have previously defined the http://updates.rocketsoftware.com/u2 locationin the Install New Software dialog, as described in step 3.

XTOOLSUBThis topic describes the XTOOLSUB program and how to upgrade to the latest version of XTOOLSUBon various operating systems.

http://www.rocketsoftware.com/brand/rocket-u2

http://www.rocketsoftware.com/brand/rocket-u2

http://updates.rocketsoftware.com/u2



Installing XTOOLSUB for UniData on Windows

9

Updating the XTOOLSUB Program

The XTOOLSUB program is a U2 database server-side BASIC program used by various U2 Client Tools.This includes U2 DataVu, U2 Web DE, Basic Developer's Toolkit (BDT), Extensible Administration Tool(XAdmin), Web Services Developer, and more. It also includes any tool that uses the U2 Resource View.

XTOOLSUB updates itself automatically. However, if something happens to the XTOOLSUB programyou can download the latest version from the public Tech Note site at:

https://u2tc.rocketsoftware.com/documentation/1410028.asp

The XTOOLSUB program contains several zip and tar files, and includes three or four files, dependingon the environment. The XTOOLSUB program is used by all the tools, but the other files included areonly used for the Basic Developer's Toolkit (BDT).

The XTOOLSUB_EXECPRE/XTOOLSUB_XPRE programs are for pre-execution functionality andXTOOLSUB_EXECPOST/XTOOLSUB_XPST are for post-execution functionality. These programs arediscussed further in the related public Tech Note, BDT Extensibility Details. If you have added your owncode to the pre- and post-functionality, copy those modified programs to the older database versionsrather than the pre- and post- files located here.

The files included for UniData are:

▪ XTOOLSUB

▪ XTOOLSUB_EXECPRE

▪ XTOOLSUB_EXECPOST

▪ EDAMAPSUB (UniData 6.1 and lower)

The files included for UniVerse are:

▪ XTOOLSUB

▪ XTOOLSUB_XPRE

▪ XTOOLSUB_XPST

▪ EDAMAPSUB (UniVerse 10.3 and lower)

Do not catalog the EDAMAPSUB subroutine when using UDT 7.1 or UV 11.1 and higher. This programalready exists on those versions.

There is a difference between the databases because UniVerse's catalog environment is a type 1 fileand has a 14–character file name limit.

Only extract the file that is needed for the database server/version and OS type you are using.The ...UX.tar (Unix) files come from AIX. You will need to run fnuxi/convcode if you use other UNIX/Linux operating systems. Files are not included for all operating systems in order to avoid unnecessaryconfusion. The files in the zip/tar files are the object code for the given programs; do not open them ina text editor.

Note: Log in as a root or administrator user when doing these steps to avoid any permissionserrors. If an overwrite message occurs, select "yes" to overwrite the file in question.

Installing XTOOLSUB for UniData on Windows

The XTOOLSUB program is installed and updated automatically through the U2 DBTools updates.However, if your version of XTOOLSUB somehow becomes unusable, you can install a new version.



10

Procedure

1. Download the latest version of XTOOLSUB from the public Tech Note site at https://u2tc.rocketsoftware.com/documentation/1410028.asp.

2. Copy the XTOOLSUB_UDT_NT.zip or XTOOLSUB_UDT_61_NT.zip file to a temporary directory onyour server (for example, c:\temp).

3. Extract the file to the c:\u2\ud##\sys\SYS_BP (where ## refers to the UniData major version. Forexample, 61, 71, 72, etc.) directory using your preferred unzipping utility. If UniData is installed inanother location, change the path accordingly.

4. Log in to the sys account using telnet or execute a udt shell command in the sys directory on theserver.

5. Catalog the three XTOOLSUB programs, as follows:

▪ CATALOG SYS_BP XTOOLSUB FORCE

▪ CATALOG SYS_BP XTOOLSUB_EXECPRE FORCE

▪ CATALOG SYS_BP XTOOLSUB_EXECPOST FORCE

Note: If you are using UniData 6.1 or lower, also run the CATALOG SYS_BP EDAMAPSUBFORCE command.

6. Connect with your U2 client tool to the U2 database server.

Installing XTOOLSUB for UniVerse on Windows


Procedure

1. Download the latest version of XTOOLSUB from the public Tech Note site at https://u2tc.rocketsoftware.com/documentation/1410028.asp

2. Copy the XTOOLSUB_UV_NT.zip or XTOOLSUB_UV_103_NT.zip file to a temporary directory onyour server. For example, c:\temp.

3. Extract the file to the c:\u2\uv\BP.O directory using your preferred unzipping utility. If UniVerse isinstalled in another location, change the path accordingly.

4. Log in to the UV home account via Telnet. The account name is UV or uv in the UV.ACCOUNT file.5. Catalog the three XTOOLSUB programs, as follows:




Note: You will receive a catalog error if you try to catalog all three programs on the samecommand line.

6. If you are using UniVerse 10.3 or later, also run CATALOG BP *EDAMAPSUB FORCE command.7. Connect with your U2 client tool to the U2 database server.





Installing XTOOLSUB for UNIX/Linux for UniData

11

Installing XTOOLSUB for UNIX/Linux for UniData


The $UDTBIN referenced below is an environment variable pointing to your UniData bin directory, forexample, /usr/ud##/bin (where ##, is 61,71,72, etc.). If this variable is not set, then reference the fullpath to the UniData bin directory in the commands.

Procedure

1. Download the latest version of XTOOLSUB from the public Tech Note site at https://u2tc.rocketsoftware.com/documentation/1410028.asp.

2. Copy the XTOOLSUB_UDT_UX.tar or XTOOLSUB_UDT_61_UX.tar file to a temporary directory onyour server (for example, /tmp). If transferring using ftp, remember to use binary format.

3. Extract the file to the $UDTHOME/sys/SYS_BP directory.a. To install using UniData 6.1 or earlier, the commands will be:

cd $UDTHOME/sys/SYS_BPtar -xvf /tmp/XTOOLSUB_UDT_61_UX.tar

b. To install UniData 7.1 or later, the commands will be:cd $UDTHOME/sys/SYS_BPtar -xvf /tmp/XTOOLSUB_UDT_UX.tar

4. If you are using a non-AIX operating system, run the convcode command, as shown: $UDTHOME/sys/SYS_BP: $UDTBIN/convcode .

Note: The convcode command includes a period at the end of the line. This will converteverything in the SYS_BP file to the current format. All files report that they were converted,but this is the default answer for convcode. The existing files should already be in the correctformat.

5. Change directories to the $UDTHOME/sys directory and then and execute the UDT command, asshown:a. CD $UDTHOME/sysb. $UDTBIN/udt







Installing XTOOLSUB for UNIX/Linux on UniVerse





12

Procedure


2. Copy the XTOOLSUB_UV_UX.tar or XTOOLSUB_UDT_UV_103_UX.tar file to a temporary directoryon your server (for example, /tmp). If transferring files using FTP, remember to use binary fileformat.

3. Extract the file to the /usr/uv/BP.O directory. If UniVerse is installed in another location, changethe path accordingly. Use 'cat /.uvhome' to find the path if needed.

Note: `cat /.uvhome` references include single backward quotation marks. This commandretrieves the current value for the UniVerse home directory before running the command.

a. To install using UniVerse 10.3 or earlier, the commands to use are:cd `cat /.uvhome`/BP.Otar -xvf /tmp/XTOOLSUB_UV_103_UX.tar

b. To install using UniVerse 11.1 or later, the commands to use are:cd `cat /.uvhome`/BP.Otar -xvf /tmp/XTOOLSUB_UV_UX.tar

4. If you are using a non-AIX operating system, run the convcode command, as shown:`cat /.uvhome`/bin/fnuxi XTOOLSUB*

5. Change directories to the UniVerse home directory and then and run the UV command, as shown:a. cd `cat /.uvhome`b. bin/uv

6. Click Escape to exit the menu.7. Catalog the three XTOOLSUB programs, as follows:




Note: You will see a catalog error if you try to catalog all three programs on the samecommand line.

8. If you are using UniVerse 10.3 or earlier, also run the CATALOG BP *EDAMAPSUB FORCEcommand.


Installing XTOOLSUB on Windows


Procedure


2. Copy the XTOOLSUB_UDT_NT.zip or XTOOLSUB_UDT_61_NT.zip file to a temporary directory onyour server (for example, c:\temp).





Installing XTOOLSUB on Windows

13

3. Extract the file to the c:\u2\ud##\sys\SYS_BP (where ## refers to the UDT major version, i.e. 61, 71,72, etc.) directory using your preferred unzipping utility. If UniData is installed in another location,change the path accordingly.

4. Log into the sys account using telnet or execute a udt shell command in the sys directory on theserver.







14

Chapter 2: XAdmin overviewThe U2 Extensible Administration Tool (XAdmin) is an Eclipse-based interface for administering theUniData or UniVerse (U2) database server. It is the successor to the UniAdmin tool.

The XAdmin workspace contains multiple panes, or views. From these views, you can performadministration tasks, view reports, and monitor the performance of U2 processes in real time.

What makes XAdmin “extensible”? After gaining expertise with the standard interface, you cancustomize the tool by adding your own tasks. You can also contribute menus to call your own UniBasicor UniVerse BASIC programs.

To begin, you can start XAdmin and become familiar with the workspace in the standard interface.After that, you can create a U2 server definition, connect to the U2 server, and select an administrationtask to perform.

A screen resolution of 1280x1024 or higher and a text setting of 100% is recommended for all U2Eclipse-based applications.

Starting XAdminBefore you can perform UniData or UniVerse administration tasks, you must start the U2 ExtensibleAdministration Tool (XAdmin).

Prerequisites▪ XAdmin must be running on a Microsoft Windows computer that is on the same network as the

server computer running UniData or UniVerse.

▪ Make sure that UniData or UniVerse services are currently running on the server computer.

Procedure

On the taskbar of the Windows computer on which XAdmin is installed, select Start > All Programs >Rocket U2 > Extensible Administration Tool.

Next step

Creating U2 server definitions, on page 16

XAdmin workspaceThe U2 DBTools workspace contains multiple panes, called views. Views structure the workspace andserve as a device to organize similar items inside a defined work area.

▪ U2 Resource view

▪ Admin Tasks view, on page 15

▪ Performance Monitor views

▪ Properties view

▪ U2 Dictionary view

By default, the workspace is arranged in a standard layout, but you can move or resize views. Eachview contains its own controls for minimizing and maximizing the space consumed within the U2DBTools workspace. Alternatively, you can drag the border of a view to increase or decrease its size.

XAdmin workspace

15

A view may contain just one item or tabs for multiple items. Each view or tab within the view has aClose (X) button to close the entire pane or to close a tab within the pane.

You can do no damage in experimenting with the workspace. If you close a view and want to show itagain later, you can select it from the Window menu. Otherwise, if you want to reset the main windowto show all views in their default locations, you can select Window > Reset.

U2 Resource view

The U2 Resource view contains information about each U2 account on the server to which youare connected. This information includes accounts, data files, dictionary files, UniBasic programs,UniVerse BASIC programs, XML/DB mapping files, and cataloged programs.

Admin Tasks view

The Admin Tasks section allows users to perform a variety of administrative tasks, such as managinglicenses, managing files, and monitoring performance.

U2 REST servers view

The U2 REST servers view contains information about each REST server and resource that you create.You can manage you RESTful servers, resources, and subroutine services from within this view.

When you create a new resource or subroutine service within the RESTful Developer, it appears inthe RESTful Servers view. All data files are grouped under the Data Resources node. Subroutinesare grouped under the Subroutine Resources node, with dynamic arrays nested together withinSubroutine Resources under the Dynamic Array Definitions node.

Right-click on any of the nodes in this pane to view the different options available to each node.

To start a REST server, for example, right-click your RESTful server and select Start REST Server. Youcan also double-click any of the data resources in your REST server to test the service in the TestBrowser. If the REST server is not running, double-click the resource to start the REST server.

U2 REST server log view

The Server Log view displays the logging details about your Web services. To enable the debug logwhen the server is running, right-click the REST server and then select Turn On REST Server Debug.

You can also turn logging on by changing the Debug Log option in the RESTful server properties. If youselect true, the U2 RESTful Web Services Developer starts the debug log each time you start the server.You can only make this change when the server is not running.

To disable the debug log when the server is running, right-click the REST server and then select TurnOff REST Server Debug.

To view a REST server log, in the U2 REST Servers view, click the REST server.

Properties view

The Properties view displays the properties defined for each file, account, program, server, andresource available.

Select a node in any of the views to see the properties for that node.

Chapter 2: XAdmin overview

16

Note:

The first time a file is selected in the Resource view, the file path and dictionary path informationmay show as "unknown" in the Properties pane. This is by design to improve initial performancewhen loading the content of the U2 Resource View. Selecting a different file and reselecting theoriginal will populate the file information the Properties pane.

U2 Dictionary view

The U2 Dictionary view displays the dictionary information about the database files in the U2 Resourceview. You can see data source information and view the structure of the file system from within thisview.

Establishing server connections

U2 server definitions

The U2 DBTools interface does not detect the presence of UniData or UniVerse (U2) database serverson the network or let you connect to them by default. To work with UniData or UniVerse accounts anddata, you must enable the computer to connect to the server on which the accounts and data reside.The client computer requires a U2 server definition to make a connection with the server.

A U2 server definition is stored on the client computer on which it was created, and is not sharedacross a network. One or several users can create multiple U2 server definitions on the same clientcomputer.

U2 server is the term for a defined connection to a server computer on which U2 accounts and dataare stored. All existing U2 servers on the client computer are listed in the U2 Resource view. You canconnect to any U2 server in the U2 Resource list.

Creating U2 server definitions

To administer UniData or UniVerse accounts and data, you must create a U2 server definition thatenables the client computer to connect to the U2 database server on which the accounts and data arestored.

Prerequisites

Open the U2 DBTools workspace from the Start → Rocket U2 menu.

Procedure

1. To start the Create a New U2 Server wizard, right-click the U2 Servers node in the U2 Resourceview, and click New U2 Server.

2. In the Name field, enter a unique name to identify the U2 server definition.The name cannot contain a slash (/) or backslash (\) character.

3. In the Host field, enter the name or IP address of the computer on which UniData or UniVerse isrunning.

4. From the U2 database server options, select UniData or UniVerse.

Viewing or editing advanced settings of a U2 server definition

17

5. Optional: To view or edit the unirpc service name, port number, and other advanced settingsdefining the connection, click Advanced.

Go to Viewing or editing advanced settings of a U2 server definition, on page 17.

Tip: The default values for advanced settings work best in most situations. Alter thesesettings only if necessary.

6. Optional: To view or update the SSL settings, click Setup SSL.

Go to Setting up SSL settings for a U2 server definition, on page 187. To save the U2 server definition, click Finish.

The tool creates a directory for the U2 server, registering the server definition so the tool can findit in future sessions. The name of the new U2 server is added to the list in the U2 Resource view.

Next step

Connecting to U2 servers, on page 20

Viewing or editing advanced settings of a U2 serverdefinition

On the advanced settings page of the server definition, you can view or edit the protocol, port number,and other advanced settings that define the connection. You can also specify commands to run whenyou connect to the U2 server. The default values for advanced settings work best in most situations.Alter these settings only if necessary.

Prerequisites

Creating U2 server definitions, on page 16 or Editing U2 server definitions, on page 19

Procedure

1. The Protocol Type field displays TCP/IP as the communications protocol used by the UniData orUniVerse to access the internet.At this time, the only supported protocol is TCP/IP, and this setting cannot be changed.

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

3. In the RPC Service Name field, enter the name of the remote procedure call (RPC) service on thesystem.For UniData, the name is normally udcs; for UniVerse, the name is normally uvcs.

4. In the Login Account field, enter the full path to the account folder on the server running UniDataor UniVerse.You can enter just the account name if the account is defined in the UD.ACCOUNT or UV.ACCOUNThash file.

5. If you run a RetrieVe command, a saved paragraph, or a globally cataloged program every timeyou connect to the U2 server, you can save time by entering the command in the U2 serverdefinition. To enter a command to run on connection, click Add in the Commands to Executegroup box.See Specifying a command to run on connection, on page 18.


18

6. In the Specify the session to run/debug your BASIC program on server side group box, enterdetails for connecting to the server in a debug session.a. From the Protocol options, select the network protocol to use when you connect to the U2

server in a debug session: Telnet or SSH (Secure Shell).b. In the Port Number field, enter the port number on which the Telnet or SSH service runs on

the server computer. The default Telnet port number is 23; the default SSH port number is22.

c. If device licensing is supported on the server, select the Use Device License check box toconserve license usage in the debug session.

While running or debugging BASIC programs, you may use multiple server connections to browsefiles, check data, update records, or perform other tasks. If device licensing is disabled, the debugsession consumes one U2 license for each connection. With device licensing enabled, the sessionconsumes one U2 license and one device license for up to 10 connections from a single device.

Tip: If you are unable to establish a Telnet or SSH connection with the Use Device Licensecheck box selected, clear the check box and try again.

7. To save changes to advanced settings and return to the main page, click Finish.

Specifying a command to run on connection

You can run a RetrieVe command, a saved paragraph, or a globally cataloged program every timeyou connect to the U2 server. Rather than type the same command each time you connect, you canincrease efficiency and save time by entering the command in the U2 server definition.

1. In the Specify a command field, enter a RetrieVe command, the name of a saved paragraph, orthe name of a globally cataloged program to run when you connect to the U2 server.

2. To save the changes and return to the details page, click OK.

Setting up SSL settings for a U2 server definitionOn the Database Connection Security page for the server definition, you can turn on SSL, and add atrust store and trust store password for the connection.

Prerequisites


Procedure

1. Select the Use SSL checkbox to enable SSL.

Note: The key store must be an absolute file.

2. Select Use Default Trust Store to enable the trust store.3. Enter the location of the trust store you want to use, or click Browse to navigate the correct

location.4. Enter the trust store password.5. To save changes to the SSL settings and return to the main page, click Finish.

Editing U2 server definitions

19

Editing U2 server definitionsYou can modify the details of an existing U2 server definition, with one exception. It is not possible tochange the name of the U2 server. However, you can create the U2 server again with a new name.

Prerequisites


Procedure

1. To start the Edit U2 Server Definition wizard, right-click the name of the U2 server definition in theU2 Resource view, and click Properties.

2. In the Host field, enter the name or IP address of the computer on which UniData or UniVerse isrunning.

3. From the U2 database server options, select UniData or UniVerse.4. Optional: To view or edit the unirpc service name, port number, and other advanced settings

defining the connection, click Advanced.

Go to Viewing or editing advanced settings of a U2 server definition, on page 17.

Tip: The default values for advanced settings work best in most situations. Alter thesesettings only if necessary.

5. To save the U2 server definition, click Finish.The tool creates a directory for the U2 server, registering the server definition so the tool can findit in future sessions. The name of the new U2 server is added to the list in the U2 Resource view.

Importing an existing U2 server definitionYou can import existing U2 server definitions to your XAdmin environment from the XAdmin ResourceView.

Prerequisites


Note: When you import U2 servers, all credential information is included. It is important to limitrestricted access services, depending on your security policy. It is the function of your securityadministrator to determine if U2 servers can be imported with credentials included. You can saveserver resources without password credentials.

Procedure

1. From the U2 Resource View, right-click the Servers icon and then select Import U2 Servers.2. In the Installation path field, enter the location of the server definitions you want to import. This

must be an existing U2 DBTools directory.3. Select the server definitions you want to import, then click OK.

The imported server now shows in the U2 Resource View.


20

Connecting to U2 serversYou must open a U2 server connection to work with the accounts stored on the associated UniDataor UniVerse (U2) database server computer. You can connect to any U2 server that is listed in the U2Resource view.

Prerequisites


Procedure

1. To start the Connect to a U2 Server wizard, double-click the name of the U2 server in the U2Resource view.

2. In the User ID field, enter the administrator user name or the user name of a valid user on theserver computer running UniData or UniVerse.

3. In the Password field, enter the password for the administrator or user on the server computer.4. To store the password for future connections, select the Remember me check box.

With this check box selected, Microsoft Windows stores the encrypted password on the clientcomputer.

5. If you are using a proxy server, select the Use Proxy Server check box.a. In the Proxy Host field, enter the name or IP address of the computer on which the proxy

server is running.b. In the Proxy Port field, enter the number of the port on which the proxy server listens for

communication from UniData or UniVerse.6. To connect to the U2 server, click Connect.

When the connection is established, the U2 Resource view displays a tree view of the U2 accountsand catalog programs on the U2 database server to which you are connected.

Disconnecting from U2 serversAfter completing tasks for a U2 account, you can disconnect from the U2 server. Disconnecting onlycloses the connection to the U2 server. It does not delete the U2 server definition or remove the U2server from the list in the U2 Resource view.

In the U2 Resource view, right-click the name of the U2 server from which you want to disconnect, andclick Disconnect.

Deleting U2 server definitionsIf you no longer require access to the U2 accounts and catalog programs on a U2 database server, youcan delete the associated U2 server definition. It is not possible to change the name of an existing U2server. However, you can delete the U2 server definition and create it again using a new name.

In the U2 Resource view, right-click the name of the U2 server you want to delete, and click Delete.The name of the U2 server and folders for its U2 accounts and catalog programs are removed from thelist in the U2 Resource view.

21

Chapter 3: Administering U2 accounts

U2 accounts overviewA UniData or UniVerse (U2) account is a virtual container used to organize a collection of related filesand data for a specific business purpose or activity. For example, a business organization may create aU2 account for use in tracking and managing data on the Sales function of the business.

More technically, a U2 account is a UNIX or Windows directory in hashed format that contains avocabulary (VOC) file and other U2 system files that provide the environment in which to run U2tools and applications. An account can be configured to meet the needs of one user, a job function, adepartment, or an entire company.

A U2 account is associated to a specific U2 server definition. The U2 account name must be unique tothe U2 server.

Initiating Accounts tasksAccounts administration tasks are performed in the editor view, which you can open from the AdminTasks view in XAdmin.

Prerequisites

Starting XAdmin, on page 14

Procedure

To open the Accounts editor, in the Admin Tasks list, double-click Accounts.

Adding or viewing U2 accountsA UniData or UniVerse (U2) account serves as a container for a collection of files and data for a relatedbusiness purpose or activity. In this task, you can create a U2 account or view the list of existing U2accounts.

1. To create a U2 account, click Add.See Creating a U2 account, on page 21.

2. To view a list of U2 accounts, check information in the grid:Account Name lists the unique name of each U2 account.

Path displays the full path of the U2 account.3. Optional: To sort the data for all U2 accounts in the list, click any column heading to sort on that

column.4. Optional: To filter the results, enter a string in the Filters field above any column.

Creating a U2 accountIn this task, you can define a new U2 account as the container for a collection of related files for abusiness purpose or activity.

Chapter 3: Administering U2 accounts

22

1. From the Select U2 server list, select the name of the U2 server to be associated to the new U2account.

2. In the Account Name field, enter a name for the new U2 account. This name must be unique tothe U2 server.

3. In the Account Path field, enter the full path for the U2 account, or click Browse to search for thelocation in which to create the account.To create the account in a path that does not already exist, select the Create the account path ifit does not exist check box.

4. To create the U2 account, click Finish.The Create New U2 Account wizard closes. The new U2 account is listed in the grid in the Accountseditor. The U2 account is stored on the U2 database server.

23

Chapter 4: Managing disk space

Disk space usageThe Disk Space tool enables you to view statistics on a U2 file system's current disk space usage,helping you gauge whether the file system is working optimally—or is overloaded, or is allocated toomuch space.

The total amount of disk space available, the amount of free space, and the percentage of disk spacecurrently in use are all factors that help you determine whether to make adjustments.

Initiating disk space tasksDisk Space administration tasks are performed in the editor view, which you can open from the AdminTasks view in XAdmin.

Prerequisites


Procedure

To open the License tool, in the Admin Tasks list, double-click Disk Space.

Viewing disk space usageThe Disk Space tool enables you to view current data on the disk space usage of U2 file systems,helping you determine whether a file system needs space adjustments. In this task, you can viewstatistics on disk space usage, sort or filter the data, and refresh the display.

Prerequisites

Initiating disk space tasks, on page 23

Procedure

1. From the Block Size options, select a block size for expressing units of disk space: 512 bytes or1024 bytes.

2. To view statistics on disk space usage for U2 file systems, check information in the grid:

File System lists the full path of each U2 file system.

Total Size displays the total amount of disk space allocated to the file system.

Free Space displays the remaining amount of disk space available for use by the file system.

% in Use displays the percentage of total disk space currently in use by the file system.

Free Space displays the remaining amount of disk space available for use by the file system.



Chapter 4: Managing disk space

24

3. Optional: To sort the data for all U2 file systems in the list, click any column heading to sort onthat column.

4. Optional: To filter the results, in the Filters field above any column, select an operator (=, >, or <)from the drop-down list and enter a string in the associated field.

5. Optional: To refresh the results with current disk space usage data, click Refresh.

25

Chapter 5: Managing Secure Sockets Layer (SSL)

Secure Sockets Layer (SSL) technologySSL is a transport layer protocol that provides a secure channel between two communicatingprograms over which arbitrary application data can be sent safely. It is by far the most widelydeployed security protocol on the World Wide Web.

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

UniData and UniVerse currently support CallHTTP and the Sockets API. SSL is important to both ofthese internet APIs, providing the means to deploy commercial applications and securely processsensitive data, such as credit card transactions.

Although the term “SSL” is used exclusively in this help system, U2 also supports the more recentTransport Layer Security (TLS) protocol. TLS is an expanded version of SSL published by theInternational Engineering Task Force (IETF) standards body. TLS provides support for more public keyalgorithms and cipher suites.

If you need a more detailed overview of public key cryptography and SSL, see information on thesesubjects on the World Wide Web.

Initiating SSL tasksAll SSL setup and configuration tasks are performed in the editor view, which you can open from theAdmin Tasks view in XAdmin.

Prerequisites


Procedure

To open the Configure SSL for Servers editor, in the Admin Tasks list, double-click SSL Configuration.

Setting up and managing SSLTo use the Secure Sockets Layer (SSL) protocol, you must perform some initial setup to createcertificates and configure SSL for the U2 server. You can set up and manage SSL certificates andconfiguration details on an ongoing basis using the editor tool inside XAdmin.

Complete the following tasks:

▪ Generating certificate signing requests, on page 26

▪ Generating SSL certificates, on page 29

▪ Creating security context records, on page 33

▪ Configuring SSL for U2 servers, on page 42


26

Generating certificate signing requestsBefore you can obtain or create an SSL certificate, you must generate an X.509-compliant certificatesigning request (CSR) containing a digital signature. You can send the CSR to a third-party certificateauthority (CA) to obtain a certificate, or use the CSR as input to generate a certificate with the wizardin XAdmin.

Starting the Generate Certificate Signing Request wizard

The Generate Certificate Signing Request wizard leads you through the process of generating a CSR.You can start the wizard from the editor view.

1. In the Configure SSL for Servers editor, click the Certificate Signing Request tab.2. To start the Generate Certificate Signing Request wizard, click Generate a Certificate Request.

The Generate Certificate Signing Request dialog box contains an introduction to this task.3. To continue, click Next.

Specifying a file and algorithm for the CSR

In this child task of generating a certificate signing request, you can specify the file to contain the CSRand select the algorithm to use in generating the digital signature for the CSR.

1. In the Certificate Signing Request File field, enter the full path of the operating system-level fileto contain the certificate signing request, or click Browse to search for the file location.

2. From the Digest Algorithm options, select the algorithm to use in generating the digital signaturefor the certificate signing request:

▪ SHA1 – SHA1 cryptographical hash function

▪ SHA224 — SHA2 cryptographical hash function (available for UniData 8.1 or later or UniVerse11.2.4 or later)




▪ MD5 – MD5 cryptographical hash function

3. To continue, click Next.

Defining properties of the CSR

In this child task of generating a certificate signing request, you can enter required and optionalproperties to define the CSR.

1. In the Request Properties dialog box, from the C (Country Code) list, select the two-letter codefor the country in which the requesting organization is located.

2. Optional: In the ST (Province) field, enter the full name of the state or province of theorganization requesting the SSL certificate.

Selecting a key pair option

27

Example: Massachusetts.3. Optional: In the L (Locality) field, enter the full name of the city or locality of the requesting

organization.Example: Newton.

4. In the O (Organization) field, enter the full legal name of the company or person requesting thecertificate, as legally registered in the locality.Example: Rocket Software, Inc.

5. Optional: In the OU (Organization Unit) field, enter the name of the requesting business unit orbranch within the organization. Example: Information Technologies

6. In the CN (Common Name) field, enter the fully qualified domain name (FQDN) for which you arerequesting the certificate.

7. Optional: In the Email field, enter the e-mail address of the primary contact requesting thecertificate.


Selecting a key pair option

In this child task of generating a certificate signing request, you can choose to use an existing key pairor generate a new key pair for the CSR.

1. In the Key Pair Selection dialog box, select one of the following key pair options:

▪ Use existing key pair

▪ Generate new key pair


Supplying key pair parameters

The tool needs several pieces of information to generate a new key pair or find an existing key pair.

In this child task of generating a certificate signing request, you will either:

▪ Select the format and private key file of an existing key pair, or

▪ Select the parameters required to generate a new key pair.

1. In the Key Pair Info dialog box, from the Key Algorithm options, select the algorithm to use ingenerating a new key pair or the algorithm that was used to generate an existing key pair:

▪ RSA – RSA key algorithm

▪ DSA – Digital signature algorithm

2. The Key Length list is enabled only if you selected the Generate new key pair option in theprevious task. From this list, select the length of the key in bits.This is the primary measure of the cryptographic strength of the key. Valid values are multiples of64, ranging from 512 to 16384.

Note: The stronger the key, the longer it takes to create the key. For example, a key strengthof 16384 can take up to ten minutes to create. We recommend that keys have a minimumlength of 2048.


28

3. From the Key File Format options, select the format for private and public key files:

▪ PEM – Privacy Enhanced Mail format

▪ DER – Distinguished Encoding Rules format

4. The Parameter File field is enabled only if you selected DSA as the Key Algorithm option.

▪ For a new key pair, enter the full path of an existing parameter file, or click Browse to searchfor the file location. The UniData or UniVerse (U2) data server uses the selected parameter fileto generate the key pair. If you leave this field blank, the U2 database server uses its defaultparameters table to generate the key pair.

▪ For an existing key pair, enter the full path or browse for the parameter file that was used togenerate the key pair.

5. In the Private Key File field, enter the name of the file to contain the private key, or click Browseto search for an existing private key file.

6. The Public Key File field is enabled only if you selected the Generate new key pair option in theprevious task. In this field, enter the name of the file to contain the public key, or click Browse tosearch for an existing public key file.


Entering a password for the private key file

The private key file must be password-protected to maintain its security.

In this child task of generating a certificate signing request, you will:

▪ Enter the password previously established for an existing private key file, or

▪ Create a password for a new private key file.

1. In the Password for Private Key field, enter the password for the private key file.XAdmin does not enforce password length or strength rules on this password; however, as a bestpractice, create a strong password to protect the private key.

2. In the Confirm Password field, enter the password again for verification.The wizard now has all the information required to generate the certificate signing request file.

3. To generate the CSR file, click Next.Otherwise, to review selections or make changes, click Back.

Verifying the status of generating the certificate

In this child task of generating an SSL certificate, you can check the status message to see whether thecertificate was generated successfully. If it was not, you can go back to make corrections.

1. In the Review Status and Finish dialog box, check the message indicating the status of generatingthe certificate.If the certificate was created successfully, the dialog box contains the message “Certificate wasgenerated successfully.” If the process did not generate a certificate, the dialog box contains themessage “Failed to create certificate.” To return to previous dialog boxes and correct the error,click Back.

2. To close the Generate SSL Certificate wizard and return to the Configure SSL for Servers editor,click Finish.

Generating SSL certificates

29

Generating SSL certificatesUsing a wizard, you can create three types of X.509 SSL certificate:

A certificate is used to bind the name of an entity with its public key. It is used as a means ofdistributing a public key. A certificate always contains three pieces of information:

▪ Name

▪ Public key

▪ Digital signature signed by a trusted third party, called a certificate authority (CA), with its privatekey

If you have the public key of the CA (contained in the CA certificate), you can verify that the certificateis authentic.

SSL protocol specifies that when two parties start a handshake, the server must send its certificateto the client for authentication. It may also require the client to send its certificate to the server forauthentication. U2 servers that act as HTTP clients are not required to maintain a client certificate. U2applications that act as SSL socket servers must install a server certificate. UniObjects for Java serversand Telnet servers also require a server certificate.

There can be only one server/client certificate per security context record. Adding a new certificateautomatically replaces an existing certificate. However, for issuer certificates, the U2 data serverchains a new one with existing certificates so U2 applications can perform chained authentication.

If the issuer certificate is in PEM format, it can contain multiple certificates by concatenatingcertificates together.

All certificates that form an issuer chain must be of the same type.

▪ Self-signed root certificate

▪ Intermediate CA certificate

▪ Server or client certificate

You can also use the wizard to view the details of existing SSL certificates stored on the computer.

Starting the Generate SSL Certificate wizard

The Generate SSL Certificate wizard leads you through the process of generating or viewing an SSLcertificate. You can start the wizard from the editor view.

Procedure

1. In the Configure SSL for Servers editor, click the Certificate tab.2. To start the Generate SSL Certificate wizard, click Generate a Certificate.

The Generate SSL Certificate dialog box contains an introduction to this task.3. To continue, click Next.

Specifying a certificate file name

In this child task of generating an SSL certificate, you can specify the name for a new certificate file.Alternatively, you can use the wizard to select the name of an existing certificate file and view itsdetails.


30

1. In the Certificate File field, enter a unique name or full path for a new certificate file, or clickBrowse to search for the location of an existing certificate file.

2. The appropriate action in this step depends on whether you entered a new file name or selectedan existing file name.

▪ To continue with creating a new certificate, click Next.

▪ To view the details of an existing certificate, click Show. When you finish viewing thecertificate details, you can close the wizard and perform another task.

Setting the validity period for a new certificate

An SSL certificate is valid only for a specified time period. In this child task of generating an SSLcertificate, you will set the number of days for which the new certificate is valid.

1. From the Validity Period list, select the number of days for which the new SSL certificate is to bevalid.The certificate is valid starting from the current date until the specified number of days elapses.The default value is 365 days.


Selecting a certificate type

An X.509 SSL certificate can be one of three types, depending on the purpose it serves. In this childtask of generating an SSL certificate, you can select the type of certificate to create.

1. From the Certificate Type options, select the type of SSL certificate to create:

▪ Self-signed root certificate

▪ Intermediate CA certificate

▪ Server/Client certificate

2. From the Signing Algorithm options, select a signing algorithm. The default selection is SHA1.

▪ SHA224

▪ SHA256

▪ SHA384

▪ SHA512

▪ SHA1

▪ MD5


Next step

The next step depends on the certificate type you selected:

▪ Self-signed root certificate: Selecting the private key file of the CSR, on page 31

▪ Intermediate CA certificate or Server/Client certificate: Optional: Defining certificate extensions, onpage 31

Optional: Defining certificate extensions

31

Optional: Defining certificate extensions

Extensions can be used to further define the purpose or provide identifiers for an intermediate CAcertificate or server/client certificate. In this child task of creating a certificate of either type, you havethe option of defining relevant certificate extensions.

Procedure

1. In the X.509 v3 Certificate Extensions dialog box, select the check box for each certificateextension that you want to define for the new certificate:

▪ Subject Alt Name – The subject alternative name extension allows additional identities to bebound to the subject of the certificate.

▪ Key Usage – This extension defines the purpose of the key contained in the certificate and canbe used to put certain restrictions on key usage.

▪ Basic Constraints – This extension indicates whether the subject of the certificate is acertificate authority (CA).

▪ Subject Key Identifier – This extension provides a means of identifying certificates thatcontain a particular public key.

▪ Authority Key Identifier – This extension identifies the public key corresponding to theprivate key used to sign the certificate.

When you select an extension, help text for that extension is displayed in the lower half of thedialog box, along with the relevant options for defining the extension.

If no extensions are relevant, leave all check boxes cleared.


Selecting required files to generate a certificate

Selecting the private key file of the CSR

A private key was used to generate the certificate signing request (CSR) you selected in a previousstep. In this child task of creating a self-signed root certificate, you will select the private key file of theCSR associated with the new certificate.

Prerequisites

Selecting a certificate type, on page 30

Procedure

1. In the Private Key File field, enter the full path of the private key file used to generate thecertificate signing request associated with the new certificate, or click Browse to search for thefile location.


Next step

Entering the password for the private key file, on page 32


32

Selecting the signing certificate file and private key file

In this child task of creating an SSL certificate, you will select the signing certificate file to use insigning the new certificate and the private key file of the signing certificate.

Two files are required as input to generate an intermediate CA certificate or server/client certificate:

▪ A signing certificate file to use in signing the new SSL certificate.

▪ A private key file that was used to generate the signing certificate file.

Prerequisites

Optional: Defining certificate extensions, on page 31

1. In the Signing Certificate File field, enter the full path of the certificate file to use in signing thenew certificate, or click Browse to search for the file location.

2. In the Private Key File field, enter the full path of the private key file that was used to generatethe signing certificate file, or click Browse to search for the file location.


Entering the password for the private key file, on page 32

Entering the password for the private key file

A private key file is password-protected. In this child task of generating an SSL certificate, you willenter the password for the private key file you selected in the previous step.

Prerequisites

The prerequisite task depends on the type of certificate you are creating:

▪ Self-signed root certificate:Selecting the private key file of the CSR, on page 31

▪ Intermediate CA certificate or Server/Client certificate: Selecting the signing certificate file andprivate key file, on page 32

Procedure

1. In the Password for Private Key field, enter the password for the private key file selected in theprevious step, as follows:

▪ For a Self-signed root certificate, enter the password for the private key file used to generatethe certificate signing request file.

▪ For an Intermediate CA certificate or Server/Client certificate, enter the password for theprivate key file used to generate the signing certificate file.

2. In the Confirm Password field, reenter the password for verification.The wizard now has all the information required to generate the certificate.

3. To generate the new certificate, click Next.Otherwise, to review selections or make changes, click Back.

Creating security context records

33

Next step

Verifying the status of generating the certificate, on page 28

Creating security context recordsA security context record (SCR) is a data structure that holds the security properties that theapplication associates with a secured connection. The Security Context Record wizard leads youthrough the steps of creating or modifying an SCR, which the application requires for securedcommunication through SSL.

Starting the Security Context Record wizard

The Security Context Record wizard leads you through the procedure of creating a new securitycontext record (SCR). You can start the wizard from the editor view.

Prerequisites

Generating SSL certificates, on page 29

Procedure

1. In the Configure SSL for Servers editor, select the Security Context Record tab.2. From the SCR Database list, select the database account in which to create or view the security

context record. The full path of the selected database account is populated in the Path field.

Note: If the database account you want to use is not shown in the list, you can add it usingthe XAdmin Accounts option, as described in Adding or viewing U2 accounts, on page 21.

3. To start the Security Context Record wizard, click Add.The Security Context Record (SCR) dialog box contains an introduction to the task of creating anSCR. Make sure you have generated the necessary keys and certificates before proceeding.


Specifying the record ID and protocol

A unique record ID is used to identify each security context record (SCR), and one of several transportlayer protocols can be used to generate the SCR. In this child task of creating a security context record,you will assign a record ID to the SCR and select the protocol to use in generating the new SCR.

1. In the Security Context Record ID field, enter a unique ID for the security context record.2. From the SSL/TLS Version list, select the appropriate transport layer protocol version to use in

generating the security context record. Valid versions are:

▪ SSLv2

▪ SSLv3

▪ TLSv1

▪ TLSv1.2 (available for UniData 8.1 or later or UniVerse 11.2.4 or later)

▪ TLSv1.2 (available for UniData 8.1 or later or UniVerse 11.2.4 or later)


34

Tip: For increased security, select TLSv1.2 or TLSv1. Use of either protocol is recommended asa best practice.


Selecting server or client usage

Either a server or a client accesses the security context record (SCR) to get the properties to associatewith a secured connection. In this child task of creating a security context record, you will select anoption indicating whether the new SCR is to be used by a server or a client.

1. From the SCR Usage Type options, select an option indicating how the security context record isto be used:

▪ SCR for server – The security context record is to be used by a server

▪ SCR for client – The security context record is to be used by a client


Setting authentication properties

The server or the client must authenticate the validity of certificates during handshake negotiations. Inthis child task of creating a security context record, you will set the parameters that the server or theclient uses to authenticate certificates.

▪ For an SCR for server, go to Setting server authentication properties, on page 34.

▪ For an SCR for client, go to Setting client authentication properties, on page 35.

Setting server authentication properties

With an SCR for server, the server must verify the validity of incoming certificates during handshakenegotiations. In this child task of creating a security context record, you will set the parameters thatthe server uses to authenticate certificates.

Prerequisites

Selecting server or client usage, on page 34

Procedure

1. In the Server Authentication Properties dialog box, from the Authentication Depth list, selecta value to indicate the level of verification the UniData or UniVerse (U2) database server is toperform before determining that a certificate is not valid.Depth is the maximum number of intermediate issuer certificates, or CA certificates, the U2database server must examine while verifying an incoming certificate. A depth of 0 indicates thatthe certificate must be self-signed. A depth of 1 means that the incoming certificate can be eitherself-signed or signed by a CA known to the security context record. The default value is 3.

2. Optional: In the Trusted Peer Names field, you can add one or more trusted peer names, asexplained here.

Setting client authentication properties

35

The U2 database server uses this list of peer names to determine whether to trust a peer inhandshake negotiations. Trusted server/client names are stored in the security context record.

If no trusted peer name is set, any peer is considered legitimate.

To add trusted peer names, click Add. For steps, go to Adding trusted peer names, on page 36.3. From the Authentication Strength options, select the level of security to be used in the

authentication process:

▪ Generous – The certificate need only contain the subject name (common name) that matchesone specified by “PeerName” to be considered valid.

▪ Strict – The incoming certificate must pass a number of checks, including signature check,expiry check, purpose check, and issuer check.

Tip: Use the Generous option for development or testing purposes only, and the Strictoption for any other purpose.

4. If the server is to use client authentication during the handshake, select the ClientAuthentication check box.With this check box selected, the server sends a client authentication request to the client duringthe initial handshake. The server also receives the client certificate and performs authenticationaccording to the issuer’s certificate (or certificate chain) set in the security context record.


Next step

Selecting the certificate path rule, on page 36

Setting client authentication properties

With an SCR for client, the client must verify the validity of certificates during handshake negotiations.In this child task of creating a security context record, you will set the parameters that the client usesto authenticate certificates.

Prerequisites

Selecting server or client usage, on page 34

1. In the Client Authentication Properties dialog box, from the Authentication Depth list, selecta value to indicate the level of verification the client is to perform before determining that acertificate is not valid.Depth is the maximum number of intermediate issuer certificates, or CA certificates, the clientmust examine while verifying an incoming certificate. A depth of 0 indicates that the certificatemust be self-signed. A depth of 1 means that the incoming certificate can be either self-signed orsigned by a CA known to the security context record. The default value is 3.

2. Optional: In the Trusted Peer Names field, you can add one or more trusted peer names, asexplained here.

The client uses this list of peer names to determine whether to trust a peer in handshakenegotiations. Trusted server/client names are stored in the security context record.

If no trusted peer name is set, any peer is considered legitimate.

To add trusted peer names, click Add. For steps, go to Adding trusted peer names, on page 36.


36

3. From the Authentication Strength options, select the level of security to be used in theauthentication process:

Note: Use the Generous option for development or testing purposes only, and the Strictoption for any other purpose.

The Client Authentication check box is not applicable to an SCR for client, so it is unavailable inthis client dialog box.


Next step


Adding trusted peer names

The U2 database server client uses a list of peer names to determine whether to trust a peer inhandshake negotiations. Trusted server/client names are stored in the security context record. In thischild task of setting authentication properties, you can add the names of trusted peers.

Prerequisites

The prerequisite task depends on the authentication method you selected:

▪ Server authentication: Setting server authentication properties, on page 34

▪ Client authentication: Setting client authentication properties, on page 35

Procedure

1. In the Peer Name field, enter one or more trusted peer names in a comma-separated list.

Note: The trust names can be either fully specified names like [email protected], orwildcard names. There are two wildcard characters: ‘%’ can be used to match ANY characterstrings, while ‘_’ (underscore) can be used to match a single character. For example,%@us.xyz.com matches both [email protected] and [email protected].

2. To save the changes and return to the parent task, click OK.

Selecting the certificate path rule

When loading a certificate to establish an SSL connection, the UniData or UniVerse (U2) databaseserver retrieves the certificate from its registered full path by default. In this child task of creatinga security context record, you can select a certificate path rule to specify the default path or analternative location in which to search for certificates.

Prerequisites

Setting authentication properties, on page 34

Procedure

1. From the Certificate Path Rule options, select a certificate path rule to specify the search path:

Associating certificates to the security context

37

▪ Default – When you add a certificate to a security context record, the full path for thatcertificate is registered in the security context record. This path is derived from the currentdirectory in which U2 is running. When the certificate is loaded into memory to establish theSSL connection, the U2 database server by default uses the registered full path to retrieve thecertificate.

▪ Relative – With this option, the U2 database server looks for the certificate in the currentdirectory in which U2 is running. Be aware that some processes, such as the Telnet server, runfrom the system directory.

▪ Path – With this option, the U2 database server uses the path you specify here to load thecertificate. You can enter either an absolute path or a relative path, or click Browse to searchfor the path.

▪ Env – If you select this option, enter an environment variable name in the Env field. With thisoption, the U2 process first obtains the value of the environment variable you specify, andthen uses that value as the path to load the certificate.

The U2 database server evaluates the environment variable only when the first SSL connection ismade. The value is cached for later reference.


Associating certificates to the security context

A certificate is used to bind the name of an entity with its public key.

It is used as a means of distributing a public key. A certificate always contains three pieces ofinformation:

▪ Name

▪ Public key

▪ Digital signature signed by a trusted third party, called a certificate authority (CA), with its privatekey

If you have the public key of the CA (contained in the CA certificate), you can verify that the certificateis authentic.

SSL protocol specifies that when two parties start a handshake, the server must send its certificateto the client for authentication. It may also require the client to send its certificate to the server forauthentication. U2 servers that act as HTTP clients are not required to maintain a client certificate. U2applications that act as SSL socket servers must install a server certificate. UniObjects for Java serversand Telnet servers also require a server certificate.

There can be only one server/client certificate per security context record. Adding a new certificateautomatically replaces an existing certificate. However, for issuer certificates, the U2 data serverchains a new one with existing certificates so U2 applications can perform chained authentication.

If the issuer certificate is in PEM format, it can contain multiple certificates by concatenatingcertificates together.

All certificates that form an issuer chain must be of the same type.

Associating server/client certificates to a security context

You can select an existing certificate to associate to the security context. This certificate is used aseither the server certificate or the client certificate in handshake negotiations.


38

▪ For an SCR for servers, go to Associating a server certificate to a security context, on page 38.

▪ For an SCR for clients, go to Optional: Associating a client certificate to a security context, on page38.

Associating a server certificate to a security context

When you use an SCR for server, the server sends its certificate to the client in handshake negotiations.In this child task of creating a security context record, you can load a server certificate to the securitycontext. Only one server certificate can be associated with a security context. If you add a newcertificate, it automatically replaces an existing certificate.

Prerequisites


Procedure

1. In the Server Certificate File field, enter the full path of the file containing the server certificate,or click Browse to search for the file location.

2. From the Certificate File Format options, select the file format for the server certificate:

▪ PEM – Base64 encoded format

▪ DER – ASN.1 binary format

▪ PKCS #12 – Public-Key Cryptography Standards format


Next step

Selecting the private key file for the server or client certificate, on page 39

Optional: Associating a client certificate to a security context

When you use an SCR for client, the client may be requested to send its certificate to the server inhandshake negotiations. In this child task of creating a security context record, you can associate aclient certificate to the security context. Only one client certificate can be associated with a securitycontext. If you add a new certificate, it automatically replaces an existing certificate.

Prerequisites


Procedure

1. In the Client Certificate File field, enter the full path of the file containing the client certificate, orclick Browse to search for the file location.

2. From the Certificate File Format options, select the file format for the client certificate:





Selecting the private key file for the server or client certificate

39

Next step

Selecting the private key file for the server or client certificate, on page 39

Selecting the private key file for the server or client certificate

A private key file protects the security of the server or client certificate. In this child task of associatinga server or client certificate to a security context record, you can select the private key file of theselected server or client certificate.

Prerequisites

Associating a server certificate to a security context, on page 38 or Optional: Associating a clientcertificate to a security context, on page 38

1. In the Private Key File field, enter the full path of the file that contains the private key associatedwith the server or client certificate, or click Browse to search for the file location.

2. In the Password for Private Key field, enter the password for the private key file.3. In the Confirm Password field, reenter the password for verification.4. From the Private Key Format options, select the format of the private key file:





Optional: Associating CA certificates to a security context record

A certificate authority (CA) certificate is used to sign other certificates. If a CA certificate is associatedto a security context, it can be used to verify incoming certificates. In this optional child task ofcreating a security context record, you can associate one or more CA certificates to the securitycontext.

1. In the CA Certificates dialog box, click Add.2. The Add CA Certificate dialog box allows you to associate CA certificates to the security context,

one at a time. In the Certificate File field, enter the full path of the CA certificate file, or clickBrowse to search for the file location.

3. From the Format options, select the format of the CA certificate:




4. To add the CA certificate to the security context, click OK.The full path of the selected CA certificate is populated in the CA Certificates dialog box.

5. Repeat steps 1-4 for each CA certificate to be added to the security context.6. To continue, click Next.


40

Selecting or generating a random file

The UniData or UniVerse (U2) database server uses a random (.rnd) file to perform every securedoperation, from generating keys to creating certificates and certificate signing requests. In this childtask of creating a security context record, you can select a random file or generate a new random fileto associate to the security context.

Procedure

1. In the Random File dialog box, use one of the following three methods to select or generate arandom file for use in the security context:

▪ By default, the U2 database server uses the random (.rnd) file in the current account. To usethe default random file, leave the Random File field blank.

Tip: The strength of cryptographic functions depends on the true randomness of keys. Asa rule, the default random file in the current account is the best means to achieve a secureenvironment.

▪ To use an alternative random file, in the Random File field enter the full path of an existingrandom file, or click Browse to search for the file location.

▪ Otherwise, to generate a new random file from seed source files, click New Random File. Goto Optional: Generating a random file, on page 40.


Next step

Optional: Specifying ciphers, on page 41

Optional: Generating a random file

In some cases, you can choose not to associate the default random file or an existing random file tothe security context. Alternatively, you can build a new random file from scratch. In this optional childtask of creating a security context record, you can generate a new random file from seed source files.

Remember: The strength of cryptographic functions depends on the true randomness of keys.As a rule, the default .rnd file in the current account is the best means to achieve a secureenvironment.

1. In the File Name field, enter a name for the new random file, or click Browse to select the filelocation.

2. From the File Length list, select a file length for the new random file.3. In the Random Seed Source Files box, populate a list of one or more seed source files to use in

generating the new random file. To select a file, click Add. Go toAdding seed source files, on page 41.

4. Repeat step 3 for each seed source file to be added.5. When you have finished adding seed source files, click OK.

The Random File dialog box is redisplayed. The name of the newly generated random file ispopulated in the Random File field.

Adding seed source files

41

Adding seed source files

A seed source file contains the data used to generate random keys. In this child task of generating arandom file, you can select one or more seed source files.

1. In the File Name field, enter the full path of a file to be used as a seed source file in generating thenew random file, or click Browse to search for the seed source file location.

2. To continue, click OK.The New Random File dialog box is redisplayed. The selected random seed source file ispopulated in Random Seed Source Files list.

Optional: Specifying ciphers

The cipher parameters determine which cipher suites and public key algorithms are supported duringthe handshake and subsequent data exchanges in the security context. In this child task of creating asecurity context record, you can specify the ciphers to associate to the security context.

Prerequisites

Selecting or generating a random file, on page 40

Procedure

1. In the Ciphers field, enter the CipherSpecs parameter for the cipher suite to use in the securitycontext.

The CipherSpecs parameter is a string containing cipher-spec separated by colons. An SSL cipherspecification in cipher-spec is composed of four major attributes and several less significantattributes. For detailed information about cipher specifications, see UniData or UniVerse SecurityFeatures.

Note: The security context's cipher suites are set automatically to SSLv3 suites supported bythe SSL version you selected.


Optional: Specifying a certificate revocation list

A certificate revocation list (CRL) is a list of the serial numbers of certificates that have been revoked.In this child task of creating a security context record, you can select one or more files containing acertificate revocation list to use in the security context.

1. In the Certificate Revocation List dialog box, populate the list with one or more certificaterevocation files to use in the security context. To select a file, click Add.Go to Optional: Specifying a certificate revocation list, on page 41.

2. Repeat step 1 for each certificate revocation file to be added.3. To continue, click Next.


42

Setting a password for the SCR

A security context record (SCR) must be password-protected to safeguard its security. In this child taskof creating a security context record, you can set a password for the SCR.

1. In the Password for SCR field, enter a password for the security context record.2. In the Confirm Password field, enter the password again for verification.3. To create the security context record, click Next.

Verifying the status of generating the SCR

In this child task of generating a security context record, you can check the status message to seewhether the SCR was generated successfully. If it was not, you can go back to make corrections.

1. In the Review Status and Finish dialog box, check the message indicating the status of generatingthe security context record.If the security context record was created successfully, the dialog box contains the message, “SCRrecord was added/updated successfully.” If the process did not generate an SCR, the message“Failed to save SCR” is displayed. To return to previous dialog boxes and correct the error, clickBack.

2. To close the Security Context Record wizard and return to the Configure SSL for Servers editor,click Finish.

Configuring SSL for U2 serversA security context record contains all SSL-related properties necessary for the UniData or UniVerse(U2) server to establish a secured connection with an SSL client. After creating a security contextrecord, you can configure SSL for a U2 server to process requests by various U2 clients, includingUniObjects (UO), UniObjects for Java (UOJ), ODBC, OLEDB, wIntegrate, and others. In this child taskof configuring SSL for U2 servers, you can configure a UniData or UniVerse (U2) database server for aselected security context record (SCR).

Prerequisites

Creating security context records, on page 33

Procedure

1. From the Service Name list, select the name of the U2 service for the U2 database server.2. From the SCR Database list, select the database account in which the security context record to

be configured is stored.3. In the Path field, the full path of the selected database account is displayed. Verify that this is the

correct path for the security context record.4. From the SCR Record list, select the security context record for this SSL configuration entry.5. In the Password Seed field, enter the password for this SSL configuration record.6. In the Confirm Password field, enter the password again for verification.7. To add the SSL configuration entry, click OK.

The new configuration record is listed in the Server Configuration tab of the Configure SSL forServers editor.

43

Chapter 6: Managing Automatic Data Encryption

Automatic data encryption (ADE) operationsThe UniData and UniVerse (U2) database servers offer automatic data encryption (ADE) as an optionalfeature for securing data-at-rest. ADE is an integrated solution built into the U2 database architecture,providing comprehensive data security with no extra licensing required.

The ADE model hinges on a password-protected master key, which it employs in all encryptionoperations. It uses the master key to derive encryption keys, which are used to encrypt and decryptthe content of U2 data files and index files. When encrypting a file, you must associate an encryptionkey and an encryption algorithm for each object to encrypt. ADE gives you the ability to encrypt anentire record or just specified fields in the record.

The U2 database server automatically encrypts data when it writes records to a U2 file. Itautomatically decrypts data when it reads records from a U2 file. The data read and write operationsmay be initiated directly by the U2 database server or through UniBasic or UniVerse BASIC commands.

The U2 automatic data encryption feature supports Federal Information Processing Standards (FIPS)encryption algorithms, including Data Encryption Standard (DES) and Advanced Encryption Standard(AES) algorithms. ADE uses these industry-standard algorithms to produce strong encryption keys thatprotect the content of U2 data stores.

ADE has many advantages, but be aware that it adds to system overhead. When using automatic dataencryption, system performance might decrease somewhat due to encryption operations, and moredisk space might be required. However, the benefits of securing data-at-rest in most cases outweighthe disadvantages.

Initiating data encryption tasksAll tasks related to automatic data encryption (ADE) are performed in the editor view, which you canopen from the Admin Tasks view in XAdmin.

Prerequisites


Procedure

To open the Data Encryption editor, in the Admin Tasks list double-click Data Encryption.

Administering data encryptionThe Data Encryption tools inside XAdmin assist you with creating keys, encrypting and decrypting files,managing the key store, setting password policies, and performing associated tasks to administer day-to-day data encryption activities.

Before administering data encryption, see Initiating data encryption tasks, on page 43, thencomplete the tasks in Managing Automatic Data Encryption, on page 43.

Chapter 6: Managing Automatic Data Encryption

44

Managing encryption keysThe U2 automatic data encryption (ADE) feature uses encryption keys to encrypt, decrypt, and re-encrypt individual U2 files. Encryption keys are derived from the master key, so their security dependslargely on password protection of the master key and safe storage of the master key file. Using theKeys tool inside the Data Encryption editor, you can create and delete encryption keys, view details ofencryption keys, grant or revoke user and group access to keys, and change passwords for keys.

Opening the Keys tool

All tasks associated with managing encryption keys are performed in the Keys tool of the DataEncryption editor. Opening the Keys tool is the starting point of all encryption key tasks.

In the Data Encryption editor, click the Keys tab.The Keys tool opens. All existing encryption keys are listed in the left pane. Details of the selectedencryption key are shown in the right pane.

Creating encryption keys

The automatic data encryption (ADE) feature uses an encryption key to encrypt, decrypt, and re-encrypt individual files. In this task, you can create an encryption key and optionally set a passwordfor the key.

1. In the Keys tool, click Add.2. In the New Encryption Key dialog box Key Name field, enter a unique name for the new

encryption key.3. Optional: In the Password field, enter a password for the encryption key.

If you set a password for the encryption key, the current password is required later to change thepassword for the key or to delete the key.

4. If you set a password for the encryption key, in the Confirm Password field, enter the passwordagain for verification.

5. To create the encryption key, click Finish.

Viewing encryption key details

All existing encryption keys that have been created for use in encrypting U2 files are listed in the leftpane of the Keys tool. In this task, you can select a key and view its details.

1. In the left pane of the Keys tool, select the name of the encryption key for which you want to viewdetails.

2. In the New Encryption Key dialog box Key Name field, enter a unique name for the newencryption key. Check the details for the selected encryption key in the right pane, as follows:

▪ Key Name displays the unique name of the selected encryption key.

▪ Creator contains the user ID of the person who created the encryption key.

▪ Date Created displays the month, day, and year (MM/DD/YYYY) on which the encryption keywas created.

▪ Time Created displays the time (HH:MM am|pm) at which the encryption key was created.

Deleting encryption keys

45

▪ Date Password Changed displays the month, day, and year (MM/DD/YYYY) on which thepassword for the encryption key was last updated. If the key is not password-protected, thisfield contains the date on which the encryption key was created.

▪ Time Password Changed displays the time (HH:MM am|pm) at which the password for theencryption key was last updated. If the key is not password-protected, this field contains thetime at which the encryption key was created.

▪ Grantees lists the names of users and groups who are granted access to the encryption key.

▪ References lists the U2 files and fields that reference the selected encryption key.

Deleting encryption keys

If an encryption key is no longer used or is not needed, you can delete it from the key store.

Note: If a key is deleted from the key store, then any data encrypted with that key cannot bedecrypted. Keys should only be deleted when they are no longer used to encrypt any data fileseither on the system concerned or on any system backups that may need to be restored andaccessed at some time in the future.

If at all in doubt about the key concerned, Rocket recommends exporting the key prior to deletionand saving the exported file (which is also encrypted) in a separate secure location in case of futureneed.

1. In the Keys tool, select the name of the encryption key to be deleted and click Delete.2. If the selected encryption key is password-protected, in the Password field, enter the current

password for the encryption key.3. If you set a password for the encryption key, in the Confirm Password field, enter the password

again for verification.4. To delete the encryption key, click Finish.

In the Keys page, the name of the encryption key is removed from the list. In the UniData orUniVerse database, the associated key file is deleted from the key store.

46

Chapter 7: Managing the credential wallet

U2 servers token-based authenticationAs customers are moving to a cloud-based Identity Management (IdM) system for user authenticationin their application, the current user ID and password method of connecting to U2 servers is becomingless appropriate or even possible. At UniData 8.1.1, token-based authentication is available to providesecurity and future extensibility for IdM systems.

Note: This feature is not yet available for UniVerse.

This section discusses how pre-configured and corresponding credentials are established, verified,and trusted in token-based authentication for connections between your application and backend U2servers.

Warning: Token-based authentication is more vulnerable than direct OS user credential-basedauthentication because if, for example, the token credential is compromised, then potentially anyand all OS users can be misrepresented. We strongly recommend that the U2 database is in a DMZor behind a firewall behind a secure, isolated environment, and the connections are always secure.For more information, see the sections about SSL in this manual.

Overview of IdM and token-based authenticationThe following architectural diagram describes the two options available to connect to a U2 Databaseserver. The traditional method requires username and password, which is used to validate thelegality of the connection using operating system calls. The new token-based connections requireusername@TOKEN-ID (no password), and providing the username and TOKEN-ID are known to the U2credential manager, the connection will be allowed through.

Token-based authentication

47

Token-based authenticationToken-based authentication supports no password login to U2 Servers. Prior to UniData 8.1.1, U2Servers require actual OS user ID and password to impersonate the user.

Warning: On Windows, the Active Directory is required for token-based authentication towork. If authentication involves servers belonging to different domains, a mutual-two-way trustrelationship between domains is required.

For obvious security concerns, U2 cannot do this blindly for any client connections; otherwise thebackend database will be open for unauthorized accesses. To authenticate the IdM application, anauthentication token is supplied by the connection and points to the backend U2 server.

Authentication token

The authentication token contains two parts separated by "@". The left side contains informationsuch as the user name, and the right side contains the actual name of the token-ID.

Currently this token is nothing but an ID and its password. The ID is not necessarily for an OS user ID,nor is the password.

Auth ID

Auth ID is used to search the credential wallet for a mapping to an OS-level user account. Its generalformat is:

OS-user-id@TOKEN-ID

Depending on the application’s need, the Auth ID can be in one of the following forms:

▪ OS user account only, such as johnz. In this case, account impersonation is done like previousversions.

▪ TOKEN-ID only, such as @PRODUCTION. Note that the preceding @ is required.

▪ Full format, such as johnz@PRODUCTION

Password

Depending on how the Auth ID is formed, the password can be either a direct OS user accountpassword, or a token password set up by the Credential Wallet Manager (credman).

Credential mapping recordThe credential mapping record is a multi-column text record that maps a token-ID to an OS user ID.

A token record is a logical collection that maps an authentication ID to an OS user or an OS group.Each token record should explicitly specify its members, which can be either individual OS user IDs orOS group IDs. For the latter case, each group ID must be preceded with an asterisk; IDs are separatedby commas. If no member is specified, U2 validates the token password only. The AuthID will be usedfor no password login for the OS ID that the token is part of.

If an OS ID is specified for a record, it can be used as a default user ID if the Auth ID is suppliedwithout a specific user ID (such as @PRODUCTION). If the PRODUCTION token does not have an OS IDspecified, using @PRODUCTION will result in authentication failure.


48

Allowed services specify which interfaces that can use this mapping record (such as InterCall, UCI, ortelnet). Currently, there are 4 valid values:

▪ UDCS or UVCS (for InterCall servers that support UO, UOJ and UO.NET)

Note: Telnet, XAdmin, and UniAdmin connections are not supported.

▪ UDSERVER or UVSERVER (UCI servers support ODBC, OLE DB, and JDBC)

A token password must be specified when creating a token record, and it is required whenever alookup (mapping) is requested. Currently there are no password policies enforced other than requiringa minimum length of 8 characters.

Credential wallet

The credential wallet is a collection of credential mapping records stored as an OS-level opaque filethat is automatically encrypted and control-accessed.

The only allowed access to this wallet is through the Credential Wallet Manager or through internalcalls by U2 Servers.

To secure this file, in addition to encryption, a machine tag can be added so that the file cannot bemoved to other machines and used directly. An optional wallet password can also be specified for thewallet to protect the integrity of it. If a wallet has password protection, then for any wallet operations,a valid password must be provided. Note that when mapping an Auth ID to OS ID, this wallet passwordis not required.

Adding a mapping record

The credential manager performs additions, deletions, and other necessary management tasks.

In XAdmin, you create a mapping record using the Credential Manager options from the Admin Taskspane, as described in the following steps.

Adding a mapping record

49

1. To access the credential manager tools, in XAdmin, select the server you want to use. From theAdmin Tasks pane, double-click Credential Manager.The Credential Mapping Records pane opens, as shown in the following example.

2. Click Add.3. Enter the values for your mapping record in the dialog box that appears, then click OK. The

following table describes each field.

Field Description

Token Type The TokenType of 2 cannot be changed. This value means the token isuser defined; whereas 1 is a system-defined meta token.

Token ID The ID of the mapping record

Password Adds a password for the mapping record

Confirm Password Confirms the password

OSID The operating system ID or user

Allowed Services Specifies which interfaces can use this mapping record. Allows servicesinclude:▪ UDCS or UVCS (for InterCall servers that support UO, UOJ and

UO.NET)

▪ UDSERVER (UDUCI) or UVSERVER (UVUCI) (UCI servers supportODBC, OLE DB, and JDBC)

Members Specifies which members or groups are added to the mapping record.

Note: XAdmin does not support the import file function that the credman utility is able toperform.

After you click OK, the dialog box closes and you can see the mapping record displayed in theCredential Mapping Records tab.

4. Optional: You can search for credential mapping records by entering a search term in the Filtersfield.


50

5. Optional: Click the Configuration tab to define or modify the wallet password and machine tags.

Sending the token to the U2 Server

After you have defined a token-ID and its properties, your client application can now start using thetoken-based authentication method to connect to the U2 server via the unirpc interface using one ofthe following services: UDCS, UVCS, UDServer, and UVServer.

The U2 Server verifies the credentials received using the credential wallet. Once verified, theconnection impersonates the corresponding actual OS user.

If the wallet is not present on the system, or the authentication token cannot be mapped and verified,then the U2 Server reverts to using the old style OS-ID-password impersonation method. It treatsthe ID and password as actual OS credential to impersonate. If the “Auth ID” is provided withoutthe token-ID part (@tokenid), then U2 servers perform impersonation as is now – maintaining 100%backward compatibility.

When performing mapping lookup, membership checking is tested against each OS-group until eithera containing group is found or all OS groups are exhausted. In other word, the OS-group membershipis based on conventional system setup outside of this implementation. There is no need to re-specifyOS-group membership in the wallet.

The membership checking is done each time a connection is requested. If you have many groups ora large number of individual OS user IDs specified in a token record, performance may be adverselyaffected.

51

Chapter 8: Managing licensesTo access the License tool in XAdmin, select the server you want to use. From the Admin Tasks pane,expand License. The License pane opens and displays the database type that you are using. In thefollowing example, UniVerse is the displayed database.

Note: Not all of options shown are available for UniData.

Updating license informationAfter you have opened the License pane, verify that the number of users and expiration date displayedin the License pane matches the configuration on the Product Configuration sheet shipped withUniData or UniVerse.

Note: If you are using UV/NET, you must authorize both the UniVerse database and UV/NET.

Procedure

1. Enter your UniData or UniVerse serial number in the Serial # box.2. Enter the number of users for which you are licensed in the UniVerse User Limit (UniVerse) or

UniData RDBMS (UniData) field.3. Enter the number of Connection Pooling licenses in the Connection Pooling box. If you are not

licensed for any connection pools, enter 0.4. Enter the number of device licenses for which you are authorized in the Device License box.5. UniData only. Select the NFA checkbox if you are running Network File Access (NFA).

Chapter 8: Managing licenses

52

6. UniData only. Select the RFS checkbox if you are running Recoverable File System (RFS).7. Select the EDA check box if you are running External Database Access (EDA).8. UniVerse only. Select the AUDIT check box if you are running Audit Logging.9. Select the SUBKEY check box if you are using device subkeys with device licensing.10. If the expiration date of you license is incorrect, enter the correct date in the Expiration Date box.11. Verify that the number of users and expiration date displayed in the Licensing dialog box matches

the configuration on the Product Configuration sheet.

Obtaining an authorization codeAfter updating all of the license information, you must obtain an authorization code.

Updating license information, on page 51

Procedure

1. Copy the configuration code shown in the Configuration Code field.2. Go to the Rocket Authorization page, listed below, and follow the instructions on the website to

obtain the authorization code.▪ US: https://rbc.rocketsoftware.com/authprod.asp?js=y

▪ International: https://rbcint.rocketsoftware.com/authprod.asp?js=y3. Paste the authorization code into the Authorization Code field.

You must authorize UniData or UniVerse within 10 days of installation.

Configuring Account-based licensesFrom the XAdmin menu, double-click License, then click the Account-based License tab.

1. In the Logical License Account Definition area, click Add.The Add Account dialog box opens.

2. In the Path box, enter the full path to the account to which you want to allocate licenses, or clickBrowse to locate the account.

3. In the License Account ID box, enter the logical license account ID for the account.4. In the Account License Configuration area, click Add.5. Expand the Licn Account ID list and select the Logical Account ID to which you want to allocate

licenses.6. In the Seats/DB box, enter the number of database licenses you want to allocate to the account.7. In the Seats/CNPL, enter the number of connection pool licenses you want to allocate to the

account.8. Optionally, you can enter a description for the license account ID license allocation in the

Description box.9. Click Save.

If you change the configuration outside of XAdmin, you must Refresh for the change to take effect.

https://rbc.rocketsoftware.com/authprod.asp?js=y

https://rbcint.rocketsoftware.com/authprod.asp?js=y

53

Chapter 9: Managing U2 Data ReplicationRocket U2 Data Replication provides an automatic way to deliver read-only copies of UniData orUniVerse files to other UniData or UniVerse systems. You can use the replicated data as a standbysystem in case of system failure, or as a reporting system.

The system where the source data resides is called the publisher. A system requesting copies of fileupdates from the publisher is called a subscriber.

There are four types of replication:

▪ Real-time: Real-time replication is a type of U2 Data Replication where transactions on thepublishing server do not commit until all logs of the transaction arrive at the subscriber. With thistype of replication, should the publishing server failover to the real-time subscribing system, allcommitted transactions on the publishing system are guaranteed to apply to the standby system.

▪ Immediate: Immediate replication is a type of U2 Data Replication where UniData or UniVersesends a transaction log to the subscribing system immediately after it is ready to commit. Thepublishing system does not wait for the log to arrive on the subscriber before committing thetransaction. Should the publishing server failover to the immediate subscribing system, there isa slight chance that some committed transaction on the publisher did not arrive on the failoversystem. Administrator intervention may be necessary to recover the system.

Note: Immediate replication has better performance than real-time replication.

▪ Deferred: Deferred replication saves transaction logs in a file rather than sending them to thesubscriber at a predefined period of time. The subscribing system connects to the publishingserver, retrieves all of the logs, and synchronizes its database to the publishing database. Deferredreplication can only be used in non-standby replication.

▪ Delayed: Delayed replication allows updates to be delayed by a specified time on the standbysystem in U2 Data Replication. With this type of replication, you can failover to the subscribersystem up to a specified time. This will allow you to cancel or void some unwanted updates duringthe failover to protect the database from accidental misuse or malicious damage.

Managing U2 Data ReplicationTo access the replication tools, in XAdmin, select the server you want to use. From the Admin Taskspane, expand Replication (U2 Replication in UniVerse), then double-click Configuration.

The Replication pane opens and displays the database type that you are using. In the followingexample, UniData is the displayed database.

Chapter 9: Managing U2 Data Replication

54

Note: The Recovery Logs tab shown in the previous example is only available with UniData.

To administer U2 Data Replication, perform the following tasks:

1. Defining replication systems, on page 542. Adding a publishing group, on page 553. Adding a subscribing group, on page 574. Verifying the account defaults, on page 585. Starting replication, on page 59

Defining replication systemsOnce you have opened the Replication pane, define the replication systems. This task needs to beperformed on both the publisher and subscriber servers.

1. To define replication systems, click the System Definition tab.2. To add a new system, click Add.

The Replication System Definition dialog box appears.3. In the System ID field, enter the system name.4. In the Host Name field, enter the host network name or network address of the system.

Select the DHCP check box if the remote system has a dynamic IP address.5. In the Version field, enter the database version on the system. For UniVerse, the version must be

111 or higher. For UniData, the version must be 60 or higher.6. Auto resume determines if replication from the publishing system you specify will be

synchronized and resume automatically when UniVerse or UniData starts, or after a

Adding a publishing group

55

reconfiguration. Select Yes if you want UniVerse or UniData to automatically resume processing,or No if you want to manually synchronize data and resume processing.

7. In the Sync Interval field, select the time interval, in minutes, in which the replication systemautomatically synchronizes replication.U2 Data Replication automatically issues a SYNC request to the publishing system every perioddefined by sync_interval. A sync_interval of 0 indicates a manual synchronization system, whereUniVerse or UniData does not automatically synchronize the systems.

8. Optional: Select Connection Authorization. If you select this check box on the subscribingsystem location definition on the publishing system, you must define the connection user nameand password to the publishing system location after you complete this dialog box.

9. In the Timeout field, define the timeout interval.The timeout interval defines the number of seconds to wait if no packets are received beforesuspending replication.The publishing system sends a packet to the subscribing system approximately every 4 secondswhen replication is idle. If the publishing system had the timeout interval defined, the processcounts the time that has elapsed between packets being received. If the amount exceeds thetimeout interval, replication is suspended.

Note: We recommend that you not set the timeout interval to less than 2 minutes.

10. Enter the full path to the trigger in the Exception Action field, or click Browse to locate thepath. The Exception Action is a shell script on UNIX platforms, or a batch program on Windowsplatforms.

11. In the Failover Action field, enter the full path to the failover action or click Browse to locate thepath.

12. To define an account for replication, click Add.13. In the dialog box that appears, enter a name for the account in the Account Name field.14. Enter the full path to the account in the Account Path field, or click the arrow and select the full

path to the account from the list.The account information is written to the repsys file. You can refer to the account name in otherareas of replication without having to specify the full path.

15. Click Finish.16. If you selected Connection Authorization on step 8, select the system and click Set Connection

to define the connection user name and password to the publishing system.17. In the dialog box that appears, enter the login name and the corresponding password. Reenter

the password. Click Finish.

Adding a publishing groupAfter you have defined the replication systems, add a publishing group.

1. In XAdmin, from the U2 Resource pane, select the publisher server. From the Admin Tasks pane,expand Replication then double-click Configuration.The Replication pane appears.

2. Click the Replication Group tab.3. To add a publishing group, from the Publishing Groups area, click Add.4. In the dialog box that appears, enter the ID of the publishing group in the Group ID field.5. Specify the publishing account by selecting the account where the files you want to publish reside

from the Account list.


56

6. To define replication level, select the level of replication you want from the Level list. You canselect either ACCOUNT or FILE replication.If you select ACCOUNT, replication will occur at the account level for the account you selected.This means every file in that account will be replicated.If you select FILE, only the files selected in the Files area will be replicated for the account youselected.

7. To add files to the publishing group, in the Files area, click Add.A dialog box appears with all the files for your account listed. If you selected ACCOUNT in step5, you can still select specific files for reasons such as making them sub-writable. If you selectedFILE in step 5, select the specific files that you want to publish.When you are done adding files, click Finish.

8. By default, both the Data and the Dict cells of the file are selected. If you do not want to publishthe data portion of the file, clear the Data check box (cell). If you do not want to publish thedictionary portion of the file, clear the Dict check box (cell).

9. If you want to make any of the files that you selected sub-writeable, select the cell for that file.A check mark appears in the SUB_WRITABLE column. Making a file sub-writable allows you to editor change them on the subscriber without error.

10. If you are using account-level replication, you can select files to exclude from U2 Data Replication.To specify any files that are excluded, in the Excluded Files area, click Add.Select the specific files that you want to exclude, and click Finish.

11. Set any of the configuration parameters necessary for your environment in the Configurationarea.The following table describes each of these parameters.

Parameter Description

RFS FailoverSystem

Defines the behavior of U2 Data Replication when a publishing group starts.If you are running RFS, when UniData starts it checks to see if the system wasproperly shutdown when UniData stopped. If it was not, UniData runs crashrecovery to recover the database.

Note: This parameter is currently only available in UniData.N_LOGINFO The maximum number of replication logs that can be loaded in the shared

memory buffer. If the number of logs in the replication buffer exceeds thisvalue, UniVerse or UniData stores the logs in the replication buffer extendedfile. The default value is 4096.

REP_BUFSZ The shared memory buffer size used to hold the log body for the replicationgroup. The default value is 1048576.

LARGE_RECSZ When a record is larger than the value of LARGE_RECSZ, UniVerse or UniDatastores it in the LEF instead of the Replication buffer. The default value is 64K.

RESERVED_FILE_SPACE

Defines the amount of file slots to reserve for an account-level group. Thedefault value is 500.

Pacing level The pacing level is a tunable parameter for a replication group that definesthe overall delay level of the group. The higher the pacing parameter is, thelonger a delay will occur if the other pacing criteria are in effect. The valuecan be an integer from 0 to 255. A pacing level of 0 turns off replication pacingfor the group. The default value is 5.

Note: This parameter is currently only available in UniData.

For more information about pacing, see Replication pacing, on page 60.

12. Click Finish.

Adding a subscribing group

57

Adding a subscribing groupAfter you have added a publishing group, add a subscribing group.

1. In XAdmin, from the U2 Resource pane, select the subscriber server. From the Admin Tasks pane,expand Replication then double-click Configuration.The Replication pane appears.

2. Click the Replication Group tab.3. Decide whether you to manually add a subscribing group or you want to import the configuration

from the one you set in the publishing server, as described in Adding a publishing group, on page55. To add one manually, continue to the next step. To import the configuration, click Import.a. In the dialog box that appears, select the server where you set up the publishing group.b. Select the version number.c. Select whether you want to merge or replace the subscribing configuration file with the

remote one.d. Click Finish.

The configuration is imported, and the values are automatically populated in the dialog boxthat appears.

e. Verify that your configuration is correct, and click Finish.You have successfully added a subscribing group, and can move on to Verifying the accountdefaults, on page 58.

4. To add a subscribing group, from the Subscribing Groups area, click Add.5. In the dialog box that appears, select the publishing system from which this subscribing system is

receiving data from the From System list.6. Select the group ID from the publishing system in the Group ID list.

When you select the group ID, XAdmin populates the file list and configuration parameters fromthe same group ID on the publishing system.

7. Select the account to which you want to replicate data in the Into Account field. XAdminautomatically populates the Account Path field.

8. Click the file you want to receive. You can select multiple files by clicking the file while holdingdown the CTRL key.

9. By default, both the Data and the Dict cells of the file are selected. If you do not want to receivethe data portion of the file, clear the Data check box (cell). If you do not want to receive thedictionary portion of the file, clear the Dict check box (cell).

10. If you want to be able to update the file on the subscribing system, select the SUB_WRITEABLEcheck box (cell).

11. If you are using account-level replication, you can select files to exclude from U2 Data Replication.To specify any files that are excluded, in the Excluded Files area, click Add.Select the specific files that you want to exclude, and click Finish.

12. In the Distributions area, click the value in the Type field, then select the ellipsis button (...) thatappears.

13. In the dialog box that appears, select the type of replication mode you want and the account forthe subscriber.

When choosing Realtime or Immediate subscribing, the subscribing system can optionallybe defined as a standby system. This can be done by selecting the Hot Standby check box. Astandby system can also be optionally configured for delayed standby replication.

When selecting the Hot Standby check box, a Delayed Time Period field appears. Enter theamount of time you want to delay the updates on the subscriber in minutes. When using delayedstandby replication, the updates are immediately sent to the subscriber but are not applied untilthe delayed time period has elapsed.


58

Click Finish.14. Set any of the configuration parameters necessary for your environment in the Configuration

area.The following table describes each of these parameters.


RFS FailoverSystem

Defines the behavior of U2 Data Replication when a publishing group starts.If you are running RFS, when UniData starts it checks to see if the system wasproperly shutdown when UniData stopped. If it was not, UniData runs crashrecovery to recover the database.

Note: This parameter is currently only available in UniData.N_LOGINFO The maximum number of replication logs that can be loaded in the shared

memory buffer. If the number of logs in the replication buffer exceeds thisvalue, UniVerse or UniData stores the logs in the replication buffer extendedfile. The default value is 4096.

REP_BUFSZ The shared memory buffer size used to hold the log body for the replicationgroup. The default value is 1048576.

LARGE_RECSZ When a record is larger than the value of LARGE_RECSZ, UniVerse or UniDatastores it in the LEF instead of the Replication buffer. The default value is 64K.

RESERVED_FILE_SPACE

Defines the amount of file slots to reserve for an account-level group. Thedefault value is 500.

Pacing level The pacing level is a tunable parameter for a replication group that definesthe overall delay level of the group. The higher the pacing parameter is, thelonger a delay will occur if the other pacing criteria are in effect. The valuecan be an integer from 0 to 255. A pacing level of 0 turns off replication pacingfor the group. The default value is 5.

Note: This parameter is currently only available in UniData.

For more information about pacing, see Replication pacing, on page 60.

15. Click Finish.

Optional: Changing a replication group definitionYou can change a replication group definition without having to stop and restart UniData or UniVerse.

1. From the Replication Group tab, select the group that you want to update, then click Detail.2. Make the appropriate changes, as described in Adding a subscribing group, on page 57 and

Adding a publishing group, on page 55, then click Finish.After making your changes, you may need to resubscribe the group to update the subscribersystem’s configuration.

Verifying the account defaultsYou can view the account defaults to see which files are automatically included (replicated) andexcluded.

1. In XAdmin, from the U2 Resource pane, select a server. From the Admin Tasks pane, expandReplication then double-click Configuration.The Replication pane appears.

Starting replication

59

2. Click the Account Default tab.The Files area displays all of the default files that are included in the replication process. TheExcluded Files area displays all of the automatically excluded files.

3. Optional: If you want to include or exclude a file, click Add next to Files or Excluded Files.In the dialog box that appears, enter the file name, and select any applicable specifications –Data, Dict, and/or SUB_WRITEABLE.When you are done, click Finish.

Starting replicationAfter you have defined the replication systems and added both a publishing and subscribing group,you can start replication.

1. In XAdmin, from the U2 Resource pane, select the publishing or subscribing server. From theAdmin Tasks pane, expand Replication then double-click Configuration.The Replication pane appears.

2. Click the Replication Tool tab.3. From the Functions section, select the type of administrator option that you want to execute.

▪ Report – Reports the current status of a replication. This command is useful after a failure orfailover occurs.

▪ Sync – Synchronizes subscribing systems to their publishing systems. The publishing systemestablishes a connection to the subscribing system and invokes the subscribing process.UniVerse or UniData reads and transfers replication logs from the publishing system to thesubscribing system. The subscribing system then applies the updates to the database.

▪ Reconfig – Reconfigures the replication configuration while UniData or UniVerse is running.

▪ Suspend – Suspends a live replication. In a suspended mode, UniVerse or UniData interruptsthe connection between the publisher and the subscriber. The publishing system saves thereplication log files to the replication logs reserve file rather than transferring them to thesubscribing systems. The subscribing system and all replication writer processes stop afterthey finish updating existing logs in the replication buffer.

▪ Failover – Changes the replication direction on a local system, either from the local system tothe publishing system or subscribing system, or changes the subscribing source distribution.

▪ Reset – The reset command clears saved replication logs in the replication log reserve file. Usethe reset command after you copy or store database files, since the remaining replication logsare no longer useful.

▪ Enable – Enables replication.

▪ Disable – Disables replication. For more information, see Replication disablement, on page60.

For more information about each of the commands, see the U2 Data Replication User Guide forUniVerse or UniData.

4. The choices in the Options section become available based on which function you select. Selectthe appropriate options for this replication.

5. Select whether you want a target definition of All or Selected.A target is a replication, a replication group, or a distribution of a replication group. A replicationis all data replicated from a remote system to the local system, or from a local system to a remotesystem. A target definition of ALL represents all replications on the system. One command canhave multiple targets.If you want to execute the command against all targets, leave All selected in the Targets area.


60

If you want to select the replication to execute the command against, select the Selected optionin the Targets area of the replication tool dialog box, then click Add. In the dialog box thatappears, enter the target information, then click Finish.

6. Start the replication process by selecting Execute.Any output from the command appears in the Status box.

Replication disablementReplication disablement is an enhancement to U2 Data Replication that allows a databaseadministrator to temporarily disable the replication system and stop generating unnecessaryreplication logs for better performance, and to avoid running out of disk space which could triggersystem crash.

U2 Data Replication can be disabled for any of the following reasons:

▪ The administrator determines that it is no longer necessary for the replication system to berunning, for example, if problems with the subscribing system occur or changes are necessary forthe requirements of replication.

▪ The replication system incurs an unrecoverable failure, for example, the communication link failsbetween the publisher and subscriber, and the log area fills up before the communication link canbe restored. A similar situation can occur if a power failure arises at the subscribing system.

To set up replication disablement, you must define the REP_DISABLE_DISK_PCT parameter in theudtconfig file. This parameter defines the system-wide limit of disk usage for replication logs. Thevalue is the maximum percentage the replication log files can consume of the total space availableon the file system in which the logs are configured. The default udtconfig parameter is 95%. U2Data Replication is disabled immediately if this limit is reached, and a full resynchronization of thesubscriber would be required after this event. If the replication log disk is shared with data files orother applications, you should properly define this percentage with that in consideration to preventapplication or database failure due to a growing replication log file size.

To define this parameter, use the Configuration Editor from the Admin Tasks pane in XAdmin.

For example, REP_DISABLE_DISK_PCT=95.

Replication pacingReplication pacing allows U2 Data Replication to gracefully slow down the pace of publisher databaseupdates when replication falls behind. This prevents the replication system from overflowing andultimately disabling U2 Data Replication.

Note: Replication pacing is currently only available in UniData.

Pacing gracefully slows the database updates to prevent too many replication overflows to the logfiles. As the publisher process slows the updates, the subscriber is able to catch up according topriorities set by the administrator. Administrators can define a session priority level that ensurescritical updates are replicated faster than non-critical updates or background processes.

To define the pacing level, from the Admin Tasks pane, expand U2 Replication > Configuration.Select a publisher or subscriber group (or add a new one as described in Adding a publishing group, onpage 55), and click Detail. The Pacing Level field allows an integer from 0 to 255. 0 turns off pacing.The default value is 5.

Diagnosis utility

61

When the process finishes a single update or transaction commit, all degradation weights are addedtogether to calculate the degradation time.

The following formula shows the calculation:

Group pacing weight=Sum(Pacing weights)*Group pacing level

Delay time=(Group pacing weight)*Session priority level*10 microseconds

If there are multiple groups, the group pacing weight would be the sum total of each group beingupdated.

The process sleeps for the amount of the replication delay time before continuing to the nextinstruction.

Diagnosis utilityThe diagnosis utility is used by U2 support for diagnosing problems encountered with U2 DataReplication. With the utility, you can view information such as the current configuration, groups,semaphores, and other general information that can help you troubleshoot any issues you have withreplication.

To access the diagnosis utility, in XAdmin, select the server you want to diagnose. From the AdminTasks pane, expand Replication, then double-click Configuration. Click the Diagnosis Utility tab.

Replication recovery logTo view the logs from XAdmin, from the Admin Tasks pane, expand Replication, then double-clickConfiguration. Click the Recovery Logs tab.

Select the time stamp for which you want to view the logs from the Time Stamp drop-down list, thenselect the replication group in the Group ID list. XAdmin displays the recovery status.

The replication recovery log has two associated files:

▪ REP_RECV_LOG – records the recovery of publishing groups and the keys of missing transaction.

▪ REP_RECV_REC – records the records and virtual attribute values of the missing transaction.

Monitoring replicationThe replication monitoring tool monitors connection status, data transferring, and whether thepublisher and subscriber systems are synchronized.

1. To access the replication monitor, in XAdmin, select the publishing server. From the Admin Taskspane, expand Replication, then double-click Performance and double-click Status.Two tabs appear: the Replication Performance Monitor tab and the Replication StatusMonitor tab. These tabs work together to monitor replication.You can monitor two types of replication:▪ 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 onepublishing replication defined.

▪ Subscribing replication – the data replication from a remote publishing system to the localsystem, including all replication groups involved. A subscribing system can have more thanone subscribing replication defined.


62

2. Optional: You can perform the previous step again but for the subscribing server. This stepis not required, but can be useful because you can see how the publisher and the subscribercommunicate with each other.

3. Click the Replication Performance Monitor tab.a. Select the name of the replication you want to monitor from the Replications list.

Each replication is assigned a unique name on one system, consisting of the replication typeand the remote system name. A replication type can be one of the following:▪ Immediate

▪ Standby immediate

▪ Realtime

▪ Standby realtime

▪ Deferred

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

b. Select the number of seconds to refresh the monitor in the Interval in seconds field. Thedefault interval is 3 seconds.

c. Next to the Server Control field, click Start Test Period.d. Next to the Interval in seconds field, click Start.

The replication group status table displays the current status of each replication groupbelonging to the replication you specify. The following example shows the replication groupstatus table.

e. Select a row, then below the table, select either Buffer Usage, Data Volume, or LatencySplit to view the extended results displayed below the table.The following example shows the replication group status table with Buffer Usage selected.

The following example shows the replication group status table with Data Volume selected.

Monitoring replication

63

The following example shows the replication group status table with Latency Split selected.

f. By default, the table displayed with General selected. You can also view the table by testperiod by selecting TP Split from above the table.The following example shows the results displayed using the TP Split option.

4. Click the Replication Status Monitor tab.a. Select the name of the replication you want to monitor from the Replications list.b. Select the number of seconds to refresh the monitor in the Interval in seconds field. The

default interval is 3 seconds.c. Next to the Interval in seconds field, click Start.

Two traffic lights appear along with details about the replication, as displayed in thefollowing example.


64

For more information about what this table displays, see The Replication Status Monitor tab,on page 64

5. Optional: If you opened the Replication Performance Monitor tab and the Replication StatusMonitor tab for both the publisher and the subscriber, repeat the previous two steps to start bothtests.

The Replication Status Monitor tab

The following table describe the functionality from the Replication Status Monitor tab.

Field/Area Description

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

▪ Green – The publisher and subscriber are connected for all groupsinvolved in the replication.

▪ Yellow – At least one of the replication groups has been suspended by anadministrator.

▪ Red – At least one of the replication groups has been terminatedabnormally.

Sync Status The sync status indicates whether the subscribing database is synchronizedwith the publishing database. The status can be one of the following:

▪ Green – The publishing and subscribing databases are synchronized.

▪ Yellow – There are pending updates that have not been applied to thesubscribing database.

Replication Details Provides specific details about replication as described below.


65

Field/Area Description

PacketReceived

The number of packets received from the other party of the replication.Types of packets include data packets, confirmation packets, heartbeatpackets, and other control packets. Monitoring this information indicateswhether the physical connection between the publishing database andthe subscribing database is satisfactory. This number is cumulative fromthe last time UniData or UniVerse was started or U2 Data Replication wasreconfigured.

Packet Sent The number of packets that have been sent to the other party of thereplication. Types of packets include data packets, confirmation packets,heartbeat packets and other control packets. Monitoring this informationindicates whether the physical connection between the publishingdatabase and the subscribing database is satisfactory. This number iscumulative from the last time UniData or UniVerse was started or U2 DataReplication was reconfigured.

SubscriberReceived

The number of data records that have been received by the subscriber. Thisnumber is cumulative from the last time UniData or UniVerse was started orU2 Data Replication was reconfigured.

Note: When monitoring a publishing replication this number may be out ofdate if the replication status is not green.

SubscriberCommitted

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

Note: When monitoring a publishing replication this number may be out ofdate if the replication status is not green.

PublisherCommitted

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

TP Total The sum of all transactions committed in the replication groups on the localsystem. This number is cumulative from the last time UniData or UniVersewas started or U2 Data Replication was reconfigured.

CGTPsResolved

The sum of all transactions committed across more than one replicationgroup on the local system. This number is cumulative from the last timeUniData or UniVerse was started or U2 Data Replication was reconfigured.

DisablementDisk Pct

The replication logs disk percentage defined by the udtconfig oruvconfig file parameter REP_DISABLE_DISK_PCT.

Max ReplogSize

The limit the replication log file size can reach before U2 Data Replication isdisabled.

CurrentReplog Size

The total replication log file size for all replication groups.

Replication groupstatus table

The replication group status table displays the current status of eachreplication group belonging to the replication you specify. See the followingtable for a description of each column of this table.

The following table describes the columns in the replication group status table.

Column Description

Groupname

The name of the replication group.


66

Column Description

ConnectionStatus

The connection status between the publishing system and the subscribing system inthe 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 Indicates 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 beenapplied to the subscribing database.

Rep. Status The current replication group status.

▪ 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 – The replication on the subscribing system has been shut down.

▪ SUB_RUNNING – The replication on the subscribing system is running.

▪ SUB_DO_RECONFIG – A reconfiguration process is occurring on the subscribingsystem.

▪ SUB_DO_SUSPEND – The replication is suspended on the subscribing system.

▪ SUB_SYNCING – The replication is performing synchronization on the subscribingsystem.

▪ SUB_RESYNCING – The replication is performing resynchronization on thesubscribing system.

▪ SUB_DO_FAILOVER – The subscribing system is performing a failover.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 detailederror string is available in the tool tips. See the following table for a description of eachof the events.

#Recv’d The number of packets received in the group. Monitoring this number indicates ifthe physical connection between the publishing system and subscribing system issatisfactory.

#Sent The number of packets sent in the group. Monitoring this number indicates if thephysical connection between the publishing system and subscribing system issatisfactory. This number is cumulative from the last time UniData or UniVerse wasstarted or U2 Data Replication was reconfigured.


67

Column Description

DataReplicated

The total amount of data, in bytes, replicated in the group. On a publishing systemthis field represents the total amount of data sent out. On a subscribing system, thisfield represents the total amount of data received from the publishing system. Thisnumber is cumulative from the last time UniData or UniVerse was started or U2 DataReplication was reconfigured.

SubGot The log sequential number of the latest replication log received by the subscribingsystem. This number is cumulative from the last time UniData or UniVerse was startedor U2 Data Replication was reconfigured.

SubAvail The log has been loaded into the replication buffer and is available for the replicationwriter processes.

SubDone The log sequential number of the latest replication log committed to the subscribingdatabase. This number is cumulative from the last time UniData or UniVerse wasstarted or U2 Data Replication was reconfigured.

PubDone The log sequential number of the latest replication log committed to the publishingdatabase. This number is cumulative from the last time UniData or UniVerse wasstarted or U2 Data 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 or UniVerse was started or U2Data Replication was reconfigured.

DataTransfer

The total amount of transferred data that has been replicated.

Data Size The total size of data replicated.PacingLevel

The replication pacing level in a group, as defined in the REP_PACING parameter in therepconfig file.

Note: This column is currently only available in UniData.TotalDegradation

The total group pacing weight since the UniData or UniVerse system has started or U2Data Replication was reconfigured.

Total RepLog Size

The current replication log file size including LEF and LRF.

The following table describes the valid events of reasons that appear in the Changed By column thatcan cause a change in the replication status.

Event/Reason Description

AUTO_SYNC Replication is automatically resuming.CGTP_SUSPEND Cross-group transaction processing is suspended.CM_REQUEST Checkpoint manager is requested (RFS only).DBA_ORDER The system administrator issued a request resulting in a change of status.ENABLE Replication is enabled.FAILOVER A failover has occurred.PUB_REQUEST A request was sent from the publishing system, or an event occurred on the

publishing system resulting in a change of status.PUB_STARTUP The publishing system started.RECONFIG Replication is reconfiguring.REMOTE_REQ A subscribing system can request to execute a SYNC command on the

publishing system.REP_DISABLED Replication is disabled.


68

Event/Reason Description

SCHEDULED The repmanager process can only schedule a SYNC command for deferredreplication.

SUB_REQUEST A request was sent from the subscribing system, or an event occurred on thesubscribing system resulting in a change of status.

SYNCDONE A synchronization process succeeded.SYS_STARTUP The UniData or UniVerse system started.

69

Chapter 10: Managing Locks in UniVerseLocks are set on UniVerse files by certain BASIC statements and UniVerse commands. The type of lockdetermines what a process can access while other processes hold locks on records or files

To access the Locks tool in XAdmin, select the server you want to use. From the Admin Tasks pane,expand Locks. The Locks pane opens and displays the database type that you are using. In thefollowing example, UniVerse is the displayed database.

File and record locksThe following information is in the File/Record Locks list:


Device A number that identifies the logical partition of the disk where the filesystem is located.

Inode A number that identifies the file that is being accessed.Net A number that identifies the host from which the lock originated. Zero (0)

indicates a lock on the local machine.User# The user ID.

Chapter 10: Managing Locks in UniVerse

70


Lmode The lock semaphore number and the type of lock. For record locks, thereare two settings:

▪ RU for an update lock

▪ RL for a shared lock

For file locks, there are six settings:

▪ FS for a shared lock

▪ IX for a shared lock with intent to acquire an exclusive file lock

▪ FX for an exclusive file lock

▪ XU for an exclusive lock set by CLEAR.FILE

▪ CR for a shared file lock set by RESIZE

▪ XR for an exclusive file lock set by RESIZEPid The process ID number.Login Id The login ID.Record Id The name of the record that is locked.

Group locksThe following information is in the Group Locks list:


Device A number that identifies the logical partition of the disk where the filesystem is located.

Inode A number that identifies the file that is being accessed.Net A number that identifies the host from which the lock originated. Zero (0)

indicates a lock on the local machine.User# The user ID.Lmode The lock semaphore number and the type of lock. There are five settings:

▪ EX for an exclusive update lock

▪ SH for a shared lock

▪ RD for a read lock

▪ WR for a write lock

▪ IN for an information lockG-Address The logical disk address of the group. This value is 1 for a type 1 or type 19

file. Any other value is represented in hexadecimal format.Rec Locks The number of locked records in the group.Reader The number of readers in the group.SH The number of shared group locks.EX The number of exclusive update locks.

Clearing locks

71

Clearing locksYou can clear a single file, record, or group lock, or all the locks for a specified user using the Lockswindow.

To clear a file or record lock

To clear a file or record lock:

1. Select the lock from the File/Record Locks list.2. Click Clear Lock.

The Lock window is updated.

To clear a group lock

To clear a group lock:

1. Select the lock from the Group Locks list.2. Click Clear Group Lock.

The Locks window is updated.

To clear all locks

To clear all locks for a specified user:

1. Click User ID.The Clear User Locks window appears.

2. Enter the user ID in the User Id field.3. Click OK.

The Locks window is updated.

72

Chapter 11: Managing Locks in UniDataLocks are set on UniData files by certain BASIC statements and UniData commands. The type of lockdetermines what a process can access while other processes hold locks on records or files

To access the Locks tool in XAdmin, select the server you want to use. From the Admin Tasks pane,expand Locks. The Locks pane opens and displays the database type that you are using. In thefollowing example, UniVerse is the displayed database.

Note: The information displayed in the Lock Administration window is a snapshot of the file,record, and group locks when you activated the Locks option. To view the current state of locks,click Refresh.

File/Record Locks tabThe following table describes the column headings of the File/Record Locks section on the LockAdministration window.

Tip: To increase or decrease the size of a column, place the cursor on the line to the right of thecolumn heading you want to change until the cursor becomes a double-headed arrow, then clickthe mouse button and drag to the proper size.

Column Heading DescriptionUNO The sequential number the database assigns to the process that

set the lock.UNBR The process ID of the user who set the lock.UID The user ID of the user who set the lock.UNAME The log on name of the user who set the lock.

System Resource Locks tab

73

Column Heading DescriptionTTY The terminal device of the user who set the lock.FILENAME The file name in which the record is locked.INBRH The high integer of the inode of the file holding the lock, on

Windows platforms only.INBR The Inode of the locked file. On Windows platforms, this is the low

integer of the Inode of the file holding the lock.DNBR Used in conjunction with INBR to define the file at the operating

system level.RECORD ID The record ID of the locked record.M The type of lock. X indicates an exclusive lock. S indicates a shared

lock.TIME The time at which the lock was set.DATE The date on which the lock was set.

To refresh the display, click Refresh.

System Resource Locks tabThe System Resource Locks tab on the Lock Administration window displays semaphore-type locksthat reserve system resources for exclusive use. These locks can be set individually with the LOCKcommand. They are also set by other commands, including T.ATT.

The following table describes the column headings of the System Resource Locks tab.


Column heading Description

UNO Sequential number assigns to the session.UNBR Process group ID (pid) of the user setting the lock.UID User ID of the user setting the lock.UNAME Login name of the user setting the lock.FILENAME File name in which the record is locked.INBR I-node of the locked file on for UNIX only.DNBR Used in conjunction with INBR to define the file at the operating

system level on for UNIX only.TTY Terminal device of the user setting the lock.RECORD ID Record ID of the locked record.M Record lock mode.TIME The time at which the lock was set.DATE The date on which the lock was set.


Chapter 11: Managing Locks in UniData

74

Lock Waiting Queue tabThe Lock Waiting Queue tab on the Lock Administration window lists processes that currently waitingfor locks. If a process is waiting for a lock, this window displays information about the holder of thelock and processes waiting for the lock. Locks are set by each udt process through the General LockManager (GLM) module.

UniBasic commands that check for locks, such as READU and READVU, cause processes to wait forlocks to be released before proceeding.

Information about the owner of the lock is listed above the line. Information about processes waitingfor the lock is listed below the line, sorted by the date and time the process requested the lock.

The following table describes the column headings that display in the output for the Lock WaitingQueue window for the owner of the lock.



FILENAME The name of the file holding the lock.RECORD ID The record ID holding the lock.M The type of lock held. X is an exclusive lock, S is a shared lock.OWNER The user name of the owner of the lock.UNBR The process group ID (pid) of the user who set the lock.UNO The sequential number UniData assigns to the udt process for the

owner of the lock.TTY The Terminal device of the user owning the lock.TIME The time the lock was set.DATE The date the lock was set.

The next table describes the Lock Waiting Queue window column headings for the processes waitingfor locks.


FILENAME The name of the file for which a lock is requested.RECORD ID The record ID of the record for which a lock is requested.M The type of lock held. X is an exclusive lock, S is a shared lock.OWNER The user name of the process waiting for a lock.UNBR The process group ID (pid) of the user who waiting for the lock.UNO The sequential number UniData assigns to the udt process waiting for

the lock.TTY The terminal device of the user waiting for the lock.TIME The time the lock was requested.DATE The date the lock was requested.


Clearing a lock

75

Clearing a lockTo clear a lock displayed in the window, select the lock you want to clear, and then click Clear Lock.

Managing Deadlocks in UniVerseDeadlocks occur when one of several processes acquiring locks incrementally tries to acquire a lockthat another process owns, and the existing lock is incompatible with the requested lock. Conditionssuch as the following can lead to deadlocks:

▪ Lock promotion from a shared record or shared file lock to a stronger lock

▪ Lock escalation to file locks when two processes try to escalate at the same time

You can configure UniVerse to automatically identify and resolve deadlocks as they occur, or you canmanually fix a deadlock by selecting and aborting one of the deadlocked user processes. The deadlockdaemon uvdlockd identifies and resolves deadlocks.

To start, stop, or configure the deadlock manager on the server, or to manually resolve file lockingconflicts, choose Dead Locks from the U2 Extensible Administration Tool main window. When thedeadlock manager is running on the server, deadlocks are automatically resolved. The deadlockmanager keeps a log file that records all deadlocks that it automatically resolved.

When you choose Dead Locks from the U2 Extensible Administration Tool menu, the Deadlockswindow appears, as shown in the following example:

The following information appears in the :

Field Description Action

Deadlock Check Interval The number of minutes that thedeadlock process waits beforechecking deadlock conditions.XAdmin converts that time intoseconds and stores it in theuvdlockd.config file.

Choose the number of minutes.

Resolution Strategy Determines the action to take ifa deadlock is encountered.

Select one of the followingactions to resolve the deadlock:

▪ Terminate deadlockedtransaction at random

▪ Terminate newesttransaction

▪ Terminate transaction withfewest deadlocks

76

Chapter 12: Managing Deadlocks in UniVerseDeadlocks occur when one of several processes acquiring locks incrementally tries to acquire a lockthat another process owns, and the existing lock is incompatible with the requested lock. Conditionssuch as the following can lead to deadlocks:

▪ Lock promotion from a shared record or shared file lock to a stronger lock

▪ Lock escalation to file locks when two processes try to escalate at the same time

You can configure UniVerse to automatically identify and resolve deadlocks as they occur, or you canmanually fix a deadlock by selecting and aborting one of the deadlocked user processes. The deadlockdaemon uvdlockd identifies and resolves deadlocks.

To start, stop, or configure the deadlock manager on the server, or to manually resolve file lockingconflicts, choose Dead Locks from the U2 Extensible Administration Tool main window. When thedeadlock manager is running on the server, deadlocks are automatically resolved. The deadlockmanager keeps a log file that records all deadlocks that it automatically resolved.

When you choose Dead Locks from the U2 Extensible Administration Tool menu, the Deadlockswindow appears, as shown in the following example:

The following information appears in the :

Field Description Action

Deadlock Check Interval The number of minutes that thedeadlock process waits beforechecking deadlock conditions.XAdmin converts that time intoseconds and stores it in theuvdlockd.config file.

Choose the number of minutes.

Resolution Strategy Determines the action to take ifa deadlock is encountered.

Select one of the followingactions to resolve the deadlock:

▪ Terminate deadlockedtransaction at random

▪ Terminate newesttransaction

▪ Terminate transaction withfewest deadlocks

Starting and stopping the deadlock managerTo start the deadlock manager on the server using system default settings, click Enable. ClickingShutdown disables the deadlock manager.

Note: When the deadlock manager process is running, you cannot manually resolve deadlocks,and the Resolve button is dimmed. If you shut down the deadlock manager, click Refresh to selectand resolve deadlocks displayed in the Dead Locks Pending box.

Using the uvdlockd command

77

Using the uvdlockd commandYou can also use the uvdlockd command from the operating system level to administer thedeadlock daemon. The syntax is as follows:

uvdlockd { [ –t time ] [ –r resolution ] [ –l location ] } | [ –query ] | [ –stop ] | [ –v victim ]

time is the time interval (in seconds) between the deadlock daemon’s successive checks of the lock-waiter tables. The default is 60 seconds.

resolution is the resolution strategy the deadlock daemon uses. resolution is one of the following:

Value Description

0 Selects a transaction at random. This is the default.1 Selects the newest transaction.2 Selects the transaction with the fewest number of locks held.

location is the location of the deadlock log file (the default is uvhome/uvdlockd.log).

–query generates a report based on a one-shot analysis of the lock-waiter tables and any detecteddeadlocks.

–stop shuts down the deadlock daemon.

victim specifies which user number to select as the process to abort.

If the deadlock daemon is not running, the uvdlockd command starts it.

Resolving deadlocks automaticallyThe deadlock daemon automatically resolves deadlocks by creating and updating a set of lock-waitertables, which represent the state of the locking and transactional system. These tables are continuallyexamined for evidence of a deadlock. Once the daemon detects a deadlock, it selects one of thecurrently active transactions to abort, removing the deadlock.

The deadlock daemon notifies the selected transaction that a deadlock has occurred and abortsthe current execution layer. This rolls back any active transactional statements and cleans up anyremaining locks.

UniVerse provides three automatic resolution strategies for removing deadlocks:

▪ Selecting a transaction at random

▪ Selecting the transaction with the fewest number of locks held

▪ Selecting the newest transaction

Selecting a random transaction works well in most situations. Selecting the transaction with thefewest locks or selecting the newest transaction work well when transactions are long. When UniVersestarts up, the system administrator determines which of these methods the deadlock daemon shoulduse to remove deadlocks.

78

Chapter 13: Managing Windows Telnet SessionsTo manage telnet sessions on a Windows server from XAdmin, double-click Network Services, thendouble-click Telnet in UniVerse or UDTelnet in UniData. The Network Services dialog box appears, asshown in the following UniVerse example:

The Network Services dialog box contains the following fields and options:

▪ Telnet Port # – This field displays the TCP port that the telnet session uses. This is taken from theWindows registry information on Windows computers. Windows users can selectively disable theTelnet port or SSL Telnet Port by selecting the relevant Disable option. The default non-secureport number is 23. The default secure port number is 992.

Note: For information about UNIX telnet settings, refer to Administering UniData on UNIXPlatforms or Administering UniVerse on UNIX Platforms.

▪ SSL Port # – The SSL port number that the telnet service should monitor for client connections.The default value for the telnet port number is 992. We recommend that you not change this unlessyou have another service that requires socket 992.

▪ UniVerse only. User Policy – The User Policy setting determines how the telnet session is usedwhen a user makes a telnet connection.

▪ Connection Parameters – Connection Parameters are the current connection values for thetelnet service. UniVerse stores these parameters in the Windows Registry on the Server.

▪ Keep Alive Parameters – The Keep Alive parameters determine intervals when UniVerse checksthe viability of a network connection between the client and server.

▪ Set backlog queue - The maximum length of the queue of pending telnet connections. The defaultvalue is 14.

Modifying the telnet session parameters

79

▪ Detach process - If you select this option, the telnet service creates the as a detached process.

▪ Create desktop - If you select this option, the telnet service creates its own WinStation/Desktopand assigns it to the UniData process.

Note: Not all of options shown are available for UniData.

Modifying the telnet session parametersYou can modify any of the telnet session parameters from the Network Services dialog box.

Note: To use the new settings, you must stop and restart the udtelnet (UniData) or uvtelnet(UniVerse) service.

Changing the telnet session port number

To change the port number for the telnet session, enter the new port number in the Port # box.UniVerse stores the new port number as a uvtelnet entry in the services file when you click Save.

Defining the user policy

UniVerse only. As a UniVerse administrator, you can specify how all users use the telnet session. Validuser policies are:

▪ Home Account – On connection, users attach to their home directory. The home directory must bea valid UniVerse account.

▪ Home Directory – This is the default setting. Users connect to their home directory, but if thehome directory is not a UniVerse account, UniVerse prompts users to set up the account.

▪ Any Account – Users can connect to any valid UniVerse account.

▪ Any Directory – Users can connect to any directory, but if the directory is not a UniVerse account,UniVerse prompts to set up the account.

▪ UV Account – Specifies that the user connects to an existing UniVerse account defined in theUV.LOGINS file.

▪ UV Directory – Specifies that the user connects to a directory defined in the UV.LOGINS file,and can create a UniVerse account in that directory if the directory is not already configured forUniVerse.

Note: Administrators are prompted for the account to which they want to connect regardless ofthe User Policy setting.

Setting the telnet connection parameters

The four valid telnet connection parameters are:

▪ Max. Logon Attempts – Defines the number of failed log in attempts a user is allowed before thetelnet connection is dropped. The default setting is 4.

Chapter 13: Managing Windows Telnet Sessions

80

▪ Logon Pause – If a login attempt fails, the pause between login attempts (in seconds). The defaultsetting is 4 seconds.

▪ Logon Timeout – The time (in seconds) the system waits for a response to a login prompt. As soonas this time limit is reached, the telnet connection is dropped. The default value is 30 seconds.

▪ Termination Pause – The amount of time UniVerse pauses after the final failed login attemptbefore dropping the telnet connection. The default value is 4 seconds.

Setting keep alive parameters

The Keep Alive feature determines when inactive connections can be disconnected. When aconnection becomes inactive, keep-alive packets are periodically exchanged. When a number ofconsecutive packets remain unanswered, by default 20, the connection is broken.

▪ Keep Alive Interval – The interval, in milliseconds, separating keep alive retransmissions until aresponse is received. Once a response is received, the delay until the next keep alive transmissionis controlled by the value of Keep Alive Time. After the number of retransmissions specified byMax. Data Retransmissions are unanswered, the connection aborts. The default value is 1000(one second).

▪ Keep Alive Time – This parameter specifies how often TCP attempts to verify that an idleconnection is still valid by sending a keep alive packet. If the connection is still valid, the remotesystem will acknowledge the keep alive transmission. The default value is 7,200,000 milliseconds(two hours).

▪ Max. Data Retransmissions – This parameter specifies the number of times TCP retransmits anindividual data segment before aborting the connection. The retransmission timeout is doubledwith each successive retransmission on a connection. It is reset when responses resume.

Specify logon banner

You can specify the banner that users will see when they telnet to a host in the Logon Banner box.

Administering UniVerse usersUniVerse only. The UV.LOGINS file resides in the UV account. It contains a list of users and thedirectories or UniVerse accounts they log on to when they first invoke UniVerse from a telnet session.

To maintain entries in the UV.LOGINS file, click the Users tab. The UniVerse Users dialog box appears,as shown in the following example.

Adding a new UniVerse user

81

You can enter users logging on to the system both from the local machine and from domains. You canalso maintain entries for users who have accounts on multiple domains with access to this system. Youcan specify the user’s account either as a case-sensitive entry in the UV.ACCOUNTS file, or as a fullyqualified path.

If the user logs on to the system using a local machine login ID, UniVerse uses the Local Machine entry.If the user logs on to the system through a domain, UniVerse uses the entry for the domain. If the userenters a login ID without a machine or domain name, UniVerse first uses a local machine login ID if itexists, and then checks domain login IDs.

Adding a new UniVerse user

UniVerse only.To add a new user, click Add from the UniVerse Users dialog box. A dialog box similar tothe following example appears:


82

Add a UniVerse domain user

UniVerse only.To add a domain user, in the Domain area, click Add. The Domain Account Detailsdialog box appears.

Enter the name of the domain to which you want the user to connect in the Domain box.

Enter the full path to the account to which the user is to connect, or click Browse to search for theaccount.

Click OK to save the information, or click Cancel to exit without saving changes. The user appears inthe Domain area of the User Account Details dialog box.

Adding a local machine user

UniVerse only. To add a user to a local machine, in the Local Machines area of the Add Telnet Userdialog box, click Add. The Local Machine Account Details dialog box appears, as shown in the followingexample:

Enter the name of the local machine in the Local Machine box.

Enter the full path to the account to which the user is to connect, or click Browse to search for theaccount.

Configuring UniData user profiles

83

Click OK to save the information, or click Cancel to exit without saving changes. The user appears inthe Local Machines area of the User Account Details dialog box.

Configuring UniData user profilesUniData only. From the Admin Tasks view, double-click UDTelnet Users to specify which users areallowed to connect to your system through UDTelnet, and to create custom user profiles.

A window similar to the following example appears when you click the Users tab:

This dialog box enables you to specify a list of users that are allowed to connect to your Windowssystem through UDTelnet. At installation, UDTelnet is started with a default configuration that allowsany user who can access your Windows system from the network to access the system throughUDTelnet as well. This default behavior is acceptable in many instances. However, administrators maywish to grant only certain users Telnet access, or to create individual user profiles. The Users dialogbox allows this flexibility.

Warning: If you remove the Default profile, no user can log on through UDTelnet unless you havecreated a specific profile for the user.

Default user profile

When you first display the Users dialog box, you see an entry for DEFAULT in the User box. HighlightDEFAULT and click Update to display the default profile. The following example illustrates a sampledefault profile.


84

Specify default shell

In the Default Shell box, enter the full path of an executable. In the default profile, this is set toudtbin\udt.exe, which starts a UniData session.

Specify startup directory

Enter the full path of the working directory to which you want to connect when you log on in theStartup Directory box. In the default profile, this is set to the UniData demo account.

Specify arguments

In the Command Line box, enter any arguments you want to pass to the default shell. In the defaultconfiguration, this is blank.

Specify UDTHOME

Enter the full path to the UDTHOME directory in the UDTHOME box.

Determine ANSI version

Select the ANSI Version 3.x check box if you want to enable faster screen refreshes for terminals thatsupport ANSI 3.x color. By default, this check box is not selected.

Determine how to map characters

85

Determine how to map characters

Select the Use Redirection Chars check box if you want to map unprintable characters to printablecharacters. By default, this check box is selected.

Prompt for working directory

Select the Prompt Directory check box if you want the user to select a working directory when theylog on. By default, this check box is not selected.

Note: If you want one or more users to see the MS-DOS prompt when they log on, edit the userprofile or profiles so that the default shell is%systemroot%\system32\cmd.exe.

Click OK to return to the Telnet Server dialog box, or click Cancel to exit without saving changes.

Customizing user profiles

Complete the following steps to create a customized profile for a user.

1. Add a Profile. Click Add to add a user profile.

The following dialog box appears:

2. Enter the name of the user in the User Name box. Enter the logon name only (for instance,user01). Do not enter the domain name (for instance, do not enter ACCOUNTING\user01).UniData populates the dialog elements with the values from the Default Configuration. ClickOK to accept those values, or edit one or more fields to customize the profile.


86

Note: If you deleted the Default profile, UniData displays a message when you attempt toadd new user profiles. You must enter all the configuration settings manually, since UniDatacannot copy them from the default profile.

3. Customize a profile. To edit a profile, highlight the user name in the User box, then click Edit.Consider the following points when customizing a user profile:▪ Specify a full path in the Default Shell box. You can use either drive letters or the Universal

Naming Convention (UNC) to specify the path.

▪ By specifying the Startup Directory, you can direct different users to different startupdirectories, even if they are using the same default shell.

▪ You can allow users to choose their directory when they log on by selecting the PromptDirectory check box.

▪ If you do not know whether a particular terminal supports Version 3 Color, select the ANSIVersion 3.x check box. Test the terminal; if screen colors are not displayed correctly, modifythe user profile to clear the ANSI Version 3.x check box.

The following example shows a sample configuration that allows a user to log on through UDTelnet,select a starting directory, and access the MS-DOS command prompt. The default startup directory isC:\U2\ud73\demo:

Changes to a user’s configuration are visible the next time the user logs in through UDTelnet.

Generated profiles

If you selected Prompt Directory in your Default Profile, UniData creates a profile for each user whowould normally receive the default user profile. UniData creates the individual profiles the first timea user chooses a startup directory different from the default. The generated profile uses the sameconfiguration settings as the default profile, with the exception of Startup Directory, which is set tothe directory chosen by the user when they log on.

Generated profiles

87

The following examples show the effect of the Prompt Directory option. In the first example, thedefault user profile has Prompt Directory selected:

The following example shows the appearance of the screen when a user logs on:

Path (C:\U2\ud73\demo) : \U2\ud73\claireg

Notice that the default path is C:\U2\ud73\demo, and the user is selecting an alternate startupdirectory, \U2\ud73\claireg. Pressing ENTER starts a UniData session in \U2\ud73\claireg.This logon session also creates a profile for the user, which you can view or edit from the TelnetServer dialog box. The generated profile is shown in the following example:


88

The next time the user logs on through Telnet, the default path is changed, as shown in the followingexample:

Path (\U2\ud73\claireg) :

89

Chapter 14: UniVerse file utilitiesThere are a number of utilities you can use to keep your files at peak efficiency. This section describesthe XAdmin File Tools option.

Use the File Tool option for general file administration. Use the format conversion utility to importfiles and BASIC object code from different hardware platforms. For information about other UniVersefile maintenance commands and techniques, see UniVerse System Description.

Administering UniVerse filesTo administer UniVerse files, choose File Tool from the U2 Extensible Administration Tool. The FileTool window appears, as shown in the following example:

The tasks you can perform from this window include:

▪ Listing all files in all UniVerse accounts

▪ Listing file properties and statistics

▪ Running file diagnostics

▪ Repairing damaged files

Listing files in a UniVerse account

From the File Tools window, select the account for which you want to view files. All files for thataccount appear in the window, as shown in the following example:

Chapter 14: UniVerse file utilities

90

View file properties

To view the properties of a file, select the file for which you want to view properties in the File Toolsdialog box, then click Properties. The Properties dialog box appears, as shown in the followingexample:

Base information

91

Base information

From the Properties dialog box, select the Base Info tab. XAdmin displays the following informationabout the file:

▪ File name

▪ File type

▪ Separation and modulus of static hashed file

▪ Dynamic file parameters

For a detailed description of UniVerse files, see the UniVerse System Description.

Header information

From the Properties dialog box, select the Header Info tab. A dialog box similar to the followingexample appears:


92

The U2 Extensible Administration Tool displays the following header information for the file:

▪ File version

▪ SICA and schema name, if the file is a table

▪ Free chain

▪ Part block

▪ mkdbstamp

If the Read Only check box is selected, the file is read-only.

National Language Support (NLS) information

From the Properties dialog box, click the NLS tab. A dialog box similar to the following exampleappears:

Transaction logging information

93

The U2 Extensible Administration Tool displays the following information about NLS:

▪ In the Map Name box, the name of the character set map associated with the file

▪ Map checksum

▪ In the Sort Name box, the Collate convention that determines how to sort file data

▪ Sort checksum

For detailed information about NLS, see the NLS Guide.

Transaction logging information

From the Properties dialog box, click the Trans Logging tab. A dialog box similar to the followingexample appears:


94

The U2 Extensible Administration Tool displays the following information about transaction logging:

▪ File number

▪ Number of the last checkpoint log

If the Inconsistent check box is selected, and file is inconsistent.

Indexes information

From the Properties dialog box, click the Indexes tab. A dialog box similar to the following exampleappears:

Backup and replication information

95

If the file has a secondary index, the U2 Extensible Administration Tool displays the name of the indexin the Index File box.

Backup and replication information

From the Properties dialog box, click the Backup + Replication tab. A dialog box similar to thefollowing example appears:


96

The U2 Extensible Administration Tool displays the following information about backup andreplication:

▪ In the Backup Time box, the date and time of the last backup.

▪ In the Clearfile Time box, the date and time the last CLEARFILE command was executed againstthe file.

▪ The type of backup, either full, weekly, or daily.

▪ In the File Count box, the number of records in the file, counted by either the last COUNTcommand executed against the file, the last full backup, or the last restore.If the File Changed check box is selected, the file count may be out of date because the file hasbeen changed since the last file count.

▪ In the Replication area, Stat indicates whether the file is a published file, a subscription file, or afailed-over file. This area also lists the replication ID in the ID box.

View file statistics

To view statistics about a file, from the File Tools window, select the file for which you want to viewstatistics, then click Statistics.

A dialog box similar to the following example appears:

File information

97

File information

In the File Information area of the Statistics dialog box, the U2 Extensible Administration Tooldisplays the following information:

▪ File Name

▪ Date of the last update

▪ File separation if a static hashed file

▪ Modulus if a static hashed file

File statistics

The U2 Extensible Administration Tool displays the following statistics about the file you selected:

Field Description

Reads Total number of READ operations on the file.ReadUs Total number of READU operations on the file.Writes Total number of WRITE operations on the file.Write Updates Total number of WRITEU operations on the file.Oversize Reads Total number of READ operations executed against large records.Oversize Writes Total number of WRITE operations executed against large records.Overflow Reads Total number of READ operations that accessed overflow buffers.Deletes Total number of DELETE operations on the file.


98

Field Description

Selects Total number of SELECT operations on the file.ReadLs Total number of READL operations on the file.Opens Total number of OPEN operations on the file.Clearfiles Total number of CLEARFILE operations on the file.Write to Locked Total number of WRITE operations executed against a locked record.Writes Blocked Total number of WRITE operations blocked by a record lock.ReadU lock conflict Total number of READU operations that failed because of an existing

record lock.ReadL conflicts Total number READL operations that failed because of an existing

record lock.Compressions Total number of free operations that compacted a group after a record

was deleted.

Running file diagnostics

To run file diagnostics against a file, from the File Tools window, select the file for which you want torun diagnostics, then click Diagnostics. A dialog box similar to the following example appears:

Use the File Diagnostics dialog box to specify how much diagnostic testing to perform on the file,how much diagnostic detail to list in the error report window, and where to store output from thediagnostic test.

Determine diagnostic level

In the Diagnostics Settings area, select the level of diagnostic detail you want to produce in the Levelbox. The lowest diagnostic level is 1, while the highest diagnostic level is 10. The default value is 5. The

Specify types of error report

99

higher this level setting, the longer the diagnostics test takes to complete. Use the Level arrows toselect the diagnostic level.


In the Diagnostics Settings area, select the types of errors you want to appear in the Error Reportwindow. Select one of the following values:

▪ All – List all diagnostic details in the Error Report window.

▪ Fatal – List only fatal errors in the Error Report window.

▪ None – Do not list any errors in the Error Report window.

Specify output location

If you want to save a report of irreparable groups and record blocks detected by the diagnostic test,select Outpath, then enter the full path to a directory where you want to store the output.

If you want to store a copy of the error report, select Logging, then enter the full path to a directorywhere you want to store the report.

If you do not specify Outpath or Logging, the output and error report are stored in the directory wherethe file currently resides.

Click Start to start the diagnostic program, or click Cancel to exit without saving changes.

Diagnostics test

After you run the diagnostics program, the Diagnostic Run dialog box displays the account name, thefile name, and the progress of the program. It also displays the number of errors encountered andspecifies what action to take if an error is detected.

The following example illustrates the Diagnostic Run dialog box:


100

Viewing errors

After you run the diagnostics program, the Diagnostic Run dialog box displays the account name, thefile name, and the progress of the program.

It also displays the number of errors encountered and specifies what action to take if an error isdetected.

▪ The error type

▪ A description of the error

▪ The group number where the error occurred

▪ The record block number where the error occurred

After repairing the damaged file, click Rerun to rerun the diagnostic program.

Repairing damaged files

To run file diagnostics against a file, from the File Tools window, select the file you want to repair, thenclick Repair. A dialog box similar to the following example appears:


101

Use the File Repair dialog box to specify how much diagnostic testing to perform on the file, how muchdiagnostic detail to list in the error report window, and where to store output from the diagnostic test.


In the Diagnostics Settings area, select the level of diagnostic detail you want to produce in the Levelbox. The lowest diagnostic level is 1, while the highest diagnostic level is 10. The default value is 5. Thehigher this level setting, the longer the diagnostics test takes to complete. Use the Level arrows toselect the diagnostic level.


In the Diagnostics Settings area, select the types of errors you want to appear in the Error Reportwindow. Select one of the following values:

▪ All – List all diagnostic details in the Error Report window.

▪ Fatal – List only fatal errors in the Error Report window.

▪ None – Do not list any errors in the Error Report window.

Specify output location

If you want to save a report of irreparable groups and record blocks detected by the diagnostic test,select Outpath, then enter the full path to a directory where you want to store the output.

If you want to store a copy of the error report, select Logging, then enter the full path to a directorywhere you want to store the report.

If you do not specify Output or Logging, the output and error report are stored in the directory wherethe file currently resides.

Click OK to save your changes and run the Repair program, or click Cancel to run the Repair programwith default settings. The repair program starts.


102

When the Repair program completes, a dialog box similar to the following example appears:

The File Repair dialog box displays the following information:

▪ The account name where the file resides

▪ The file name

▪ The current stage of the program

▪ The number of errors encountered

▪ What action to take if an error is found

If an error is encountered, click the account name to display the Error Report window.

Rerun repair program

After you execute the Repair program, click Rerun to re-execute the program to ensure no errorsremain in the file.

Exit the program

Click Cancel the exit the dialog box and return to the File Tool window.

Repair the file if it is damaged.

103

Chapter 15: Administering UniData FilesTo administer UniData files, choose File Tool from the Admin Tasks pane and then select the filecommand you want to work with. The File Tool window opens, as shown in the following Checkoverexample:

Administering the Checkover file toolThe File Tools Checkover tool checks UniData hashed files for level 2 overflow. The Checkover toolworks on all UniData hashed files and subfiles and checks all files in a UniData account directory. Youcan execute the system-level version with UniData shut down or with UniData running.

Chapter 15: Administering UniData Files

104

1. Select File Tools → Checkover from the Admin Tasks pane.The Checkover pane opens, as shown:

2. Browse to the directory for which you want to view the level 2 overflows.3. Click Start.

The overflow files are shown in the Result box.

Administering the Convcode file toolThe system-level convcode command converts UniData object files from Motorola 68000 internalinteger format. Format information is embedded within the file header. This command automaticallydetermines if object files match the present machine integer format. If the files do not need to beconverted, UniData displays a message that no files were converted.

Administering the Convdata file tool

105

1. Select File Tools → Convcode from the Admin Tasks pane.The Convcode pane opens, as shown:

2. Browse to the directory for the account you want to convert.3. Click Start.

The converted files are shown in the Result box.

Administering the Convdata file toolThe system-level convdata command converts UniData hashed data files from Motorola 68000internal integer format to Intel 386 internal integer format. Format information is embedded withinthe file header. This command automatically determines if files match the present machine integerformat. If files do not need to be converted, UniData displays a message that no data files wereconverted. You can run convdata more than once on a UniData file.


106

1. Select File Tools → Convdata from the Admin Tasks pane.The Convdata pane opens, as shown:

2. Browse to the directory for the account you want to convert.3. Optional. Select the Convert sub-directories option if you want to process subdirectories

recursively. Used only with the directory option.4. Click Start.


Administering the Convidx file toolThe system-level convidx command converts UniData index files from Motorola 68000 internalinteger format to Intel 386 internal integer format. Format information is embedded within the fileheader. This command automatically determines if files match the present machine integer format.If files do not need to be converted, UniData displays a message to that effect. The system-levelconvidx command converts UniData hashed data files from Motorola 68000 internal integer formatto Intel 386 internal integer format. Format information is embedded within the file header. Thiscommand automatically determines if files match the present machine integer format. If files do notneed to be converted, UniData displays a message that no data files were converted. You can runconvidx more than once on a UniData file.

Static index files have a prefix of X_. Dynamic index files are named idx001, idx002,.... See the UsingUniData manual for more information about working with index files and alternate key indexes.

Administering the Convmark file tool

107

1. Select File Tools → Convidx from the Admin Tasks pane.The Convidx pane opens, as shown:

2. Browse to the directory for the account you want to convert.3. Optional. Select the Convert sub-directories option if you want to process subdirectories

recursively. Used only with the directory option.4. Click Start.


Administering the Convmark file toolThe system-level convmark command searches for and converts ASCII values in UniData files. Thenew_value must be one that is not contained in the file to be converted.

Based on the option selected, UniData does one of the following:

▪ Displays the number of occurrences of a particular ASCII value.

▪ Counts the number of UniData delimiters in files.

▪ Converts a single ASCII character (ASCII values 128 - 255 only).

▪ Converts the UniData delimiters for your language group. (Be sure you have changed thelanguage group with the system-level command udtlangconfig. For instructions, see UniDataInternational.)

Convmark constraints

You cannot use the convmark command to convert in the following conditions:


108

▪ If your source file contains the new ASCII values the ones to which you are attempting to convertno data in the file is converted. UniData instead returns a message indicating that the data alreadycontains the new mark, and returns the cursor to the ECL prompt. This does not mean that the filehas been converted or that it does not require conversion. You must review and change the recordsmanually.

▪ On UniData for UNIX, directories indicated by path1, and so forth, cannot contain any UNIX links(created with the UNIX ln command). If they do, convmark produces an error message andaborts.

1. Select File Tools → convmark from the Admin Tasks pane.The convmark pane opens, as shown:

2. Browse to the directory for the account you want to convert.3. Enter the correct Language Group ID.

The language group ID is made up of the ASCII values that represent the record mark, the cursorcontrol escape sequence, and the null value for that language group:▪ 159/130/129 French, Japanese, and English

▪ 255/192/129 English

▪ 30/31/30 English, Simplified Chinese4. Enter the original value in the Old value field.

Used without new_value, Convmark counts the occurrences of new_value. Used with new_value,Convmark converts from old_value. Must be a single ASCII value from 128 through 255.

5. Enter the replacement value in the New value field.

The replacement value must be a single ASCII value from 128 through 255.

Note: If new_value already appears in the data, UniData does not execute the conversion.Instead, an informational message appears and the cursor returns to the environment fromwhich you executed convmark.

6. Click Start.The converted files are shown in the Result box.

Administering the Dumpgroup file tool

109

Administering the Dumpgroup file toolThe system-level dumpgroup command extracts readable records from a specified group in aUniData file. If the file was corrupted, dumpgroup unloads only the complete, valid records, leavingbehind any information it cannot read.

If you execute dumpgroup without specifying an output file, the output simply displays on thescreen. You will not be able to use that output to verify records or repair the damaged group. If youdo specify an output file, dumpgroup extracts readable records in uneditable form, suitable forreloading. dumpgroup also creates a directory in the /tmp directory on UniData for UNIX or the\TEMP directory on UniData for Windows platforms for each dumped group. The directory is namedFILE_GROUP, where FILE and GROUP are the file name and group number you specified. This directorycontains an ASCII file for each record, so that you can check them for consistency before reloading thedamaged file.

For more information about how to use dumpgroup to recover files, see Administering UniData.

1. Select File Tools → Dumpgroup from the Admin Tasks pane.The Dumpgroup pane opens, as shown:

2. Enter the following information:


File Name of the file that contains groups to be extracted.Group Number of the group to be dumped.Dump info file(-d) Directs output to outputfile.

Warning: Make sure outputfile is not the name of another item inyour account. If it is, UniData will overwrite it.

Tip: This file is the input file for the fixgroup command.Convert non-printable(-p) Converts nonprinting field markers to printable characters in

output file. Makes outputfile editable. This option is valid only with-d.


110


Administering the Filever file toolThe system-level filever command displays machine type(high-byte or low-byte) and file type(recoverable or non-recoverable).

1. Select File Tools → Filever from the Admin Tasks pane.The filever pane opens, as shown:

2. Browse to the directory for the file you want to view.3. Click Start.

The results are shown in the Result box.

Administering the Fixfile file toolThe system-level fixfile command displays machine type(high-byte or low-byte) and file type(recoverable or non-recoverable).

Administering the Fixfile file tool

111

1. Select File Tools → Fixfile from the Admin Tasks pane.The fixfile pane opens, as shown:

2. Select the account name from the Account dropdown menu.3. Select the file name you want to repair from the File options.4. Enter the damaged group number in the Group box.5. Enter the correct information in the Option fields, as described in the following table.


Output file(-d) For each readable record, UniData creates an ASCII file in adirectory in the current UniData account. UniData also takes thefollowing actions for static and dynamic files:

Static files – Stores readable records in (uneditable) outputfile.

Dynamic files – Stores readable records in (uneditable)outputfile and in a subdirectory in the /tmp directory namedfilename_groupno on UniData for UNIX, or in the \TEMP directoryon UniData for Windows platforms.

Note: To repair files, you must include both the -f parameter(to clear the group) and the -d parameter (to restore readablerecords).

Fix corruption(-f) Clears damaged groups. Must be combined with the -d or -tparameters.

Do not clear groups(-k) Does not clear records before reloading them, so that damagedrecords are retained in the file. Must be combined with the -d or -fparameters.

▪ To copy readable records to another file, include the -k and the-d parameters.

▪ To copy readable records to another file and return them to thefile, include the -k, -d, and -f options.


112


Convert non-printable(-p) Combine with the -d option to convert UniData delimiters andnonprinting characters in the ASCII files as follows:

▪ Attribute mark – New line

▪ Value mark – “}”

▪ Subvalue mark – “|”

▪ Text mark – “{“

▪ Nonprinting – “.”Display only(-t) Record key and the record length are reported for each readable

record. Directs output to the terminal only. All attributes in therecord are listed, indented by two spaces. In the display, UniDatadelimiters and nonprinting characters are represented as follows:

▪ Attribute mark – New line

▪ Value mark – “}”

▪ Subvalue mark – “|”

▪ Text mark – “{“ n Nonprinting – “.”

Note: The -t and -d options are mutually exclusive.Message file(-m) Writes error messages and statistics to messagefile instead of the

terminal.Working directory(-w) Specifies directory for storing work files.Input file(-i) The file containing names of files and groups to be repaired.

inputfile is produced by the guide command. If you do notdesignate inputfile with guide, fixfile reads damaged file andgroup names from GUIDE_FIXUP.DAT in the current directory. Thefollowing describes the format of GUIDE_FIXUP.DAT:

filenameMgroup_num...filenameNgroup_numgroup_numgroup_num

Note: -iinputfile and filename group are mutually exclusive.

6. Click Start.The results show in the Result box.

Administering the Guide file toolThe system-level guide command analyzes hashed files, generates statistics, and providessuggestions for optimizing file sizes and ensuring data integrity. UniData must be running when youexecute guide.

Administering the Guide file tool

113

1. Select File Tools → Guide from the Admin Tasks pane.The guide pane opens, as shown:

2. Select the file name you want to analyze from the File menu, or click Browse. Separate multiplefile names with a space. You must have read and write access to these files.

3. Enter the correct information in the Option fields, as described in the following table.


Brief summary(-b) Summarizes file analysis in b_filename. Default file name isGUIDE_BRIEF.LIS.

Stat level Reports on file size:

1 — Summarizes file size info.

2 — Default; reports file size info.

3 — Adds information about distribution of data sizes.

Note: Cannot be used with the -ns option.#small rec(-s) Adds to information displayed by -d. Displays, in quotation marks,

keys of smallest records. Key ends with * if truncated. countspecifies number to list. Default is 3.

-l — lists keys only

-s — sorts and lists keys

Note: Must be combined with the -d option.# large rec(-s) Adds to information displayed by -d. Displays, in quotation marks,

keys of largest records. Key ends with * if truncated. count specifiesnumber to list. Default is 3.

-l — lists keys only

-s — sorts and lists keys

Note: Must be combined with the -d option.


114


Output file(-o) Combines output in filename, rather than placing it in separatefiles. If filename is not specified, sends combined output to thestandard output device. The default output device is the displayterminal.

Advice file(-a) Default. Reports file management advice in a_filename. Default filename is GUIDE_ADVICE.LIS.

Error file(-e) Default. Reports statistical errors in e_filename. Default file nameis GUIDE_ERRORS.LIS.

Stats file(-s) Default. Reports detailed statistical information in s_filename.Default file name is GUIDE_STATS.LIS.

Fixup file(-f) Default. Reports damaged groups in f_filename. Defaultf_filename is GUIDE_FIXUP.DAT.

f_filename can be used as input for ECL commands fixfile,dumpgroup, and fixgroup.

Hash type(-h) Evaluates hash algorithms of type:

▪ a — evaluates all supported hash types

▪ 0

▪ 1

▪ 3

Note: This option produces no output for dynamic files.Modulo check(-m) Analyzes the effects a different modulo would have on filename.

Must be used with the -h parameter.Input file(-i) Analyzes all files listed in i_filename. Default file name is

GUIDE_INPUT.DAT. In i_filename, list one file name per line. Blanklines and lines beginning with! are ignored.

Report file(-r) Directs output to UniData database r_filename. r_filename must bethe system-level file name. Copy the dictionary for r_filename fromudthome/sys/D_UDT_GUIDE on UNIX or udthome\sys\D_UDTGUIDE on Windows platforms. Later, you can executeUniQuery commands against r_filename.

#Child processes(-Z) Defines the number of concurrent processes to use when analyzingthe file. The default is 4. If the file has less than 100 groups, guideonly uses one process.

Check char(-u) Searches files for the existence of the ASCII character you specify inthe records and keys in the file.

Saving File Load (-sfl) Updates the data file with the calculated fileload value. Applies todynamic WHOLEFILE split-style files only (UniData 8.x and higher).

4. Click Start.The results are shown in the Result box.

Administering the Memresize file toolThe system-level memresize command analyzes hashed files, generates statistics, and providessuggestions for optimizing file sizes and ensuring data integrity. UniData must be running when youexecute memresize.

Administering the Memresize file tool

115

1. Select File Tools → Memresize from the Admin Tasks pane.The Memresize pane opens, as shown:

2. Select the file name you want to analyze from the File menu, or click Browse. Separate multiplefile names with a space. You must have read and write access to these files.



File The name of the file to be resized.Modulo The new modulo number to be assigned to the file.Block factor The size, expressed as a multiplier, of each group in a hashed file. If you

specify a block size multiplier of 0, UniData creates 512-byte groups. Ablock size multiplier of 1 represents 1024 bytes, 2 represents 2048 bytes,and so on. For 32-bit files, the maximum block size multiplier is 16. Ifspecifying a larger value, 16 will be used. For 64-bit files, the block sizelimit is '2 GB - 1' (2,147,483,647).

Temp file path The path where UniData locates a working copy of the file duringresizing. The default is /tmp on UniData for UNIX or %UDTHOME%\UDxx\TEMP on UniData for Windows platforms. This parameter hasno effect if the resulting file is a dynamic file.

Hash type Hash type for the resized file.Size in kilobytes of memory buffer used for the operation. memresizemay perform faster with a larger memory allocation. The minimum sizeis 256K. The default on most systems is 8000K (8 MB). You can assignas much memory as is available on your system. For example, 12000assigns 12 MB of memory to the memresize command.

Restore Skip over file corruption that cannot be fixed, but continue resizingthe file. Use this parameter when a file must be restored regardless ofcorruption.

Static After resizing, the file is a static hashed file.Dynamic After resizing, the file is a dynamic hashed file.Whole File After resizing, the file is dynamic and the split/merge type is WHOLEFILE.

This is the default setting beginning at 8.1.0. The default split load is 75.

Note: This option is only available when Dynamic is selected.


116


Key and data After resizing, the file is dynamic and the split/merge type isKEYDATA. This is the default setting for 7.x or earlier.

Note: This option is only available when Dynamic is selected.Key only After resizing the file is dynamic and the split/merge type is KEYONLY

(the default).

Note: This option is only available when Dynamic is selected.Part file After resizing, file is a dynamic file. part_tbl is the path and file name of a

previously established part table. memresize copies part_tbl into thedynamic file directory. The copy of part_tbl in the dynamic file directoryserves as the “per-file” part table for the dynamic file.

Note: This option is supported on UniData for UNIX only.64-bit Sets the addressing type of the file to 64-bit mode. See details above for

32-bit vs 64-bit. This option is new at UniData 8.1.0.32-bit Sets the addressing type of the file to 32-bit mode. This is the default

addressing type. This option is new at UniData 8.1.0.

4. Click Start.The results show in the Result box.

Administering the Shfbuild file toolThe system-level shfbuild command is used to create a sequentially hashed file by convertingan existing dynamic or static file. UniData must be running when you execute shfbuild. Eachsequentially hashed file contains a static, read-only file that is called the gmekey file. This file is readinto memory when you open a sequentially hashed file. The gmekey file contains information aboutthe type of keys in the file (alphabetic or numeric), and controls which group a record is hashed towhen it is written.

1. Select File Tools → Shfbuild from the Admin Tasks pane.The Shfbuild pane opens, as shown:

2. Select the file name you want to work with from the File menu, or click Browse. Separatemultiple file names with a space. You must have read and write access to these files.

Administering the Udfile file tool

117



Append only(-a) Only rebuild the last group of the sequentially hashed file. UniDatasplits the last group into groups according to the records in the group.If you use this option, the outfile should be the name of the sequentiallyhashed file. Do not specify infile.

Key file only(-k) Build the gmekey file only. If you use this option, outfile should bethe name of the sequentially hashed file. Do not specify infile. UniDatarebuilds the gmekey file according to the keys in each group of outfile.

Numeric(-n)/Alphabetic(-t)

Force the outfile to be in numeric or alphabetic order. By default, theorder of outfile is determined by the infile primary key type. If infile is asequentially hashed file, UniData uses the same order in outfile. If infileis not a sequentially hashed file, the order of outfile is determined bythe justification of the @ID of the infile dictionary record. If it is rightjustified, it is numeric. Otherwise, it is alphabetic.

If you use the -a or the -k option, these options have no effect.Modulo(-m) Specifies the new modulo of outfile.Empty percent(-e) Empty percent. This percent is a number between 0 - 99 which indicates

how much space in the rebuilt groups to reserve. UniData calculates thenew modulo of the file from empty_percent and the number of recordsin the rebuilt groups. If you do not specify -e or -m, UniData rebuilds thesequentially hashed file according to the default empty percent of 20.

Block sizemultiplier(-b)

Specifies the block size of the sequentially hashed file in kilobytes.

Input file(-) Load the contents from infile instead of outfile. infile can be any type ofUniData file.


Administering the Udfile file toolThe system-level udfile command converts a UniData file to or from recoverable state.


118

1. Select File Tools → Udfile from the Admin Tasks pane.The udfile pane opens, as shown:

2. Select the file name you want to convert from the File menu, or click Browse. Separate multiplefile names with a space. You must have read and write access to these files.

3. Select one of the following options:▪ Change to a recoverable file

▪ Change to a non-recoverable file

▪ Display current file status4. Click Start.


119

Chapter 16: Monitoring system activity inUniVerse

One of the more important jobs of the system administrator is to monitor activity on the system(such as disk use and CPU use) and to deal with bottlenecks and other potential problems beforethey impact users. This section describes ways to find out who is doing what in UniVerse and at theoperating system level.

Listing active UniVerse processes and jobsTo view UniVerse processes, choose Users from the Admin Tasks view in the U2 ExtensibleAdministration Tool. The Users window appears, as shown in the following example:

This window contains a snapshot of the user and background processes at the time the window wasinvoked. To view the current user and background processes, click Refresh.

From this window you can also:

▪ Send a message to users

▪ Terminate a process

The User Administration window is divided into two main areas:

▪ Interactive Users

▪ Background Processes

This window also has the following options:

▪ Close. Exits the window.

▪ Refresh. Displays the current user and background processes.

Chapter 16: Monitoring system activity in UniVerse

120

▪ Message. Displays the Send Message dialog box.

▪ Logout. Logs out a selected user or background process.

Interactive users

The following information appears for each user process:


Pid The process ID.User Name The user’s login name.User # The user’s UniVerse user number.Port Name The user type and UniVerse user number, for example,

console:124.Last Logged In The date and time the user logged on.Last Command The last command the user issued (if known).

Background processes

The following information appears for each background process:


Pid The process ID.User Name The user’s login name.User # The user’s UniVerse user number.Printer Segment The address of the printer shared memory segment.Last Command The last command issued (if known).

Listing UniVerse jobs with PORT.STATUSThe UniVerse PORT.STATUS command is a diagnostic tool that lists currently active UniVerse jobs onthe system. The syntax is as follows:

PORT.STATUS [ USER name ] [ PORT number ] [ DEVICE pathname ] [ PIDprocess# ] [ FILEMAP ] [ LAYER.STACK ] [ MFILE.HIST ] [ LOCK.HIST ][ { ENABLE | DISABLE } LOCK.HIST ] [ ODBC.CONNECTIONS ] [ LPTR ]

The PORT.STATUS command with no options produces a report that looks like this:

For complete details about PORT.STATUS, see the UniVerse User Reference.

Terminating a processYou can terminate a user or background process using the U2 Extensible Administration Tool.

To terminate a user process

121

To terminate a user process

1. Choose Users from the Admin Tasks view in the U2 Extensible Administration Tool.The Users dialog box appears.

2. Choose the user from the Interactive Users list.3. Click Logout.

A message box appears.4. Click Yes. An attempt is made to log the user off the server.

The Users dialog box is updated.

To terminate a background process

1. Choose Users from the Admin Tasks view in the U2 Extensible Administration Tool.The Users dialog box appears.

2. Choose the process from the Background Processes list.3. Click Logout Background Process.

A message box appears.4. Click Yes.

The chosen process is immediately terminated and the U2 Extensible Administration Tool isupdated.

122

Chapter 17: Monitoring system activity inUniData

One of the more important jobs of the system administrator is to monitor activity on the system(such as disk use and CPU use) and to deal with bottlenecks and other potential problems beforethey impact users. This section describes ways to find out who is doing what in UniData and at theoperating system level.

Listing active UniData processes and jobsTo view UniData processes, choose Users from the Admin Tasks view in the U2 ExtensibleAdministration Tool. The Users window appears, as shown in the following example:

This window contains a snapshot of the user and background processes at the time the window wasinvoked. To view the current user and background processes, click Refresh.

Optional. Click Kill to terminiate a UniData session.

U2 Extensible Administration December 2015 DBT-DEC2015-XA ... · U2 Extensible Administration Tool User Guide Version Dec2015 December 2015 DBT-DEC2015-XA-AM-01

Documents