BluePhoenix AppBuilder 2.1.

Workgroup Repository Administration Guide

BluePhoenix BluePhoenix AppBuilder 2.1.0 Workgroup Repository Administration Guide April, 2003 Corporate Headquarters BluePhoenix Solutions Vlierwerf 7B 4704 SB Roosendaal The Netherlands +31 (0) 165 399 401 +31 (0) 165 396 308 fax USA Headquarters BluePhoenix Solutions USA, Inc. 8000 Regency Parkway Cary, NC 27511 United States +1 919.380.5100 +1 919.380.5111 fax www.bluephoenixsolutions.com

1992-2003 BluePhoenix Solutions All rights reserved. BluePhoenix is a trademark of BluePhoenix Solutions. All other product and company names mentioned herein are for identification purposes only and are the property of, and may be trademarks of, their respective owners. Portions of this product may be covered by U.S. Patent Numbers 5,495,222 and 5,495,610 and various other non-U.S. patents. The software supplied with this document is the property of BluePhoenix Solutions, and is furnished under a license agreement. Neither the software nor this document may be copied or transferred by any means, electronic or mechanical, except as provided in the licensing agreement. BluePhoenix Solutions has made every effort to ensure that the information contained in this document is accurate; however, there are no representations or warranties regarding this information, including warranties of merchantability or fitness for a particular purpose. BluePhoenix Solutions assumes no responsibility for errors or omissions that may occur in this document. The information in this document is subject to change without prior notice and does not represent a commitment by BluePhoenix Solutions or its representatives.

TABLE OF CONTENTS

Table of Contents

AppBuilder 2.1.0 Workgroup Repository Administration Guide

1 Workgroup Repository Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-1

AppBuilder Repository Family . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-1 AppBuilder Repository Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-2 Workgroup Repository Functionality . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-2 Repository Administration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-3 Development Security Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-3 Planning for Workgroup Repositories. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-4 Using Workgroup Repositories in a Hierarchy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-5 Using the Import/Export Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-6 Understanding Repository Configurations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-7 Network Configurations and Protocols . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-7 Using Freeway Explorer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-8 Connecting to the Workgroup Repository . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-9 Using the Freeway Client Configuration Option . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-9 Using Freeway Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-11

2 Using Freeway Explorer and the Object Browser

. . . . . . . . . . . . . . . . . . . . 2-1

Starting Freeway Explorer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-1 Viewing and Modifying Session Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-3 Querying and Loading Object Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-5 Using the Object Browser Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-8 Object Browser Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-8 Object Browser Menus. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-8 Object Browser Toolbar. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-10 Viewing and Editing Object Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-10 Viewing Child Entities and Relationships . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-12 Viewing Parent Entities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-12 Committing Sessions Changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-13

3 Locking Repository Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-1

Understanding Lock Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-1 Exclusive Lock . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-1 Shared Lock . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-2

AppBuilder 2.1.0 Workgroup Repository Administration Guide

iii

Cascading Lock . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-3 Displaying Locking Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-3 Checking Lock Status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-4 Checking Lock Status in the Audit Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-5 Viewing the Parent/Child Relationship of an Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-6 Broadcasting Updates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-7

4 Managing Repository Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-1

Understanding the Security Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-1 Setting Scope and Permissions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-3 Creating Projects, Groups, Users, and Super Users . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-5 Creating a Project. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-6 Creating a Group . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-6 Creating a User. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-7 Assigning a Super User . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-8 Viewing Group Members and User Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-9 Changing Group Access to Objects in a Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-10 Using Relationship Properties to Set Group Security. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-11 Managing Multiple Permissions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-12 Allowing Groups Access to Multiple Projects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-12 Setting Global User Access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-12 Creating Subgroups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-13 Using Default Security Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-14 Defining Native Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-15 Using Default Projects and Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-15 Understanding Default Permission Levels. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-15 Modifying the Default Repository User ID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-16 Setting System Administrator Permissions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-16 Configuring Native Security for the SQL Server. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-17 Optimizing Repository Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-18

5 Moving Data Between Repositories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-1

Migration Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-1 Understanding Migration Phases. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-2 Performing a Migration Export . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-3 Understanding the Migration Export Toolbar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-3 Using the Migration Export Tool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-3 Creating a Migration Object - Load Phase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-6 Using the Migration Export Action Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-7 Setting Export Migration Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-8 Creating Migration Entities - Export Phase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-10 Setting the Migration Object Scope . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-11 Performing a Migration Import . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-14 Migration Import Toolbar and Icons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-14 Importing a Migration Object - Analyze Phase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-15 Using the Analyze w/Merge Option . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-17

iv

AppBuilder 2.1.0 Workgroup Repository Administration Guide

Performing Migrations - Import Phase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-18 Using a Selective Import . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-19 Choosing Object Import Actions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-19 Importing Migration Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-21 Performing a Direct Import . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-22 Using Migration Results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-23 Sample LOG File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-24 Migrating Between Workgroup and Enterprise Repositories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-24 Renaming PC Migration Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-25 Understanding Mainframe Migration and Repository Security . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-25 Using Application Folder to Migrate Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-26 Exporting Application Folder Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-26 Configuring the Application Folder Export. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-28 Creating a Target Destination . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-29 Importing Application Folder Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-30 Performing an Application Folder Migration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-31 Importing and Exporting Using CDIF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-31

6 Administering Repositories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-1

Using the Archive and Restore Utilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-1 Archiving Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-2 Restoring Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-4 Performing a Rollback. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-6 Using the Import/Export Utility. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-7 Importing and Exporting Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-7 Using the Import Utility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-8 Using the Export Utility. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-9 Maintaining a Repository . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-11 Performing Repository Maintenance for Oracle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-11

A Performance Tuning . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .A-1

Improving SQL Server Response for Workgroup. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .A-1 Using Temporary Database (tempDB) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .A-2 Increasing Memory Allocation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .A-2 Setting Number of User Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .A-3 Changing Windows Process Priority . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .A-3 Clearing Transaction Logs (SYSLOGS) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .A-4 Tuning Performance for Oracle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .A-5 Tuning Disk Storage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .A-5 Optimizing Oracle Instance Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .A-5 Reindexing and Packing a Repository . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .A-8 Reindexing a Repository . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .A-8 Packing a Repository . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .A-8 Understanding Date Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .A-9 Using Repository Dates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .A-9 Migrating Data between Dates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .A-9

Table of Contents

Adding Applications to Freeway Explorer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-9 Adding a Function Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-10 Deleting a Function Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-11 Creating Add-in DLLs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-11 Additional Information. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-13 DLL Add-in Samples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-13

B CDIF Format and Samples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-1

CDIF Layout. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-1 Sample CDIF Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-2

C Using Freeway Manager and Utilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . C-1

Using Freeway Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . C-1 The Freeway Manager Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . C-2 Server Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . C-3 Repository Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . C-4 Options Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . C-4 Window Menu Items. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . C-5 Help Menu Items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . C-5 Workgroup Repository Browser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . C-6 Workgroup and Local Server Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . C-6 The Workgroup Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . C-8 Workgroup Status Utility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . C-8 Sample Status Output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . C-8 Workgroup User List Utility. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . C-9 Sample User List Output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .C-10 Workgroup Status Report . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . C-10 Performing a Manual Rollback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . C-10 Broadcasting Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . C-11

Index. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

vi

AppBuilder 2.1.0 Workgroup Repository Administration Guide

CHAPTER

1
Note

WORKGROUP REPOSITORY OVERVIEW

AppBuilder 2.1.0 Workgroup Repository Administration Guide

The AppBuilder Workgroup repository and its management tools allow concurrent, object-based application development. This guide provides information about workgroup repositories and how best to use and administer them in your development environment.
A Workgroup repository is also referred to as a Freeway repository. The terms are interchangeable.

In order to manage large-scale development and maintenance involving large groups of developers working simultaneously, AppBuilder uses repository technology as the central store of information about the application. The following topics will help you to understand the Workgroup repository: AppBuilder Repository Family Workgroup Repository Functionality Repository Administration Planning for Workgroup Repositories Understanding Repository Configurations Using Freeway Explorer Using Freeway Manager Refer to the Product Concepts Guide for an overview of AppBuilder and repository benefits and features. For mainframe repository information, refer to the Enterprise Administration Guide.

AppBuilder Repository Family

The AppBuilder Repository provides a tool to administer and manage a software development environment from a centrally-located database residing on a server. Using the repository, complex client/server and cooperative processing applications can be developed in a controlled and efficient workspace. The repository holds software application objects, the methods, and the facilities used to access the objects. These methods and facilities are accessed using AppBuilder tools that reside on a client machine.

AppBuilder 2.1.0 Workgroup Repository Administration Guide

1-1

Workgroup Repository Functionality

AppBuilder Repository Types

A repository is a type of relational database containing all the application components, objects, and business logic, including configuration settings, relationships, and metadata used within a development environment. There are three types of repositories available in AppBuilder:
Table 1-1 AppBuilder Repository Types

Workgroup Repository

A controlled, secure development environment for client/server environments with the repository accessible on a network server from remote workstations. Repository functionality on a client workstation that is configured to be easily uploaded and merged with a larger development effort. A mainframe repository for enterprise application development teams. The mainframe is designated as the central archive and site for the team to conduct application development.

Personal Repository Enterprise Repository

Workgroup Repository Functionality

The AppBuilder Workgroup repository provides a LAN-based tool to administer and manage a software design and development environment from a centrally-located database residing on a server. Using the Workgroup repository, complex client/server and cooperative processing applications can be developed in a controlled and efficient workspace. AppBuilder provides the repository technology to support: A flexible, scalable architecture An object-oriented information model Data migration between repositories Conference-based notification Windows 2000 platform support Platform, protocol, and database-independent configurations of Workgroup installations Industry-standard APIs International language support National language support (NLS), Multiple Language Support (MLS), and double-byte character support (DBCS) The example in Figure 1-1 shows three client workstations communicating across a network using a TCP/IP communications protocol to connect to a network server that contains the Workgroup repository configured for an Oracle database connection. See Chapter 6, Administering Repositories for detailed information on managing repositories.

Note

Do not install a Workgroup and personal repository on the same machine. If a personal repository is installed and a Workgroup is installed on the same machine, the Workgroup overwrites the files directory and all the personal repository files are lost.

1-2

Workgroup Repository Overview

Repository Administration

Figure 1-1

Client Machines Accessing the Repository

Repository Administration
Using AppBuilder, the Workgroup Administrator maintains control on all the components in the AppBuilder repository. Security controls limit who can modify objects and to what degree they can be modified. The Workgroup Administrator assigns userIDs and passwords with specific permissions assigned to each user accessing the repository. The security model is based on a simple series of permissions. The user is associated with at least one user group. The group is associated with another group, or with one or more projects, and so on. The scalability and flexibility of the repository allow a large or growing number of users to have limited or full access to groups and projects, read-only access, the ability to create, relate to, update, or delete objects, or a combination of all these and other security parameters.

Development Security Model

AppBuilder repository software enables a Workgroup Administrator to implement security restrictions that control access to objects in the repository. Security is implemented using the Workgroup repository security model stored within the repository. The model consists of users, groups, projects, and the permissions and scope of objects available to Groups. Figure 1-2 illustrates the various security restrictions that can be used to manage a repository development environment.

AppBuilder 2.1.0 Workgroup Repository Administration Guide

1-3

Planning for Workgroup Repositories

Figure 1-2

Workgroup Repository Security Model

In Figure 1-2 are three sample scenarios. The Workgroup Administrator has set up membership for Users 1 through 6 into Groups A, B, and C. Users 1 and 2 are associated with Group A. Users 3 and 4 are associated with Group B. User 4 is associated with Groups B and C. Users 5 and 6 are associated with Group C. Group A has access to Project W and the Group A objects within Project X. Group B has access to Projects X and Y, including the Group A objects within Project X. Object type scope and access authority can further be refined to permit specific types of actions by the Groups, including which objects can be modified and how they can be modified. Permissions for create, relate, update, and delete actions can be defined for users, groups, and projects.

Planning for Workgroup Repositories

Using AppBuilder, you can set up unique Workgroup repositories to accommodate different environments. For example, you might configure different environments for: Application development System and integration testing Developer training User acceptance Platform-specific objects, such as Java or COBOL Protocol variations When planning the number of Workgroup repositories for your enterprise, consider the following: The application development lifecycle The amount and type of development activity Other project needs, such as the amount of user demand for particular objects Because each environment requires systems support, maintenance, and machine resources, plan carefully for the number of group repositories you need. See Understanding Repository Configurations for sample configurations.

1-4

Workgroup Repository Overview

Planning for Workgroup Repositories

Using Workgroup Repositories in a Hierarchy

AppBuilder uses Workgroup repository technology to manage simple or complex application development environments. For growing or large workspaces, using multiple Workgroup repositories associated in a hierarchical structure can dramatically boost performance and increase efficiency. In a two-tier repository hierarchy, Workgroup repositories are connected to a central repository. In three-tier hierarchies, multiple Workgroup repositories with a large number of repository users subdivided into development areas, are connected to staging repositories where data from their subgroups is integrated before being migrated to the central repository. A non-hierarchical structure, unlike the two-or three-tier hierarchies, supplies a flat hierarchy. The following sections describe how you can use these hierarchy structures in configuring Workgroup repositories: Using Workgroup Repositories in a Two-Tier Hierarchy Using Workgroup Repositories in a Three-Tier Hierarchy Using Workgroup Repositories in a Non-hierarchical Structure Using the Import/Export Function

Using Workgroup Repositories in a Two-Tier Hierarchy

Figure 1-3 shows a two-tier repository hierarchy in which multiple Workgroup repositories are used with a central repository.
Figure 1-3 Two-tier Repository Hierarchy

In Figure 1-3, Group 1 and Group 2 maintain separate Workgroup repositories for their projects and both groups can migrate their data to a central repository that contains integrated data. This central repository can be another Workgroup repository or a repository on a mainframe. Groups 1 and 2 share each others repository objects by migrating a subset of the data from the central repository to their respective Workgroup repositories.

Using Workgroup Repositories in a Three-Tier Hierarchy

In environments where you have a large number of repository users subdivided into major development areas, consider using a three-tier repository hierarchy. Figure 1-4 shows an example of a three-tier repository hierarchy.

AppBuilder 2.1.0 Workgroup Repository Administration Guide

1-5

Planning for Workgroup Repositories

Figure 1-4

Three-tier Repository Hierarchy

In this example, multiple Workgroup repositories defined to Groups 1 through 6 are connected to staging Workgroup repositories where data from their Groups can be integrated prior to being migrated and integrated in the central repository.

Note

It is a good practice to have your Workgroup repository in the same domain as the workstations that are connecting to that repository. If while connecting to the repository, an error message is received stating Problem Opening Client Pipe, check that you have access to the machine on which the Workgroup repository is located. This message may appear if the client machine and Workgroup machine are not in the same domain. This is part of Microsoft security and not AppBuilder functionality. If the machines are located in different network domains, you may have to set up a trust relationship between the domains or the user may have to login to the Workgroup machine (by way of Windows Explorer) before attempting the Workgroup connection. For more information, see Configuring Native Security for the SQL Server.

Using Workgroup Repositories in a Non-hierarchical Structure

Figure 1-5 shows multiple Workgroup repositories in a non-hierarchical structure.
Figure 1-5 Non-hierarchical Repositories

Unlike the two or three-tier hierarchies, there is no hierarchy to control the overall integration of repository data. Instead, each group exports migration data that the other groups import as needed.

Using the Import/Export Function

A single repositorys contents can be compressed into an export file using the Freeway Manager > Repository > Import/Export menu selection. You can then import the exported repository to multiple

1-6

Workgroup Repository Overview

Understanding Repository Configurations

environments, including the same server. You can also use this feature to backup your current repository or to import a previously-exported repository.

Warning

This approach allows only one environments repository to be available at one time. It is not recommended for normal application development, but may be suitable for a training, demonstration, or other limited use environment.

Understanding Repository Configurations

AppBuilder repository management software can be installed and configured to run on numerous platforms, as shown in Figure 1-6.

Warning

Do not install a Freeway and Personal repository on the same machine. If Personal repositories are installed and then a Freeway is installed, all Personal repository files in the directory are written over by the Freeway repository files. Supported AppBuilder Platforms

Figure 1-6

Network Configurations and Protocols

AppBuilder supports different types of network configurations and protocols. While there are many possible configurations, two common ones are: Single Repository with Multiple Clients The basic configuration in a distributed environment includes one or more client machines communicating with at least one server machine, as shown in Figure 1-7.
Figure 1-7 Single Workgroup Repository with Multiple Clients

AppBuilder 2.1.0 Workgroup Repository Administration Guide

1-7

Using Freeway Explorer

Multiple Workgroup Repositories on Multiple Servers Development projects occurring simultaneously, for example, Development and Training, can be maintained in separate repositories on separate servers. Clients with access to each server have access to the respective repositories, as shown in Figure 1-8.
Figure 1-8 Multiple Workgroup Repositories with Multiple Clients

Using Freeway Explorer

Freeway Explorer provides the user interface for you to view and modify objects within Workgroup repositories. Menu items for each function available in the Workgroup windows are explained in detail throughout this guide. Figure 1-9 shows the Freeway Explorer window menu and toolbar. Connecting to the Workgroup Repository describes the actions available in the Session menu.
Figure 1-9 Freeway Explorer Menu

Objects that have been located in the repository and loaded into Explorer can be modified using actions available in the Object Browser window. Figure 1-10 shows the Object Browser menu and toolbar.
Figure 1-10 Object Browser Menu

When starting an Explorer session, you use the main menu (Figure 1-11) to select which repository to connect to, create a new repository session, add modified objects created during a session to the repository, or revert the session, using the actions described in Connecting to the Workgroup Repository.

1-8

Workgroup Repository Overview

Using Freeway Explorer

Figure 1-11

Session Menu

Connecting to the Workgroup Repository

The Workgroup repository connection menu contains the action options listed in Table 1-2.
Table 1-2 Actions Actions Available in a Workgroup Repository Session Description Parameters Connection Alias - The name assigned by the developer to differentiate between different Workgroup repositories; typically the server name. Connect via - The protocol used during development to access the Workgroup repository from the client Server Name - The network name of the server on which the Workgroup repository resides, This must be consistent with the communications protocol Service Name - The name of the service request used to connect to the Workgroup using NetEssential. If not using NetEssential, the field is pre-filled with default. Connect Used to log into a Workgroup after a connection alias is created Closes a connection to the Workgroup server Saves all changes made during the session to the repository Reverses the session to the previous state Removes the connection alias Valid security permissions Valid user ID and password

New

Creates a new association to a Workgroup repository

Disconnect Commit Session Rollback Session Delete

Using the Freeway Client Configuration Option

Using Freeway Client Configuration, you can choose either the New or Delete action to create or delete a connection alias. This procedure permits you to create a connection alias to Workgroup repositories only. To create a connection alias to a Personal Repository, you must use Personal Repository Manager.

AppBuilder 2.1.0 Workgroup Repository Administration Guide

1-9

Using Freeway Explorer

To use Freeway Client Configuration: 1. Select Start > Programs > AppBuilder > Repository > Freeway Client Configuration. The Freeway Client Configuration window opens (Figure 1-12).
Freeway Client Configuration Window

Figure 1-12

2. 3.

Select an existing alias from the list and click Delete to delete the connection alias. Click New to create a new connection alias, the New Freeway Alias dialog opens (Figure 1-13).
Freeway Alias Dialog

Figure 1-13

4. 5.

Select the Workgroup server options that match your configuration. Name the new connection alias and click OK (Figure 1-14).
When configuring a Unix Workgroup repository, it is important that an Eventing Parent is set using the Communications Setup. Without a properly working Eventing Parent, Unix broadcasts may not work properly causing repository objects not to be updated correctly. Refer to the Configuring Communications Guide for more information on Selecting an Eventing Parent.

Note

1-10

Workgroup Repository Overview

Using Freeway Manager

Figure 1-14

Freeway Alias Window

After creating a connection alias, the following security information is required to connect to a Workgroup repository: user ID - the assigned user name for the repository password - the password as determined by native security

Using Freeway Manager

The Freeway Manager application interface allows the Workgroup Administrator to access and administer the Workgroup repository from the machine where the repository resides. Using Freeway Manager, the Administrator maintains control of software versions, modifications, releases, databases, and libraries, keeping the development environment stable and secure. Objects can be shared by groups, projects, and users, but the source object is only modifiable by the owner. The Administrator also assigns locking attributes for objects in the repository. Freeway Manager allows you to: Browse the network for Workgroup repositories Start and stop Workgroup repositories Broadcast messages Import, export, archive and restore repositories Pack and re-index repository databases

AppBuilder 2.1.0 Workgroup Repository Administration Guide

1-11

Using Freeway Manager

1-12

Workgroup Repository Overview

CHAPTER

USING FREEWAY EXPLORER AND THE OBJECT BROWSER

AppBuilder 2.1.0 Workgroup Repository Administration Guide

You use Freeway Explorer to view repository entities, owners, relationships, and status. Using the Explorer and Browser windows, you gain access to Workgroup repository objects, view the entire hierarchy in the repository, and load objects into the Explorer window to perform modifications to the properties and relationships of repository objects. The information in this section provides information on the Freeway Explorer interface and the Object Browser window. Topics include: Starting Freeway Explorer Using the Object Browser Window Viewing and Editing Object Properties Viewing Child Entities and Relationships Viewing Parent Entities Committing Sessions Changes

Starting Freeway Explorer

1. Choose Start > Programs > AppBuilder> Repository > Freeway Explorer from the desktop menu on your workstation, as shown in Figure 2-1.
Freeway Explorer Start Menu

Figure 2-1

2.

The Freeway Explorer window opens (Figure 2-2).

AppBuilder 2.1.0 Workgroup Repository Administration Guide

2-1

Starting Freeway Explorer

Figure 2-2

Explorer Start Window

3.

Select Session > New to create a new session, or Session > Connect to open a previously created session (Figure 2-3).
Session Action Menu

Figure 2-3

4.

To create a new session, type in the connection alias, connection protocol, and Workgroup server information in the New Freeway Group Server Connection Alias window (Figure 2-4). Refer to Using Freeway Explorer on page 1-8 for descriptions of the required information for the fields. Click Create.
When configuring a Unix Workgroup repository, it is important that an Eventing Parent is set using the Communications Setup. Without a properly working Eventing Parent, Unix broadcasts may not work properly causing repository objects not to be updated correctly. Refer to the Configuring Communications Guide for more information on Selecting an Eventing Parent.

1.

Note

2-2

Using Freeway Explorer and the Object Browser

Starting Freeway Explorer

Figure 2-4

Creating a New Session

5.

To open an existing session, select Connect. The Connect to Freeway Group or Personal Repository dialog opens (Figure 2-5).
Connecting to the Workgroup Repository

Figure 2-5

Note
6.

The Personal Repository is a local repository that is not available to network users. For more information about Personal Repository, refer to the Personal Repository Administration Guide.

Select the session name from the drag-down list, type in the user name and password, and click Connect. The Connecting...please wait. message displays while the repository is accessed. Click on Edit to open the Server Connection Alias window and modify the settings (Figure 2-4).

7.

The Session window opens and the status bar in the window displays the message:

Access objects within the repository using the Query or Keyword search mechanisms. (See Querying and Loading Object Types.)

Viewing and Modifying Session Properties

1. To view and change the properties of the current session, select Session > Properties (Figure 2-6).

AppBuilder 2.1.0 Workgroup Repository Administration Guide

2-3

Starting Freeway Explorer

Figure 2-6

Session Properties Menu Item

2.

The Session Properties window opens (Figure 2-7). Security and workspace information about the Session is displayed. You can change the project you are working within by choosing Select and selecting a project name from the drag-down list.
Session Properties Window

Figure 2-7

3.

The window opens that lists the active project and all available projects to choose from. Choose the project you want to work in and click Select (Figure 2-8).
Project Selection Window

Figure 2-8

2-4

Using Freeway Explorer and the Object Browser

Starting Freeway Explorer

4.

If you have not disconnected from the current project, a dialog prompts you to do so before you can connect to a new project (Figure 2-9). Select Session > Disconnect from the Freeway Explorer window.
Change Active Project Error Window

Figure 2-9

5. 6.

Select Session > Connect to reestablish your repository connection. Select Session > Properties to confirm that the new project is the currently active project. Click Close.

Querying and Loading Object Types

When the repository is accessed, you can locate and load existing objects within it using the Query options. For information on creating objects, refer to the Developing Applications Guide. 1. Select Objects > Query (Figure 2-10). The Object Query window opens (Figure 2-11).
Querying for Objects

Figure 2-10

2.

In the Find tab of the window, select an object type from the drag-down menu. To include only objects of that type beginning with a particular letter or number, type in the letter or number in the Query value field. Click Query. To see a list of all the object instances of that type, simply click Query with no entry in the value field.
The Object Query Window

Figure 2-11

AppBuilder 2.1.0 Workgroup Repository Administration Guide

2-5

Starting Freeway Explorer

Note

The Keyword tab provides an optional method to search for objects using a keyword. Keywords are assigned to objects by selecting an object in the object browser and choosing Selected > Properties. The Keywords tab contains a field to type in a keyword. Remember to commit changes to the repository. For detailed instructions, see Using the Keywords Search Wizard.

3.

Select the object instances you want to add to your sessions and click Load. The objects are added to your Freeway Explorer window session, as shown in Figure 2-12.
Objects Added to Session

Figure 2-12

Using the Keywords Search Wizard

1. The Keyword tab provides an optional method to search for objects using a keyword. The Keywords tab opens the Keywords Search Wizard (Figure 2-13) that searches for entities based on keywords that have been assigned to objects. A list is provided that allows you to select and move several object types into a subgroup to search through.
Keyword Search Wizard

Figure 2-13

2.

Select the object types you are searching for and add them to the Selected Types list (Figure 2-14). Click Next.

2-6

Using Freeway Explorer and the Object Browser

Starting Freeway Explorer

Figure 2-14

Selected Object Types List

3.

A window opens that allows you to enter the keyword to search for (Figure 2-15). Click Find.
Keyword Search Wizard

Figure 2-15

4.

The search wizard locates objects of the types listed with the keyword and returns the result (Figure 2-16).
Keyword Search Results Window

Figure 2-16

5.

Select the keyword and add it to the Keywords Selected list by clicking Add. Click Finish. The result of the search is displayed in the Keywords window (Figure 2-17).
Keyword Window

Figure 2-17

6.

Click Load to add the object to your Freeway session.

AppBuilder 2.1.0 Workgroup Repository Administration Guide

2-7

Using the Object Browser Window

Using the Object Browser Window

Use the Object Browser located in Freeway Explorer to browse the objects in a repository. When you have successfully loaded objects into the Freeway Explorer session, select an object and choose Open Browser to see the object hierarchy. Each element in the object can then be accessed and modified. The Object Browser window panes are described in Figure 2-18.
Figure 2-18 Object Browser Window

Menu

Toolbar

Hierarchy pane

Detail pane

Object Browser Window

The hierarchy pane in the left area of the window (Figure 2-18) displays the hierarchy associated with the object. If an object has a plus sign (+) in front of it, there are child objects associated with it. The detail pane on the right displays any child objects for the selected object. Some properties of the child objects are displayed: System ID the unique identifier (HPSID) of this object in the repository Type the object type Owner the owner or creator of this object Project the project in which this object was created

Object Browser Menus

The drag-down menus located at the top of the Freeway Explorer windows allow you to navigate and control the tasks of the application and view the hierarchy and properties of objects in the repository. Many of these functions are also available using the buttons in the Object Browser Toolbar. They include: File Menu Selected Menu Options Menu Print Menu Item

2-8

Using Freeway Explorer and the Object Browser

Using the Object Browser Window

File Menu
The File menu lets you return to the Freeway Explorer window or exit the application.
Figure 2-19 File Menu

Selected Menu
The Selected menu allows you to select the object or objects to view. Open Browser... - Opens another browser window of the selected object Explode upward... - Opens another browser window of the parent of the selected object Properties... - Opens the Properties dialog of the selected object Relationship properties... - Opens the Properties dialog of the selected relationship
Figure 2-20 Selected Menu

Options Menu
The Options menu lets you determine whether you want the browser to view the entities or the relationships of the objects in the browser window.
Figure 2-21 Options Menu

Print Menu Item

The Print menu item opens the Print dialog for printing the information about the selected object

AppBuilder 2.1.0 Workgroup Repository Administration Guide

2-9

Viewing and Editing Object Properties

Object Browser Toolbar

The Browser toolbar, shown in Figure 2-22, provides a shortcut to performing the tasks in the Browser. Many of these functions are also available from selections in the Object Browser Menus.
Figure 2-22 Browser Toolbar Up (Ctrl+U) Properties Print Report

Freeway Explorer

Open Browser (Ctrl+B)

Entities

Relationships

Viewing and Editing Object Properties

You can use the Object Browser to view and edit the properties and relationships of objects in your repository by following the procedures described here. Procedures - Using the Object Browser Viewing and Editing Entity Properties 1. 2. 3. Select the object in the hierarchy. Choose Selected > Properties. The Properties dialog (Figure 2-23) for that object appears. Edit the information by typing in the new values and click OK. Fields with white backgrounds are available for editing. Clicking Apply allows you to continue to edit fields before committing to the changes. Clicking Undo reverts changes.
Figure 2-23 Browser Object Properties Window

Procedure - Viewing and Editing Relationships To view or edit the properties of a relationship in the Object Browser: 1. 2. In the hierarchy, select the child object in the relationship. Choose Selected > Relationship properties or press Alt+R.

2-10

Using Freeway Explorer and the Object Browser

Viewing and Editing Object Properties

3.

The Properties dialog for that relationship appears (Figure 2-24). To edit the information, type in the new values and click Apply or OK.
If permissions to modify properties for that object are required, a message appears in the status bar.

Note

Figure 2-24

Browser Relationship Properties Window

Procedure - Using Options to View Relationships You can also view or edit the properties of a relationship using these steps: 1. In the Browser window, choose Options > View Relationships. The relationships are displayed in the detail pane designated with an arrow (->) in the entry (Figure 2-25).
Browser Relationships Example

Figure 2-25

2. 3. 4.

In the detail pane, select the relationship you want to edit. Choose Selected > Properties. The Properties dialog for that relationship appears (Figure 2-24). Type in the new values and click OK.

AppBuilder 2.1.0 Workgroup Repository Administration Guide

2-11

Viewing Child Entities and Relationships

Viewing Child Entities and Relationships

You can use the Object Browser to view the child entities in your repository. Procedures - Viewing Child Entities and Relationships Viewing Child Entities If an object has a plus sign in front of it in the hierarchy, it indicates that there are child objects associated with the object. To view the child entities in the Object Browser: 1. 2. Select the object in the hierarchy and the child objects appear in the detail pane. If you click on the plus sign in the hierarchy, the hierarchy explodes to reveal the children of that object in the hierarchy. You can continue to explode the hierarchy if a plus sign is displayed next to the object name.
Browser Hierarchy Relationships

Figure 2-26

Procedure - Viewing Parent and Child Relationships To view the relationships between parent and child objects in the Object Browser: 1. 2. Select the object in the hierarchy. Choose Options > View Relationships. Relationship objects appear in the window. See Figure 2-25 for an example of how the relationships are displayed.

Viewing Parent Entities

You can use the Object Browser to view and edit the parent entities in your repository. Procedure - Viewing Parent Entities To view the parent entities of an object in the Object Browser: 1. 2. Select the object in the hierarchy. Choose Selected > Explode Upward (or click Backspace or Up in the toolbar).

2-12

Using Freeway Explorer and the Object Browser

Committing Sessions Changes

If the selected object is a root in the hierarchy, the Object Browser changes to show the parent(s) of the object. If the selected object is a child in the hierarchy, the parent(s) of the object appears in a new Object Browser window. If the selected object has no parents, no action is taken.

Committing Sessions Changes

When you are finished editing the objects and relationships in a repository session, you must commit the changes for them to be saved. Procedure - Committing Session Changes 1. 2. In Freeway Explorer, select the object that you want saved to the repository. Select Session > Commit session changes (Figure 2-27).
Session Window

Figure 2-27

3.

A dialog opens that asks you to confirm the commit action (Figure 2-28).
Commit Changes Query Dialog

Figure 2-28

4.

Click the Commit button to save the changes to the repository. The status bar displays a success or failure message.
Once the Commit button is pressed, you cannot rollback changes.

Warning

AppBuilder 2.1.0 Workgroup Repository Administration Guide

2-13

Committing Sessions Changes

5.

If you have NOT committed the changes, you have the option to rollback any changes that have been made during the session. Select Rollback session changes and modifications will be reversed.

2-14

Using Freeway Explorer and the Object Browser

CHAPTER

LOCKING REPOSITORY OBJECTS

AppBuilder 2.1.0 Workgroup Repository Administration Guide

Objects are locked when changes are made to them in a repository, preventing other users from performing certain actions on those objects. The Workgroup repository uses an automatic object locking mechanism that: Prevents users from simultaneously updating the same object Preserves repository integrity when multiple objects are modified Preserves the integrity of relationships between objects After users commit or rollback changes, the system releases any locks that were placed on objects. Topics in this section include: Understanding Lock Types Displaying Locking Messages Broadcasting Updates

Understanding Lock Types

There are three kinds of locks that can be placed on an object in a Workgroup repository: Exclusive Lock Shared Lock Cascading Lock

Exclusive Lock
One of the types of locks that can be placed on an object in a Workgroup repository is the Exclusive Lock. When you successfully change an object, the object is exclusively locked by you. This limits the actions other users can take with the object until the session is committed or rolled back.

AppBuilder 2.1.0 Workgroup Repository Administration Guide

3-1

Understanding Lock Types

Using an exclusive lock, other users cannot: Modify or delete the object Relate objects to the locked object View the changes to the object (although the object can be seen as it existed before it was changed)
Figure 3-1 Exclusive Locks

Shared Lock
A Shared Lock prohibits other users from modifying or deleting the shared object, until the session is committed or rolled back. However, other objects can be related to the shared objects. These related objects are defined as shared locks when you: Modify an object that relates other objects together. or Create a new relationship between other objects.
Figure 3-2 Shared Locks

In Figure 3-2, the Owns relationship object that exists between a View object and a Rule object has been changed by User A, causing both the Rule and View objects to receive shared locks. Other users can attach objects to the Rule and View objects in their modeling, but they cannot modify or delete the Rule

3-2

Locking Repository Objects

Displaying Locking Messages

or View objects. User A always has privileges to modify or delete these objects. Other users can create objects that are used by the Rule or View object, as User B and C have done.

Note

If only one user has a shared lock on an object, that user can update or delete the object and the shared lock automatically converts into an exclusive lock. However, if another user has a shared lock on the object, the object cannot be changed or deleted until that user releases the lock.

Cascading Lock
A Cascading lock is identical to an Exclusive Lock, except that it applies to objects not directly updated. This type of lock is placed on an object that needs to be deleted because the object on which it depends has been deleted. The locked item is physically deleted when a commit is performed. Using the same example as Shared Lock, if a View object by definition connects to a Rule object and the Rule object is deleted, the Owns relationship object becomes locked because it cannot exist without both the View and Rule objects.
Figure 3-3 Cascading Lock

Displaying Locking Messages

Locking messages are displayed when a user attempts to: Save an object with attributes that have been modified in a design tool Create a relationship between two objects in a design tool Change an object in an analysis tool Change a drawing in an analysis tool If users attempt to change a locked object, the system displays one of the error messages summarized in Table 3-1.

AppBuilder 2.1.0 Workgroup Repository Administration Guide

3-3

Displaying Locking Messages

Table 3-1
Message

Locking Messages
Explanation The object cannot be changed or deleted because an exclusive or a cascading lock has been placed on the object by another user The object cannot be changed or deleted because it requires a shared lock on another object that is explicitly locked by another user The object cannot be changed or deleted because one or more users are sharing the object. The object cannot be deleted because an object that requires a cascading lock is already being shared by one or more users

The object is already locked by another session. A parent or child of the object is locked by another session. The object is currently being shared by one or more sessions.

AppBuilder allows you to check the locked status of objects using several processes: Checking Lock Status Viewing the Parent/Child Relationship of an Object

Checking Lock Status

1. 2. Open Freeway Explorer and connect to a Workgroup repository. Select Objects > Query, select an object type, and click Query. (See Querying and Loading Object Types on page 2-5 for instructions on Querying for objects.)
Object Query window

Figure 3-4

3. 4. 5.

The Find tab displays the list of available object instances in the repository. The Keywords tab opens the Keywords Search Wizard (Figure 2-13 on page 2-6) that searches for entities based on keywords. Select the object or objects that you wish to include in your session and click Load. You can select multiple objects using the Shift or Ctrl key. In the Freeway Explorer window, double-click on the object to open the Properties window, or choose Selected > Open Browser to view the hierarchy of the object. Select a component from the hierarchy. Choose Selected > Properties to view the properties (Figure 3-5).

6.

3-4

Locking Repository Objects

Displaying Locking Messages

Figure 3-5

Selecting Object Properties in the Browser

7.

The Properties window opens (Figure 3-6). Change the object attributes and click on Apply or OK. Only attributes in fields with a white background are available for modification.
Browser Properties Window

Figure 3-6

8.

When the modification to the object is completed, the system displays Action Successful in the status bar located at the lower left of the window (Figure 3-7).
Action Successful Message

Figure 3-7

9.

If the object is locked by another user, a message notifying you that the action failed due to security validation failure is shown (Figure 3-8).
Failed Validation Message

Figure 3-8

Checking Lock Status in the Audit Tab

You can also use the Audit tab in the Properties window for a relationship or object to check lock status. 1. 2. Select the Audit tab. The user who has the object locked is displayed (Figure 3-9).

AppBuilder 2.1.0 Workgroup Repository Administration Guide

3-5

Displaying Locking Messages

Figure 3-9

Locking Message in Properties Window

This user has the object locked.

Viewing the Parent/Child Relationship of an Object

For Entity objects: 1. 2. 3. 4. 5. Select an entity object in Freeway Explorer. Choose Selected > Open Browser. In the Browser window, select Options > View Relationships. Select the entity object relationship listed in the detail pane. Double-click it to open the Properties window. The parent/child relationship is listed under the General tab.
Entity Object Relationship Window

Figure 3-10

For Function objects: 1. Select the Function object in Freeway Explorer.

3-6

Locking Repository Objects

Broadcasting Updates

2. 3. 4. 5.

Choose Selected > Open Browser. In the Browser window, select Options > View Relationships. Select an object relationship from the list in the detail pane. Choose Selected > Properties from the menu to view the Properties window for the Function object (Figure 3-11). Follow the same procedure to view the relationship properties for any object in the Explorer window.

Figure 3-11

Function Object Relationship Properties Window

Broadcasting Updates
The system broadcasts object changes to all connected users tools when the updates are committed or rolled back. In many of the tools, the view of the objects is updated automatically. However, some tools that display complex images, such as drawings or source code, prompt the user to update the view of the object (Figure 3-12).
Figure 3-12 Out Of Sync Broadcast Message

The selections in the Out of Sync window allow you to: Refresh - updates the view of the object. Continue - leaves the view of the object as is. The words <out of sync> appear in the tool title bar. Close - closes the tool with no changes. For more information about broadcasting messages, see Appendix C, Using Freeway Manager and Utilities.

AppBuilder 2.1.0 Workgroup Repository Administration Guide

3-7

Broadcasting Updates

3-8

Locking Repository Objects

CHAPTER

MANAGING REPOSITORY SECURITY

AppBuilder 2.1.0 Workgroup Repository Administration Guide

The Workgroup repository system administrator sets security levels by assigning permissions that define access and actions that are allowable for the objects within the repository. Projects, Groups, and user IDs and passwords are managed using the Workgroup repository software. Setting and administering security of a repository involves: Understanding the Security Model Creating Projects, Groups, Users, and Super Users Managing Multiple Permissions Defining Native Security Optimizing Repository Security

Understanding the Security Model

Security is implemented using the Repository Security Model stored within the repository. The Repository Security Model uses the GROUP object as an intermediary between the PROJECT and USER objects facilitating easy, system-wide administration and access control. The security model includes: Setting Scope and Permissions Creating a Project Creating a Group Creating a User Assigning a Super User Figure 4-1 illustrates the basic Workgroup repository security model. The security model uses a simple series of assigned associations and permissions between: Projects Groups Users

AppBuilder 2.1.0 Workgroup Repository Administration Guide

4-1

Understanding the Security Model

Figure 4-1

Workgroup Repository Security Model

Projects A Project is the area to which development objects are defined. For example, an ACCOUNT object, a RECEIVABLE object, and other objects needed for an accounting application could be created in a project called ACCOUNTING. The Workgroup repository can store multiple projects. When you log on to a Workgroup repository, select and work within the context of a project you are assigned to.

Note

If you plan on migrating files between the Workgroup and a mainframe repository, project names must be four (4) characters or less.

Groups The Group defines users with common security permissions and scope. Multiple groups can be defined to a project, allowing different levels of permissions and scope. Additionally, a group can be defined to multiple projects, with the permissions in separate projects being different. For example, one user group can be permitted relate access to the objects in a project, while another group has create, relate, update, and delete access. Child subgroups can also be defined in the security model for the purpose of organization. Users A User is defined to native security with an assigned userID and password. A user must have access to the database tables in which the repository objects are stored in order to access them in AppBuilder. Users have access to objects only in the projects to which they are defined. A user may work in only one project at a time. The users permission and scope is a function of the Group-Project relationship defined for that project. From the group level, it is possible to grant or remove authority levels from many users with one action. New users in a group have access to objects in the project associated with that group. Figure 4-2 shows the relationship between projects and groups as displayed in the Project Hierarchy window.

4-2

Managing Repository Security

Understanding the Security Model

Figure 4-2

Project Hierarchy Window

Note

Access the Project Hierarchy Window by choosing Action>Project Hierarchy or Tools>Security>Projects&Group.

The type of access group members have to objects in the project is defined when a Group is included in a project hierarchy.

Setting Scope and Permissions

The Workgroup repository security model allows the Workgroup Administrator to grant scope and permissions to each Group individually. Each Group defined within a project hierarchy contains the scope and permission for the users within that group. Figure 4-3 shows a Group Security Properties window.
Figure 4-3 Security Options Window

The Administrator assigns the following group security attributes: Scope Permissions (Create, Relate, Update, Delete)

Scope
Scope defines the set of objects that developers have access to.

AppBuilder 2.1.0 Workgroup Repository Administration Guide

4-3

Understanding the Security Model

Figure 4-4

Setting Group Scope

Table 4-1 describes the five valid options for setting scope restrictions:
Table 4-1 Scope All HPS system model All HPS without field Fields only Security HPS system model Security only Definition of Scope Options Function Specifies all object types defined in the AppBuilder Information Model Specifies all object types defined in the AppBuilder Information Model except for Fields Specifies Field objects only Specifies all object types defined in the AppBuilder Information Model plus security objects Specifies security objects only

Permissions
Permissions define the allowable actions available for the group within the repository. Table 4-2 describes the permissions settings and descriptions of each option. Read access is implicit for all objects in all projects.
Table 4-2 Create Relate Update Delete Actions Permission Options The authority to create objects. The authority to make an object a child of another object. The authority to modify objects within the project if they are created by someone else. Allows a developer to delete objects within the project if they are created by someone else. To allow a developer to add, reuse, and modify (but not delete) objects to the repository, including objects that other developers have created, assign the developer membership in a Group with create, relate, and update permission for all AppBuilder system model objects.

Tip

Verifying Ownership and the Active Project

Relate, update, and delete permissions are assigned to the owner of an object exclusively until they are defined to other users using the security model. When a user attempts to update or delete an object, the Workgroup repository security mechanism verifies that the user owns the object, as illustrated in Figure 4-5. If the user owns the object and it is defined to the users active project, the user can update or delete the object. If the user does not own the object, the user must have update and/or delete permission defined within the security model.

4-4

Managing Repository Security

Creating Projects, Groups, Users, and Super Users

Figure 4-5

Verifying Ownership

Creating Projects, Groups, Users, and Super Users

AppBuilder Workgroup Repository uses a security model that requires each user to have authority assigned to the current project in order to create project, group and user objects. Follow the procedures outlined in the following sections to assign scope and permissions. Creating a Project Creating a Group Creating a User Assigning a Super User Viewing Group Members and User Groups

AppBuilder 2.1.0 Workgroup Repository Administration Guide

4-5

Creating Projects, Groups, Users, and Super Users

Creating a Project
1. In the Freeway Explorer window, open Tools > Security to open the Security User Group Maintenance window.
Security User Group Maintenance Window

Figure 4-6

2.

Click on the Projects & Groups button. The Project Hierarchy window opens (Figure 4-2).
Action Menu

Figure 4-7

3. 4.

Select Action > New Project in the Project Hierarchy window. The New Project dialog opens (Figure 4-8). Type the new <projectname> in the name field.
New Project Dialog

Figure 4-8

5.

Press OK.

Creating a Group
1. 2. In the Freeway Explorer window, open Tools > Security to open the Security User Group Maintenance window (Figure 4-6). Select Action > New Group from the menu (Figure 4-9).

4-6

Managing Repository Security

Creating Projects, Groups, Users, and Super Users

Figure 4-9

Adding a New Group in the Action Menu

3.

Type the new <groupname> in the name field of the New Group dialog (Figure 4-10).
New Group Dialog

Figure 4-10

4. 5. 6. 7.

Press OK. Open Tools > Security > Action > Project Hierarchy. Select the project you want to add the new group to. Choose Selected > Add Group.
Add Group Window

Figure 4-11

8.

Click on the group name that you want to add and click OK.

Creating a User
1. 2. In the Freeway Explorer window, open Tools > Security to open the Security User Group Maintenance window. (Figure 4-6). Select Action > New User from the menu (Figure 4-12).

AppBuilder 2.1.0 Workgroup Repository Administration Guide

4-7

Creating Projects, Groups, Users, and Super Users

Figure 4-12

Adding a New User in the Action Menu

3.

Type the <userID> in the name field of the New User window.
New User Window

Figure 4-13

4. 5. 6. 7. 8.

Click OK. Double-click on the <userID> in the Groups a member of list box. Click on <groupname> in the Groups Not a Member of list box. Click Add. Click OK.

Assigning a Super User

A super user is a user with permission to all projects with the Security system model scope. Any user in a group linked to the SYSADM project becomes a super user. Initially, anyone can log onto the system as USERID.

Tip

It is recommended that you assign a super user as soon as the first users are assigned.

The following example demonstrates how to create a super user. Procedure - Creating a Project Administrator ID in the Security Model 1. 2. 3. 4. 5. 6. In Freeway Explorer, select Connect from the Session menu. The Connect to Workgroup Group window appears. Type USERID and PASSWORD in the appropriate fields. Click Connect. The Freeway Explorer window opens. Select Security from the Tools menu. The Security window opens. Select Action > New User from the Action menu. Type JSMITH in the User Name field, and press OK. The user JSMITH appears as a child of the SYSADM group. Double-click on JSMITH in the All Users list box.

4-8

Managing Repository Security

Creating Projects, Groups, Users, and Super Users

7. 8. 9.

Click on the SYSADM Group in the Groups Not a Member of list box. Click on Add to move the SYSADM Group into the Groups a Member of list box. Click OK.

10. Click Close. 11. Select Session > Commit Session Changes from the Session menu, or click the Commit icon in the menu bar. 12. Exit Freeway Explorer. 13. To test the new ID, add JSMITH to native security. See Defining Native Security on page 4-15 for an example of this procedure. 14. Restart Freeway Explorer. 15. In the Connect to Repository window, type the new userID and password in the appropriate fields. 16. When you have confirmed that the new user ID can log in, remove the USERID user in the Security window.

Viewing Group Members and User Groups

You can see the Groups a user is a member of by selecting Tools > Security and double-clicking on the user name in the Security - User Group Maintenance window. If security settings permit membership for the user, you can add or remove a user from a Group using the Add and Remove navigation buttons (Figure 4-14).
Figure 4-14 User Group Associations User

Add or Remove Groups that the user belongs to by clicking the buttons

To view a list of members and non-members of a Group, select Action > Project Hierarchy from the Security - User Group Maintenance window, or click on the Projects & Groups button and double-click on the Group name in the Project Hierarchy window.

AppBuilder 2.1.0 Workgroup Repository Administration Guide

4-9

Creating Projects, Groups, Users, and Super Users

Figure 4-15

Group Security Associations

Changing Group Access to Objects in a Project

Use the Security - User Group Maintenance window to change Group scope and permissions for access to projects. Procedure - Setting Group Security in a Project 1. 2. 3. 4. 5. In the Freeway Explorer window, choose an object. Select Tools > Security. The Security User Group Maintenance window (Figure 4-9) opens. Click on the Projects & Groups button. Double-click on the Project or expand the Project by clicking the plus (+) sign next to it to view the associated groups. Double-click the Group in the Security - Project Hierarchy window or choose Selected > Security in the Security - Project Hierarchy menu (Figure 4-16).
Using the Selected Menu to View Security

Figure 4-16

6.

The Group Security Properties window opens. Select the required permissions by clicking the check boxes (Figure 4-17).

4-10

Managing Repository Security

Creating Projects, Groups, Users, and Super Users

Figure 4-17

Setting Group Permissions

7. 8.

Assign the Group scope setting from the options in the drag-down box. For a description of the scope selection options, see Table 4-1 on page 4-4. Click OK to apply the settings.

Using Relationship Properties to Set Group Security

1. Access Group security settings from the Security - Project Hierarchy window by selecting the Group name and choosing Selected > Relationship Properties in the menu (Figure 4-18).
The Relationship Properties Menu Selection

Figure 4-18

2.

On the General tab in the Relationship Properties window, view and modify the security information for the Group (Figure 4-19) by clicking the check boxes and selecting a drag-down option.

AppBuilder 2.1.0 Workgroup Repository Administration Guide

4-11

Managing Multiple Permissions

Figure 4-19

Relationship Properties Window

3.

Click OK or Apply.

Managing Multiple Permissions

The security settings can be used to configure AppBuilder provides several methods to manage multiple permissions, including: Allowing Groups Access to Multiple Projects Setting Global User Access Creating Subgroups Using Default Security Objects

Allowing Groups Access to Multiple Projects

Groups can be permitted access to single or multiple projects by selecting a <projectname> and adding the <groupname> to the project in the Project Hierarchy window using Selected > Add Group as described in step 5 of Creating a Group or by using the Add or Remove button as described in Viewing Group Members and User Groups.

Setting Global User Access

In addition to the SYSADM project, AppBuilder is shipped with two default projects, SEER1and SEER2, and a group, PUBLIC. The SEER1 and SEER2 projects contain default repository objects. The PUBLIC group includes all Workgroup users. The procedures that follow describe how to display the default projects and how you can grant global access to all users.

4-12

Managing Repository Security

Managing Multiple Permissions

Procedures - Default Projects and Global Access Displaying Default Projects To display the default Workgroup projects (SEER1 and SEER2) and group (PUBLIC): 1. From the Security > Project Hierarchy window, click on the plus (+) sign to the left of the project, as shown in Figure 4-20.
The PUBLIC Group

Figure 4-20

2. 3.

Double-click on the PUBLIC group to view the users permissions. Check that the relate box is checked.
PUBLIC Group Permissions

Figure 4-21

The PUBLIC group contains all Workgroup users. To grant all users access to a project, include the PUBLIC group in a projects permissions. Granting Global Access To grant all users access to a project: 1. 2. 3. 4. 5. 6. 7. Select a project <project_name> from the Security-Project Hierarchy window. Choose Selected > Add Group (Figure 4-11). Select the group PUBLIC. Click OK. Double-click on the group PUBLIC. Set the scope and access as desired. Click OK.

All Workgroup users now have access to the objects in <project_name>. The permissions and scope of the objects can be changed at any time by selecting and double-clicking the PUBLIC group under <project_name>.

Creating Subgroups
Create subgroups to organize a security structure without requiring individual user group member lists to be updated. For example, suppose there are three projects respectively named: DEVELOP1, QA1, and PRODUCTION1. Each project has a child group with an identical name.

AppBuilder 2.1.0 Workgroup Repository Administration Guide

4-13

Managing Multiple Permissions

In the example, the groups represented have the following access permissions to their respective projects:
Table 4-3 Subgroup Example Permissions Create, Relate, Update, Delete Relate, Update, Delete Relate Group Name DEVELOP QA PRODUCTION

To assign twenty new users access permissions to the DEVELOP1, QA1, and PRODUCTION1 projects, create a new group and add all the users to it (for example, you might call it NEWUSERS) and associate NEWUSERS with the DEVELOP, QA, and PRODUCTION groups, rather than adding users to each group associated with each project. Procedure - Creating a Subgroup 1. 2. 3. 4. 5. Create a new group using the standard procedure. In the Project Hierarchy window, select the group you want to connect the new group to. Choose Selected > Add Group from the menu. Select the name of the NEWUSERS group. Click OK.

Using Default Security Objects

The projects SEER1 and SEER2 and the group PUBLIC are included as default security objects. The SEER projects contain objects, such as HPS_EVENT_VIEW; components, such as GET_SELECTED_FIELD; and specialized fields, such as RETURN_CODE. All developers working in the default repository require these objects. Inclusion in the PUBLIC group provides a mechanism for implicitly granting all developers relate permission to reuse these objects. SEER projects are AppBuilders predefined, default system projects. HPS_EVENT_VIEW is an AppBuilder predefined, default system view.

PUBLIC Group
The PUBLIC group, by definition, represents all Workgroup users. It is a child of the SEER1 project by default, with only relate access permission defined. Repository system objects are in the SEER1 project, giving all users relate authority to all system objects, but not create, update, or delete authority. Defining Native Security provides detailed descriptions of the default objects provided in AppBuilder repository environments.

4-14

Managing Repository Security

Defining Native Security

Defining Native Security

Initially, each user must be defined to the supporting DataBase Management System (DBMS) providing two levels of security: Security defined within the supporting DBMS (SQL or Oracle Server). The DBMS or operating system controls the user password Security defined within the Workgroup repository Once users have been defined within the native DBMS, the Workgroup administrator may add users within the repository and then assign the appropriate project permissions. AppBuilder allows you to configure your security settings or use the defaults when appropriate. The following sections describe how to set security restrictions for specific servers or within the repository. Using Default Projects and Groups Understanding Default Permission Levels Modifying the Default Repository User ID Setting System Administrator Permissions Configuring Native Security for the SQL Server

Using Default Projects and Groups

AppBuilder contains the following default projects and groups: SYSADM - The SYSADM project represents access entry into the entire development system and database. Any user in a group linked to the SYSADM project becomes a super user. Define your project administrator as a super user immediately after installing Workgroup repository software. SEER1 and SEER2 - These projects contain default repository objects. PUBLIC - The PUBLIC group, by definition, represents all Workgroup users. Consequently, if you want to give all users access to the objects in a project, you can do so globally by associating the PUBLIC group with that project. AppBuilder is shipped with one default user (USERID) defined in its security model. Setup and configuration of the default repository creates the same default user within the native DBMS, in this case Oracle, with the password PASSWORD. Use USERID and PASSWORD to log onto the system and configure the initial security model. By default, the user USERID is defined as a system administrator or a member of the project SYSADM. This configuration is necessary for an initial connection to be established because at least one user must pre-exist within both the DBMS and the repository.

Note

Remove the default configuration after updating the model with non-default users and passwords.

Understanding Default Permission Levels

Global read permission is implicit for all users with access to the Workgroup repository. To specify permissions for other actions, use the appropriate default permission level defined in Table 4-4.

AppBuilder 2.1.0 Workgroup Repository Administration Guide

4-15

Defining Native Security

The security model contains four default permission levels:

Table 4-4 Level Project leader Analysts Programmers Project Security Security Model Scope and Permission Levels Option Settings All AppBuilder system models Create, Relate, Update, and Delete All AppBuilder system models Create, Relate, and Update (optional) All AppBuilder without fields Create and Relate Security Only Create and Relate Description Full permission to all development objects in the project Full permission, except for delete, to all development objects in the project Permission to create new objects and reuse other objects within the project Permissions required to maintain project security

Note

Generally, the Database Administrator or Analyst defines these fields, rather than a Programmer. Fields are usually defined to the PUBLIC project.

Modifying the Default Repository User ID

The default Workgroup repository allows anyone using USERID/PASSWORD to access AppBuilder development objects contained within the repository. Although the default repository only contains system objects, to prevent unauthorized access, remove USERID as the default userID as soon as you assign a system administrator.

Warning

Create a new user and add that user to the SYSADM Group prior to removing the default USERID.

Setting System Administrator Permissions

The default project included in the AppBuilder repository, SYSADM, permits entry for its users into the entire development system and database. System administrator group members have full access and permissions to the repository, security model, and Workgroup database. This mechanism provides centralized control and administration, thus maintaining the security infrastructure. Typically, system administrators are defined as super users. All Workgroup repository security checks are disabled for super users. Limit super user permissions to a select number of users, since numerous SYSADM users may create disorder in the repository. Procedure - Viewing the Default SYSADM Project To view the default SYSADM project: 1. 2. 3. 4. 5. Open Freeway Explorer. Click Connect from the Session menu. The Connect to Workgroup Group or Personal Repository window appears. Type <userID> and <password> in the appropriate fields and click Connect. Select Tools > Security. The Security User Group Maintenance window opens. Click on the Projects & Groups button. The Security-Project Hierarchy window displays, as shown in Figure 4-2.

4-16

Managing Repository Security

Defining Native Security

Figure 4-22

Default SYSADM Project and Group

6.

Select the SYSADM project and double-click, or click on the + sign, to view the groups assigned to it.

Configuring Native Security for the SQL Server

To configure native security for SQL servers, first register the server and define a user to native security.

Note
1. 2. 3. 4. 5.

The first user added becomes the System Administrator (sa) when Workgroup security is defined.

Double-click on the SQL Enterprise Manager icon located in the Microsoft SQL Server program group. The Server Manager window opens. Select the SQL 7.0 icon. Select Server > Register Server. The Register Server window opens. Type the <SQL Server name >in the Server field. Click Servers for a list of the available servers.
If the SQL Server has already been registered in SQL Enterprise Manager, skip steps 1 through 5.

Note
6. 7. 8. 9.

Select Server. Click OK. Click Use Trusted Connection. If there is a problem with the registration, re-examine the SQL Server setup. Click Register.

10. Click Close. The machine name appears with a stoplight icon in the Server Manager window. 11. Select the <machine name> 12. Select Security, Logins or Users in the Database hierarchy. The Manage Logins window appears. 13. Type <user ID> in the Login Name field. 14. Type <password> in the Password field.

Note

You must define a valid password to use Workgroup. Workgroup will not function if a null password is defined.

15. Select the Permit column for the Workgroup database for database access. 16. Select FREEWAYGROUP from the drop down combo box in the Group column. FREEWAYGROUP appears in a drop-down combo box after selecting the Group column for FREEWAY within Database Access. 17. Select Add. 18. Confirm the new users password. 19. Click OK. 20. Click Close to exit the Manage Logins screen. 21. Select File > Exit to exit SQL Enterprise Manager.

AppBuilder 2.1.0 Workgroup Repository Administration Guide

4-17

Optimizing Repository Security

After completing the procedure for Configuring Native Security for SQL Servers, the Workgroup user has permission to access the SQL Server tables. This is the first level of security a developer must have before operating within a Workgroup repository. The user must also be recognized within the AppBuilder security model to access the objects within the Workgroup repository. (See Creating a User.) When the starting point is a default repository, configure the entire security model ensuring that users have the correct level of permissions.

Optimizing Repository Security

The following recommendations can assist you in structuring and managing your repository security system for maximum performance. Define as few SYSADM users as possible. If the system administrator also develops applications with AppBuilder, define separate userIDs for administration functions and development functions, thus preventing unintentional SYSADM actions. Before the USERID user object is removed from the SYSADM group, ensure that the new SYSADM user can successfully attach to the Workgroup repository. Otherwise, the scenario of a Workgroup with no SYSADM user could occur. Define project security administrators, in addition to the SYSADM user(s), if multiple projects are being developed within the same repository. Leave the user USERID in the repository with read-only permission to ensure that a read-only user will always be defined. Define sufficient users to the security model to avoid having two developers using the same userID simultaneously. Use the client machine names, developer names, or TSO IDs whenever possible for userIDs. If objects will be migrated to an enterprise repository, define the Workgroup repository security model to match the enterprise security model. If the development project also exists on the mainframe, match userIDs to TSO IDs to maintain consistency.

4-18

Managing Repository Security

CHAPTER

MOVING DATA BETWEEN REPOSITORIES

AppBuilder 2.1.0 Workgroup Repository Administration Guide

AppBuilder repository migration tools provide a graphical user interface (GUI) on the client workstation that allows users to move objects between Workgroup repositories and the mainframe repository. You can export the migration files (MIGFILES) into any target repository within your enterprise. The migration tool functions are accessed in the Freeway Explorer window. The following topics explain migrating data between repositories: Migration Overview Understanding Migration Phases Performing a Migration Import Using Migration Results Using Application Folder to Migrate Data

Migration Overview
Most development environments require data migration. For instance, the objects comprising an application can be moved from a development to a quality assurance repository for testing. After the application is installed in the production environment, the objects can be moved to a maintenance repository. These objects can be migrated individually or as entire object hierarchies. Migration consists of four phases: Creating Migration Entities - Export Phase Creating a Migration Object - Load Phase Importing a Migration Object - Analyze Phase Performing Migrations - Import Phase The Migration Export and Import windows perform migrations between Workgroup repositories. The Application Folder tool supports the same functionality, with one exception, it does not: Perform impact analysis Create migration files in a format that mainframe and Workgroup repositories can import

5-1

Understanding Migration Phases

Understanding Migration Phases

There are four phases to a Workgroup repository data migration: Export Load Analyze Import Both the Import and the Export phases of migration are performed on a client workstation. The first phase, Export, is executed while connected to the source repository. The subsequent three stages, Load, Analyze, and Import, are executed while linked to the target repository. During the Export phase, the Migration facility is used to extract migration data from the source repository into migration files. These files are created and placed in the directory you specify in the Migration export directory field of the Migration Export setup window. Figure 5-1 shows an example of a directory path.
Figure 5-1 Migration Export Setup Window

The Load and Analyze phases are executed during an Import of data into a repository. In the Load phase, with the Migration tool linked to the target repository, the data in the migration files created during the Export phase is loaded into the target Workgroup repository. After completing the Load phase on the migration object, the Analyze phase can be executed. Analyze generates information on the entities and relationships included in the migration hierarchy. At this point, you make a determination whether or not to make the indicated changes in the target repository. This phase must be executed to determine which objects exported from the source repository are to be created or updated in the target repository. Once the Analyze phase is complete, execute the Import phase to actually create, delete, or update the repository object in the target repository. During this phase, actual ownership for the objects being maintained is assigned. The object retains the security information related to project and owner.

5-2

Moving Data Between Repositories

Performing a Migration Export

Figure 5-2

Four Phases of Migration

Performing a Migration Export

A migration object is composed of a set of migration files in the repository that you select using the AppBuilder migration tools in Freeway Explorer. Migrations can be done from a client workstation if the client is connected to a Workgroup repository. When producing object migrations during an export, the system produces files with an FIL extension. These files are used for the migration import. Multiple sets of migration files can be created by storing the files in separate directories. Related topics in this section include: Understanding the Migration Export Toolbar Using the Migration Export Tool Creating a Migration Object - Load Phase Creating Migration Entities - Export Phase Setting the Migration Object Scope

Understanding the Migration Export Toolbar

The tools available in the Migration Export toolbar (Figure 5-3) offer an alternative method to access the same functionality as the corresponding menu items in the Migration Export window drop-down menu (Figure 5-9).
Figure 5-3 Export Toolbar Icons

Export

Add root objects Remove from export

View log file

Properties Edit export properties

Open Browser

Using the Migration Export Tool

To export objects into your directory for inclusion in your Unit of Work, use the following procedure.

AppBuilder 2.1.0 Workgroup Repository Administration Guide

5-3

Performing a Migration Export

Procedure - To configure a migration export 1. 2. Open Freeway Explorer from the Start menu and connect to a Workgroup repository. Select Tools > Migration Export from Freeway Explorer, as shown in Figure 5-4.
Migration Export Tools Menu

Figure 5-4

3. 4.

Choose from the options: Create, Open, or Remove. Selecting Create opens a fill-in dialog box (Figure 5-5).
Migration Create Export Window

Figure 5-5

5.

Selecting Open displays the Migration Query dialog box (Figure 5-6). You can then type in a specific object instance, the first characters of an object instance, or you can click the Query button to view a complete list of available objects. Click on the object instance in the list to select it.

5-4

Moving Data Between Repositories

Performing a Migration Export

Figure 5-6

Migration Query Window

6.

Remove displays the Remove Migration Object dialog box (Figure 5-7). Clicking the Remove button deletes the entity in the Unit Of Work (UOW or current session) and from the server after the migration is exported.

Figure 5-7

Remove Migration Object Window

You can also remove objects from the repository using the Selected > Remove from repository menu selection, if you have been assigned delete permission (Figure 5-8).

AppBuilder 2.1.0 Workgroup Repository Administration Guide

5-5

Performing a Migration Export

Figure 5-8

Remove from Repository Option

7.

The Purge from repository option deletes the entity locally without altering the UOW; therefore, the entity is not deleted from the server upon import.

Creating a Migration Object - Load Phase

Before you perform data migration exports, you create a migration object by selecting the objects from the repository and exporting them into a directory. Procedure - Creating Migration Objects 1. Select Tools > Migration Export in the Freeway Explorer window. The Migration Export window opens (Figure 5-9).
Migration Export Window

Figure 5-9

2.

Select Objects > Add root objects to construct the migration object (Figure 5-10). The Migration Query dialog opens to access the list of available objects.
Adding Root Objects

Figure 5-10

3.

Choose an object type from the drag-down box at the top of the window (Figure 5-11).

5-6

Moving Data Between Repositories

Performing a Migration Export

Figure 5-11

Selecting the Object Type

4.

Select the object or multiple objects and click Load (Figure 5-12).
Migration Export Query Dialog

Figure 5-12

Using the Migration Export Action Menu

Select Migration Export > Action to access the tools used to initialize the export, display the object in text format, and display the log results (Figure 5-13).
Figure 5-13 Migration Action Menu

AppBuilder 2.1.0 Workgroup Repository Administration Guide

5-7

Performing a Migration Export

Table 5-1 describes the Migration Action menu options.

Table 5-1 Migration Action Menu Options Explanation Exports the objects you have added as object roots and writes the data to migration files. Displays the objects and relationships in .txt format Displays information that was recorded during the export. Menu Items Export Display View Log file

Setting Export Migration Options

Selecting Export opens the Migration Export setup dialog (Figure 5-1). The Export window contains three tabs for setting additional migration configurations: Export Filters Options
Figure 5-14 Migration Export Tabs

Export In the fields provided on the Export Directory tab, you define the target directory for migration objects. Figure 5-1 shows an example of the pathname field used to set the destination for your migration object files. There is also a Browse button that allows you to locate a directory for your migration export. Filters Using the Filters tab, you can establish project, date, and time filters for the migration objects you are exporting (Figure 5-15). The Filters window allows you to set specific filters for objects to be included or excluded in the migration.

Note
Table 5-2

The time field must be used in conjunction with the date field. Export Filters Window Options Type the name of a valid project in this field. Equal radio button includes all the objects in the specified project, consistent with the scope defined. Not Equal radio button excludes all the objects in the specified project. Type the date and time using the formats examples to export data based on date and timestamps associated with the objects. Before radio button specifies to export objects before the defined date On radio button specifies dates that match the timestamp exactly After radio button specifies dates after the defined timestamp

Project

Date and Time

5-8

Moving Data Between Repositories

Performing a Migration Export

Figure 5-15

Migration Export Filters

Options The Options tab allows you to specify notification, tracing, display log, and hierarchy settings for the migration object (Figure 5-16). Click on the check box next to the option you want to function during your migration export. Table 5-3 describes the actions in the Options menu in the Migration Export configuration window.
Table 5-3 Option Beep on completion of export Export tracing Display log on completion of export Migration Export Options Description Workstation notifies completion of the export with a beep sound Generates a string for every routine the migration calls and places it in the log file after export Automatically displays the LOG file after export Checked - Exports the entire hierarchy. The Export Level(s) as Hierarchy option must be checked for deletions to occur in a migration. Unchecked - Exports all objects and relationships in the level selected as Entity Only. Objects are automatically merged into the target repository (no implied deletes of relationships take place in the target repository).

Export Level(s) as Hierarchy

Figure 5-16

Migration Export Options

Select the Tracing option to write the information to a file called either LOAD.OUT, ANALYZE.OUT, ANAIMP.OUT, IMPORT.OUT or EXPORT.OUT, depending on the relevant operation.

Note

If an error occurs in a migration operation, a less detailed version of these .OUT files is created regardless of the tracing option selection.

AppBuilder 2.1.0 Workgroup Repository Administration Guide

5-9

Performing a Migration Export

Select Display log on completion of export to generate a log and display it after export. The system writes an EXPORT.OUT file with information about the migration whether the migration succeeds or fails and puts these files in the directory specified in Migration export Window. It can be opened and viewed using any standard text editor, such as Notepad. Figure 5-17 shows a sample migration log file.
Figure 5-17 Sample Migration Log File

Creating Migration Entities - Export Phase

The following procedure explains how to create a migration entity and attach root (child) objects to migrate to another Workgroup repository. Procedure - Creating Migration Entities 1. 2. In Freeway Explorer, follow the procedure to create a new migration object, as outlined in Creating a Migration Object - Load Phase on page 5-6. If repository security settings permit, the migration object displays a message: Object creation was successful. 3. 4. Click OK. The Migration Export window for the created object opens. Select Objects > Add root objects and query for the objects you wish to add.
If no objects have been created, open the Construction Workbench and create the objects.

Note
5. 6.

Select the objects and click Load. (You can add more than one object from the list by holding down the SHIFT or Ctrl key while selecting the files.) Highlight the migration object and choose Selected > Export properties... (Figure 5-18). The Edit Root Entity Window opens (Figure 5-19).

5-10

Moving Data Between Repositories

Performing a Migration Export

Figure 5-18

Migration Export Selected Menu

7.

In the Edit Root Entity window, select the scope and SmartScope settings, if any. Click OK.
Edit Root Entity Window

Figure 5-19

8. 9.

Select Action > Export in the Migration Export window. The Migration Export configuration window opens to the Migration Export setup window (Figure 5-1 on page 5-2). Follow the directions for setting options, as described in Using the Migration Export Action Menu on page 5-7.

10. Click Apply or Export. The result dialog displays: Action Successful 11. Click OK to accept the result.

Setting the Migration Object Scope

Scope settings must be defined for each child object included in a migration export. Modify entity scope settings in the Migration Export window by choosing Selected > Export properties... (See Figure 5-19 on page 5-11). Table 5-4 lists the available scope options for child objects.
Table 5-4 Migration Scope Options Description Exports the migration object only. Exports the migration child object and all its child hierarchies in the migration. Exports the root entity and any child entities one level down the hierarchy. Exports the root entity and any child entities one level down the hierarchy and the parent entity of the root entity (one level up the hierarchy). Exports the root entity and any child entities two levels down the hierarchy and the parent and grandparent entities (two levels up the hierarchy). Exports the root entity and any child entities two levels down the hierarchy. Scope Options Entity Only Full Hierarchy One Level (Children) One Level (Parents - Children) Two Level (Parents - Children) Two Level (Children)

AppBuilder 2.1.0 Workgroup Repository Administration Guide

5-11

Performing a Migration Export

Using SmartScope Options

SmartScope settings are also available from this window. These options can further limit the scope of objects selected for export using the options described in Table 5-5.
Table 5-5 SmartScope Options Description Exported objects are associated with the SEER1 and SEER2 projects. Exported objects are not associated with SEER1 and SEER2 projects. Exported objects of the type listed in Table 5-6 that are in the hierarchy, regardless of which project they are associated with. Exported objects of the type listed in Table 5-6 that are in the hierarchy and not associated with SEER1 or SEER2 projects. Exported objects of the type listed in Table 5-7 that are in the hierarchy, regardless of which project they are associated with. Exported objects of the type listed in Table 5-7 that are in the hierarchy and associated with SEER1 or SEER2 projects. Exported objects are of the type listed in Table 5-6, regardless of the project they are associated with. Exported objects are of the type listed in Table 5-6, not associated with SEER1 or SEER2 projects. Exports all objects, except field objects. No options selected The relationships to the field objects are created during the import, if the field objects exist in the target repository and the relationships are not already there. Rule_to_Leaf SmartScope Object Types Relationships bitmap_has_bitmap_implementation component_owns_view component_refers_to component_uses_component field_uses_language file_is_accessed_by_component file_is_accessed_by_rule file_is_forwarded_to_file file_is_keyed_to_file file_owns_view physical_event_has_rule physical_event_owns_view report_contains_section report_refers_to_set rule_converses_report rule_converses_window rule_depends_on_rule SmartScope Options ONLY_SYSTEM_COMPONENTS NO_SYSTEM_COMPONENTS RULE_TO_LEAF RULE_TO_LEAF_NO_SYS_COMPS SETS_TO_LEAF SETS_TO_LEAF_NO_SYS_COMPS WINDOW_TO_LEAF WINDOW_TO_LEAF_NO_SYS_COMPS WITHOUT FIELDS (None)

Note
Table 5-6 Entities bitmap

bitmap_implementation component field file help_text language panel physical_event report rule section set symbol value view window_content

5-12

Moving Data Between Repositories

Performing a Migration Export

Table 5-6 Entities windows

Rule_to_Leaf SmartScope Object Types (Continued) Relationships rule_has_bitmap rule_owns_view rule_refers_to_set rule_triggers_physical_event rule_uses_component rule_uses_rule section_owns_view section_uses_language set_contains_symbol set_contains_value symbol_uses_language view_includes_field view_includes_view window_content_has_help_text window_content_has_panel window_has_bitmap window_has_window_content window_owns_view window_refers_to_set

Note

Any entity or relationship of these types will be exported regardless of whether these objects appear as part of a windows subhierarchy. For example, if you export the Process, and choose the Rule_to_Leaf SmartScope, the export will include BITMAP_A, BITMAP_B, RULE AND VIEW. Sets_to_Leaf SmartScope Object Types Relationships set_contains_symbol set_contains_values symbol_uses_language Window_to_Leaf SmartScope Object Types Relationships bitmap_has bitmap_implementation field_uses_languages set_contains_values set_contains_symbols symbol_uses_language view_include_field view_includes_view window_has_bitmap window_owns_view

Table 5-7 Entities language set symbol Table 5-8 Entities bitmap

bitmap_implementation field help_text language panel set symbol value view window

AppBuilder 2.1.0 Workgroup Repository Administration Guide

5-13

Performing a Migration Import

Table 5-8 Entities

Window_to_Leaf SmartScope Object Types (Continued) Relationships window_refers_to window_content_has_help_text window_content_has_panel window_has_window_content

window_content

Performing a Migration Import

When the migration files have been successfully loaded into the target repository, you are ready to migrate objects into the Workgroup repository. The migration phases of Analyze and Import are executed using the Migration Import window. The Migration Import window allows you to analyze and compare the migration objects and perform either a Selective Import or a Direct Import of data from the migration files created in the Migration Export window. Selective Import A selective import enables objects to be analyzed, viewed, and selected in order to create, update, or delete them before being physically imported to a target repository. A selective import analyzes the objects to be created, updated, or deleted in the Selective Migration window. Revisions to the objects import status can be made there. Direct Import A direct import imports data without the analysis step. It disables the analysis options prior to doing the physical import, thus it often increases processing speed. However, the advantages of analysis and selective migration are lost because the user cannot change the status of the data to be imported.

Tip

Decide in advance whether the Merge option will be used when exporting data using a selective import.

Migration Import Toolbar and Icons

The Migration Import menu toolbar icons are described in Figure 5-20.
Figure 5-20 Migration Import Toolbar

Analyze Analyze w/Merge Selective Migration Import Direct Import Analyze Report Import Report

Direct Import Report

5-14

Moving Data Between Repositories

Performing a Migration Import

Importing a Migration Object - Analyze Phase

When migration objects have been created and identified, you are ready to begin the analysis of the objects to be migrated. The Analyze phase allows you to define the import options controlling the migration objects. The import itself acts upon data that the Analyze creates, not the migration files. The data files define exactly what will happen to the migration files that are imported. During Analyze, the option to create, update, compare, or delete objects being imported can be defined and redefined repeatedly. The migration import process consists of two phases: Connecting to a Target Repository Performing the Migration Analysis

Connecting to a Target Repository

You must connect to the target repository before beginning the migration import process. Use the Migration Export window to create a migration object or objects, if necessary, as described in Creating Migration Entities - Export Phase. Files created during the export phase must be able to access the workstation where subsequent phases are executed. Procedure - Selecting a Migration Import Directory To begin the migration import operation: 1. In Freeway Explorer, select Tools > Migration Import. The Migration Import window opens (Figure 5-21).
Migration Import Window

Figure 5-21

2.

Select File > Choose Directory (Figure 5-22) to locate the directory the migration files were exported to during the Export phase.
Choose Directory Menu

Figure 5-22

3.

Locate the directory in the Select Migration Directory window (Figure 5-23) and click OK.

AppBuilder 2.1.0 Workgroup Repository Administration Guide

5-15

Performing a Migration Import

Figure 5-23

Select Migration Directory Window

4.

The Migration Import window opens and the status bar displays the directory path (Figure 5-24).
Directory Location in the Status Bar

Figure 5-24

Performing the Migration Analysis

The objects that have been selected for migration can now be analyzed using the following procedure. Procedure - Analyzing Migration Objects To analyze migration objects, after creating the migration object and selecting the migration directory as described in Connecting to a Target Repository: 1. Select Action > Analyze, or Analyze w/Merge (Figure 5-25). (See Using the Analyze w/Merge Option for descriptions of these two options.) An analysis is performed on files in the selected migration object in the directory.
Analyze Menu

Figure 5-25

2.

On completion, the Migration Import analysis report is displayed (Figure 5-26). It contains information about the migration import phase and status, and the results summary for entities and relationships comparisons.

5-16

Moving Data Between Repositories

Performing a Migration Import

Figure 5-26

Migration Import Analysis Report

3.

Select View > Analyze to examine the results of the analysis phase for migration (Figure 5-27).
Viewing the Import Analysis

Figure 5-27

Using the Analyze w/Merge Option

The Analyze w/Merge option controls how the system effects specific objects during an import. For example, a set of migration files (source) and a repository (target) contain the Object A. Object A has a child object in the target repository, but not in the source repository. The Merge option determines what happens to the relationship between Object A and the child object when the source is imported to the target. If the Merge option is used, the relationship between the object and the child is unchanged. If the Merge option is not used, the relationship is deleted.

Note

If the Merge option is not used, only the relationship is deleted; the child object remains unchanged in the target repository.

AppBuilder 2.1.0 Workgroup Repository Administration Guide

5-17

Performing Migrations - Import Phase

The Merge option has the same effect when an object in the target repository has an associated file (text, keywords, or source). If the file object is present in the target but is not present in the source, the Merge option determines whether the file is moved or deleted when an import is performed.

Using Merge in a Direct or Selective Import

A direct or selective import with merge selected in the Analyze phase controls the analysis of relationships between the data being imported and data on the target repository. An import with merge on, where there is a relationship that exists in the target repository that does not exist in the source repository, causes the relationship to not be marked for deletion. The objects simply merge into the hierarchy without deleting any relationships. If the merge option is off, the relationship is marked for deletion. For example, as shown in Figure 5-28, suppose the target hierarchy consists of component COMP1 with child objects VIEW1 and VIEW2, and the source hierarchy consists of just COMP1 and VIEW1. If the merge option is on when the analysis is performed, the relationship between COMP1 and VIEW2 is not marked for deletion. If the merge option is off, the relationship between COMP1 and VIEW2 is marked for deletion in the target repository.
Figure 5-28 Merge Option Example

Performing Migrations - Import Phase

When the analysis of the migration object has been completed and modifications have been made, you are ready to perform the migration import.

5-18

Moving Data Between Repositories

Performing Migrations - Import Phase

The import can be a migration of all the repository objects or a group of objects Using a Selective Import option and specific actions can be specified as described in Choosing Object Import Actions.

Using a Selective Import

Use a Selective Import to choose the exact objects to be migrated from the repository by clicking on an object and using the menu items. Single or multiple objects can be selected using the Shift or Ctrl keys while clicking on the objects in the repository. The menu items and toolbar provide the tools for choosing and changing the import objects before the import. Figure 5-29 describes the toolbar options for a selective import.
Figure 5-29 Selective Import Toolbar

Query Object type Query Status Query Shortname/Child Query Name/Parent Toggle Actions Off Toggle Compare Toggle Delete Toggle Update Toggle Create Toggle Selected Save

Choosing Object Import Actions

The Toggle commands control the object import status for the migration object during selective migration. The import status determines whether the import object should be compared, created, updated, or deleted in the target repository. It also specifies whether to flag changes between the source and target objects. The import status can be toggled between on and off. For example, if the status of an object is Create, the physical import will create it in the target repository. Toggle the import status to Create Off and the physical import will not create it in the target repository. The import status Compare can be toggled to Compare Off; and so on. To toggle only specific selected objects in the import list, choose Toggle > Selected and it will modify the status. If Selected is not specified, the status requested will apply to all the objects in the import.

AppBuilder 2.1.0 Workgroup Repository Administration Guide

5-19

Performing Migrations - Import Phase

Figure 5-30 explains the import status designations. To change the import status of an object, choose the desired action from the Toggle menu.
Figure 5-30 Status Compare Create Update Delete Conflict Import Status Designations Explanation An identical object currently exists in the target repository. The object does not currently exist in the target repository. The object currently exists in the target repository but is not identical to the object about to be imported. The object exists in the target repository, but not in the source. Performing the physical import causes the object in the target repository to be deleted. The source and target objects have the same name and object type, but have different system IDs.

The following section explains the import status categories in more detail: Compare - An identical object currently exists in the target repository. When a physical import is performed, the object being imported and the object in the target repository are compared. If the object in the target repository is modified after the analysis operation but before the import, the import operation reports that the target object has been modified since the analyze was performed. However, the object is not updated by the import operation. Create - The object does not currently exist in the target repository. When the physical import is performed, if it still does not exist in the target directory, it will be created. Update - The object currently exists in the target repository, but is not identical to the object to be imported. The object being imported overwrites the object in the target repository when the import is implemented. Delete - The object exists in the target repository, but not in the source. The physical import causes the object in the target repository to be deleted. This status applies only to dependent objects, such as text, source, keywords, and relationships. Primary objects cannot be deleted using the migration facility. Conflict - The source and target objects have the same name and object type, but different system IDs. This occurs when two objects of the same type are created in two separate repositories and are given the same name. Conflict indicates that the source object will not be imported. To import the source object, rename one of the objects and then perform the analyze operation again.

Note

The Conflict import status cannot be toggled.

5-20

Moving Data Between Repositories

Performing Migrations - Import Phase

Importing Migration Objects

Before you preform a migration import, you can adjust the following INI setting in the HPS.INI file so your import will continue processing even if an error occurs: [FREEWAY] MIG_ABORT_ON_ERROR=TRUE The default for this setting is False. When set to False, the import stops on all errors, and no additional data is imported past that point in the migration. When this setting is set to True, the import continues even if an error occurs; however, the result of the migration is still failed because all of the data was not imported. The following procedure describes how to complete the migration import. Procedure - Performing a Migration Import 1. 2. Follow the steps outlined in Importing a Migration Object - Analyze Phase. Select Action > Selective Migration to selectively choose or modify the objects to import in the Selective Migration window (Figure 5-31). See Using a Selective Import for descriptions of the menu options.

Note

This step is optional. Choose Direct Import to move directly to the import. See Using Migration Results. Selective Migration Window

Figure 5-31

3.

Select the actions from the Toggle menu (Figure 5-32). Toggle > Selected turns Compare on and off selected objects. (Detailed information about Toggle menu options is provided in Choosing Object Import Actions.)

AppBuilder 2.1.0 Workgroup Repository Administration Guide

5-21

Performing Migrations - Import Phase

Figure 5-32

Toggle Menu

4. 5.

Click File > Save. From the Migration Import window, select Action > Import. A dialog appears asking if you want to add imported items to your Unit of Work. (Figure 5-33).
Active Unit of Work Dialog

Figure 5-33

6. 7. 8.

Click Yes to begin the import. The progress of the migration is displayed in the status bar during the import. The status bar message confirms that the import succeeded or failed. To check the results, query for a specific object from within the Construction Workbench application. Migration import results can be viewed in the resulting report by selecting View > Import in the Migration Import window (Figure 5-27).

Performing a Direct Import

In a Direct Import, all the objects specified in the migration files are imported to the target repository without an intervening analysis operation. The analyze and import processes are coupled into one action. A direct import disables the options to analyze, view, or select objects before doing the physical import to the target repository. This lower level of processing results in a direct import being faster than a selective import. Perform a direct import only when the import status of the data does not need to be changed. For example, Group 1 and Group 2 selectively migrate their data to a central repository where integration of the data is performed. A direct import is very useful in this scenario, because Group 1 and Group 2 are complete and approved, no revisions need to be made, and mirror images of the latest object hierarchies can be directly imported.

5-22

Moving Data Between Repositories

Using Migration Results

Direct Import has a menu item to automatically toggle objects between Compare and Compare Off before the import takes place. To use this option, in the Migration Object import window, select Options > Compare Off. Procedure - Performing a Direct Import To perform a direct import: 1. Select Action > Direct Import (Figure 5-34).
Direct Import Menu

Figure 5-34

2.

View the results of the import in the resulting Migration Import report by selecting View > Import in the Migration Import window (Figure 5-27).

Using Migration Results

Each phase of a migration produces a different set of output files. These files have either a .LOG or .OUT file extension. LOG files contain details of a successful migration. This information includes the type of entity, the long name of the entity, the scope of the migration child object to which the entity belongs, and an object status line. OUT files contain troubleshooting information to use if the migration was unsuccessful. If any phase of the migration fails, only the OUT files are produced. LOG files may still be created, but they will be empty. If the migration phase is unsuccessful, the appropriate OUT file is displayed. To display the LOG or OUT file after a successful execution, click on Results in the Migration Facility Window (Figure 5-17). LOG files are located in the directory the migration is targeted to. The generated .OUT file is placed in the same directory the migration files reside in, as defined in the Migration Export window (Figure 5-1). Table 5-9 lists the output files produced during each migration operation.
Table 5-9 Operation Export Load Direct Import Analysis Import Migration Output Files Output Files EXPORT.LOG, EXPORT.OUT LOAD.LOG, LOAD.OUT ANAIMP.LOG, ANAIMP.OUT ANALYZE.LOG, ANALYZE.OUT IMPORT.LOG, IMPORT.OUT

AppBuilder 2.1.0 Workgroup Repository Administration Guide

5-23

Migrating Between Workgroup and Enterprise Repositories

Sample LOG File

Figure 5-35 shows a sample LOG file containing the results of a successful migration import. The report contains information regarding the migration import, such as: The migration phase executed: Analyze, Import, or Export The start date and time of the LOG file The status of the action executed: Successful or Failed The summary count of the entities and relations involved in the migration A list of the entities and relationships in the migration object with descriptions of the change status The type of entity, such as Attribute, View, or Field
Figure 5-35 Migration Import Report

Migrating Between Workgroup and Enterprise Repositories

The migration files created during the export phase of a Workgroup migration can transfer data to an enterprise repository. Migration files created in an enterprise repository can also transfer data to a Workgroup repository.

5-24

Moving Data Between Repositories

Migrating Between Workgroup and Enterprise Repositories

Renaming PC Migration Files

Table 5-10 lists the naming equivalencies to use for migrations between PC and mainframe migration files for export to the mainframe and import to the PC:
Table 5-10 Migration File-naming Comparison PC File control.fil elog.fil ent.fil rel.fil inmig.fil migxx.fil text.fil key.fil srct.fil srcbhdr.fil srcbdat.fil Host File migcntl elogkey entity rlogkey inmig migxx text keyword source srcbhdr srcbdat

Transfer these files between the PC and the mainframe using FTP. Transfer the files using ASCII format, except for srcbdat.fil (srcbdat) files. These are binary files and must be transferred using the binary setting in FTP.

Understanding Mainframe Migration and Repository Security

Migration between Workgroup repositories is accomplished from a PC workstation, however, the ability to migrate is dependent upon defined levels of authorization in the respective security models for each repository. During the Export phase, a user exports objects from the source repository. These objects are stored in temporary files, loaded into migration tables, compared to the target repository tables, and then finally migrated into the target repository tables. The initial migration Import assigns ownership in the target Workgroup repository for the entities included in the migration files. The owner is the pre-existing OWNER defined in the attributes of the object. When importing objects into the enterprise repository, the project to which the object is defined must exist within the security model in the target enterprise repository. If the project does not exist, the import will fail. Additionally, the user executing the import must have create and update permissions to the target project, or the import will not successfully import the relationships between some objects. Any user who successfully migrates an object is identified by the object audit information in the target Workgroup repository as the last user. This is the case for the initial migration and for successive migrations.

AppBuilder 2.1.0 Workgroup Repository Administration Guide

5-25

Using Application Folder to Migrate Data

Using Application Folder to Migrate Data

Use the Application Folder Export window and the Application Folder/CDIF Import window to perform migrations between Workgroup repositories. Unlike the standard Workgroup migration tool, the Application Folder migration does not perform an impact analysis. In an Application Folder import, objects are merged into the existing repository, overwriting existing data. The procedures for migrating data using Application Folders include: Exporting Application Folder Data Importing Application Folder Data Performing an Application Folder Migration Importing and Exporting Using CDIF

Exporting Application Folder Data

To define an Application Folder export: 1. 2. 3. From Freeway Explorer, select Tools > Application Folder Export. Select Create, Open, or Remove from the pop-up menu. Selecting Create displays the Application Folder window (Figure 5-36). Follow the instructions for a standard Workgroup migration export. (See Creating Migration Entities - Export Phase on page 5-10).
Create Application Folder Dialog

Figure 5-36

4.

The Application Folder Export window opens (Figure 5-37).

Application Folder Export Window

Figure 5-37

Use the migration tools from the menu to add root objects (Figure 5-38), modify existing objects, and view the log file, properties, or relationships.

5-26

Moving Data Between Repositories

Using Application Folder to Migrate Data

Figure 5-38

Adding Root Objects

5. 6.

When you are ready to perform the export, select Action > Export or use the Export menu item. Complete the information in the fields of each tab in the Application Folder Export window and click Export or Apply to initiate the export. See Configuring the Application Folder Export for information on the configuration settings for the export.
Application Folder Export Configuration Window

Figure 5-39

AppBuilder 2.1.0 Workgroup Repository Administration Guide

5-27

Using Application Folder to Migrate Data

Configuring the Application Folder Export

Table 5-11 describes the Application Folder Export windows tab contents:
Table 5-11 Export Window Tabs Descriptions Tab Names Destination Description Names that define specific instances of exports in a particular Application Folder Names of the files and paths used for the export Includes dependent files in the export Available Functions Saved in the Workgroup repository to make delta exports possible Subsequent instances of exports to the same destination only include information changed since the previous export Export File field specifies the path and name of the CDF file Log File field specifies the name of the file into which the export information is saved Text and keywords Associated files Application folder and scope files Project - name of a project associated with objects to be exported Equal - includes all objects in the specified project in migration Not Equal - excludes all the objects in specified project from migration Date or Timestamps - marks objects to include in the export Beep sound - produced when export operation has completed log file - displayed automatically at end of export operation

File

Include

Filters

Optional filters to limit the objects to include or exclude in an export

Options

Available options

Some of these fields are also described in Setting Export Migration Options on page 5-8. Refer to Figure 5-40 through Figure 5-43 for examples of the Application Folder configuration tab windows.
Figure 5-40 Application Folder File Tab

Figure 5-41

Application Folder Include Tab

5-28

Moving Data Between Repositories

Using Application Folder to Migrate Data

Figure 5-42

Application Folder Filters Tab

Figure 5-43

Application Folders Options Tab

Creating a Target Destination

To create a target destination for the export, click on the Destination tab and perform the following steps: 1. Click on Create. The Create Target Destination window appears (Figure 5-44).
Target Destination Window

Figure 5-44

2. 3.

Type the destination name in the Name field. Click on OK. The name appears in the Selected Destination field. The system notifies you of a successful or failed export in message boxes (Figure 5-45).

AppBuilder 2.1.0 Workgroup Repository Administration Guide

5-29

Importing Application Folder Data

Figure 5-45

Export Status Dialog

4.

A log file is generated that can be displayed using Action > View Log File... from the Application Folder Export window (Figure 5-46).
View Export Log File Menu Item

Figure 5-46

Importing Application Folder Data

Use the Application Folder/CDIF Import window to import data from the export file created in the Application Folder Export window. 1. Select Tools > Application Folder/CDIF Import in Freeway Explorer (Figure 5-47). The Application Folder Import window opens.
Application Folder/CDIF Import Menu Item

Figure 5-47

To manage repository security when migrating objects, objects can either be imported, maintaining the same owner and project attributes, or the owner and project can be redefined to allow permissions to the user performing the CDIF import. Essentially, the user has the option to overwrite audit information.

Warning

Use caution when overwriting security information to avoid disruption in the development environment and conflicting permissions.

5-30

Moving Data Between Repositories

Importing Application Folder Data

Application folders provide the same functions as a CDIF import: Exporting objects and their hierarchies from a Workgroup repository for import into other CASE tools Importing data from other CASE tools that support the CDIF standard into Workgroup repositories Exchanging data between different Workgroup repositories Application Folders use the CDIF format for exported files. They also provide additional features: The use of Application Folders as containers for objects Application folders that track which objects have been exported to a particular destination Comparison functions so that only objects changed or added since the previous export are exported in subsequent exports to a given destination Exports that are constrained to specific objects in an Application Folder using filters: a. Only objects belonging to a particular project to be exported b. Only objects changed before, after, or on a particular date and time to be exported

Performing an Application Folder Migration

To perform a migration, export objects from the source repository into a CDF file. Use the data in the CDF file to import data into other Workgroup repositories using the procedures described in Importing Migration Objects.

Importing and Exporting Using CDIF

Case Data Interchange Format (CDIF) is an industry-standard protocol supported by Workgroup that moves individual objects or entire hierarchies between repositories. When performing an export using the Application Folder tool, data is written to a file with a CDF extension. CDF is a shortened version of CDIF. Use CDIF to: Export objects and their hierarchies from a Workgroup repository into other CASE tools Import data from other CASE tools that support the CDIF standard Exchange data between Workgroup repositories residing on different platforms CDIF is not a full migration tool because it does not perform impact analysis on imported objects. Imported objects are either created or updated. CDIF merges the imported objects with those objects already in the repository. Additionally, CDIF does not indicate that an object has been deleted in an imported file. When importing data, CDIF is restrained by the security permissions of the user specified in its parameters. If CDIF tries to update an object to which a user is not authorized, the update will fail. If CDIF encounters security failures it does not interrupt the import of authorized objects but waits until the import is complete to report the failures. Objects updated by the import retain the project and user

AppBuilder 2.1.0 Workgroup Repository Administration Guide

5-31

Importing Application Folder Data

ownership attributes they had before the import started. Objects created during the import are assigned ownership attributes using the following criteria: Designated by the import file or Designated by the current project of the user who is invoking CDIF

CDIF Command Line Export for Windows

In addition to using the Freeway Explorer interface, objects can be exported using CDIF from the Windows client command line. The executable file for Windows is CDIFOUT.EXE located in AppBuilder\NT\SYS\BIN. The command line format is: cdifout <scope_name> <object_type> <object_name> <cdif_export_file> <cdif_log_file>[-u<userid>] [-p<password>] The parameters for this command are described in Table 5-12.
Table 5-12 Windows CDIF Export Command Parameters Parameter <OBJECT_TYPE> <object_ name> <cdif_ export_ file> <userid> <password> Explanation Repository type of the root of the export hierarchy. You must type this parameter in uppercase. Name of the repository object at the root of the exported hierarchy. This is the name as it would appear in the Construction Workbench tools. Full or relative path name of a new or existing file where the export will be written. UserID used to access the repository. Password used to access the repository.

CDIF Command Line Import for Windows

AppBuilder provides a CDIF import command for the Windows client that can be run from the command line. The executable file for Windows is CDIFIN.EXE located in AppBuilder\NT\SYS\BIN. The command line format is: cdifin <cdif_import_file> <cdif_log_file> [-u<userid>] [-p<password>] [-S] The parameters for the CDIFIN.EXE command line are described in Table 5-13.
Table 5-13 Windows CDIF Import Command Parameters Parameter <cdif import file> <cdif log file> <userID> <password> [-S] Explanation Full (or relative path name) of the file to be imported. Full (or relative pathname) of a writable file to which the import writes its actions and a logfile. UserID to be used to access the repository. Password to be used to access the repository. Specifies that the project and user ownership attributes assigned to objects created during the import match the attributes of the user specified on the command line. If not included in the command, the ownership attributes default to those specified in the import file.

5-32

Moving Data Between Repositories

CHAPTER

ADMINISTERING REPOSITORIES

AppBuilder 2.1.0 Workgroup Repository Administration Guide

The Workgroup administrator archives, performs backups, and restores the contents of a repository using Freeway Manager. The specific method of performing these functions depends on the requirements of the Workgroup environment; for example, one process may emphasize speedy processing while another provides greater security. The purpose of the backup dictates whether a simple generated export is sufficient or the entire database needs to be included. This chapter outlines various procedures available to the Workgroup administrator for archiving and recovering repositories. The Workgroup repository system administrator: Archives and restores the Workgroup repository and development environment Manages projects, repositories, and users Procedures used to administer repositories include: Using the Archive and Restore Utilities Performing a Rollback Using the Import/Export Utility Maintaining a Repository For additional detailed information on using Freeway Manager, see Using Freeway Manager and Utilities.

Using the Archive and Restore Utilities

Use the Archive and Restore utilities in Freeway Manager for routine archiving and restoring of the repository. The Archive and Restore utilities include information related to the Workgroup database, as well as information included in the tables within the database. Use these utilities when archiving, backing up or restoring a Workgroup server repository and the database.

Note

For transferring data to and from systems on different platforms, use the Import and Export utilities.

AppBuilder 2.1.0 Workgroup Repository Administration Guide

6-1

Using the Archive and Restore Utilities

The topics in this section outline procedures for: Archiving Data Restoring Data Importing and Exporting Data Using the Import Utility Using the Export Utility Performing Repository Maintenance for Oracle

Archiving Data
Perform archiving only on a database that is not active. Ensure that no users are accessing the Workgroup repository. The Archive/Restore window has tabs that contain fields to define the repository to be archived and requires security authority, as shown in Figure 6-3. Procedure - Archiving a Repository 1. Select Start > Programs > AppBuilder > Freeway > Freeway Manager. The Freeway Manager window opens (Figure 6-1).
Freeway Manager Window

Figure 6-1

2.

Select Repository > Archive/Restore (Figure 6-2). The Repository Archive/Restore window opens (Figure 6-3).

6-2

Administering Repositories

Using the Archive and Restore Utilities

Figure 6-2

Repository Menu

3.

Log into the repository and select the archive and target or working directory to create the archive. Click Archive. You can also click View Log to see the results of the archive process from previous archived files.

Figure 6-3

The Archive/Restore Window

Using the Archive Command Line to Create a Database Archive

To create a database archive file, type the following command at the command line: greadmin -A <archive_file_name> <dba_userid> <dba_password> When creating a database archive file, the archive file name must be a full path name. If the system responds with an error (for example, an active session or an uncommitted repository), type the following command: greadmin -A -T <archive_file_name> <dba_userid> <dba_password>

AppBuilder 2.1.0 Workgroup Repository Administration Guide

6-3

Using the Archive and Restore Utilities

The -T option includes the tipfile, so all appropriate objects are rolled back when the repository is restored.

Note

A database name is not necessary in the archive command because the HPS.INI variable DBM_DATABASE is aware of this information. Additionally, if the path variables are set correctly, execute the GREADMIN command from any directory.

The archive file (*.ZIP) should contain at least two(2) of the following files:
<dbm_database>.$$$ FILES.$$$ TIPFILE.$$$ (optional) The <dbm_database>.$$$ is the archived database. The FILES.$$$ contains the repository files (drawings, text, rule source, and so forth). The TIPFILE.$$$, if present, is the tipfile. The tipfile is a file in which the state of the active sessions in the repository is stored.

Using the Archive Utility with SQL on Windows Use the Archive tab to backup the entire repository into archive files. The archive utility creates a single ZIP file. The data in the archive files is written in a format that can only be read into a repository that uses SQL Server for Windows that is configured identically to the repository the archive was created on.

Note
4.

Make sure that no changes are being made to the repository.

Follow the procedure outlined in Procedure - Archiving a Repository.

Information about the archive or restore operations is written to the following file: <drive>:\AppBuilder\nt\sys\bin\greadmin.log where <drive> is the drive that Workgroup repository software is installed on. Subsequent archive or restore operations will overwrite the information in this file.

Note

Restoring Data
Use the Restore tab to restore data in the Workgroup repository. The Restore utility actually restores the Workgroup database in an SQL Server and then populates the Workgroup tables with the stored repository information.

Note

The process of restoring a repository from an archive can only be performed on a non-active database. Make sure that no users are accessing the Workgroup repository when restoring.

Restoring the SQL Workgroup Repository on Windows Restoring a Database Repository on Windows Import Example Using the Command Line Export Example Using the Command Line

6-4

Administering Repositories

Using the Archive and Restore Utilities

Figure 6-4

The Restore Window

Restoring the SQL Workgroup Repository on Windows

Warning
1. 2. 3. 4.
This operation overwrites any data in the existing repository.

Shut down the Workgroup repository. Type the <userID> and <password> of an SQL Server system administrator. Type the path and name of the archive file. If the file already exists, click ... (Browse) to select the file and overwrite it. Click Restore.
The Restore utility expects the character set of the active SQL Server to be consistent with the character set of the database stored with the archived ZIP file. For example, if the stored database is from a 437 US English SQL Server, then the SQL Server on which the repository is being restored should be a 437 US English SQL Server. If necessary, use the Import/Export utility to store the repository contents in a platform- and database-independent format

Warning

Note

Information about the restore operation is written to the following file: <drive>:\AppBuilder\nt\sys\bin\greadmin.log where <drive> is the drive on which the Workgroup repository management software is installed. Subsequent restore operations will overwrite the information in this file.

Restoring a Database Repository on Windows

To restore a Windows database, the <dbm_database>.$$$ file moves to the DBBACKUP directory under \AppBuilder\AD\DBBACKUP\dbm_database and is restored.

AppBuilder 2.1.0 Workgroup Repository Administration Guide

6-5

Performing a Rollback

The associated files move to the directory specified in the HPSINI file section [Workgroup] variable FILE_DIR. The tipfile is copied to the HPSINI file section [FREEWAY_SERVER] variable TIP_DIR.

Note

The restore process can be called from any directory, but must always specify an explicit path for the file to be restored.

Performing a Rollback
In the event of an unplanned disconnection, Workgroup Manager rolls back any uncommitted work in the repository. Workgroup Manager may be unable to perform this type of rollback for a given session, for example, if the tipfile for the Workgroup repository is damaged. If there is outstanding work that Workgroup Manager was unable to roll back, an entry appears in the list view for the session during which the work was performed. The entry has a red stop sign icon and the message: Not in TIP file appears under the Current Activity column. The Status Details tab shows sessions that have uncommitted work. When you display this tab, first press Refresh and the information will appear. Procedure - To roll back an uncommitted session 1. Open a Windows command prompt.
Windows Command Prompt

Figure 6-5

2.

Change to the following directory: <freeway_home_dir>\nt\sys\bin

3.

Type the following command: gresrvnt -r -i<Session_ID> -u<userid> -p<password> <userid> and <password> are the userID and password of a user with full access to the Workgroup repository database. <Session_ID> is the session containing uncommitted work to be rolled back. For example: gresrvnt -r -i4 -usa -p

4.

After performing a manual rollback, click Refresh again to confirm that the rollback was successful.

6-6

Administering Repositories

Using the Import/Export Utility

Using the Import/Export Utility

The Import/Export utility allows the Workgroup administrator to import and export data to or from the Workgroup repository. The Import/Export utility does not backup and restore the database, rather it extracts the contents of the Workgroup tables into an independent format that is transferred between or across platforms. Display the Repository Import/Export window by selecting Import/Export from the Repository menu in Freeway Manager.

Tip

For best results, use these utilities only to transfer data to and from systems on different platforms. For routine archiving of the repository, use the Archive/Restore utilities that include a backup of the Workgroup database itself.

This topic includes: Importing and Exporting Data Using the Import Utility Using the Export Utility

Importing and Exporting Data

Use the Import and Export utility to transfer data to and from systems on different platforms. For routine archiving of the repository, use the Archive and Restore utility.

Caution

Make sure you have the latest package release and Fixpack level of the product before running the Workgroup repository utility (FWYUTIL).

The syntax for this program is as follows: fwyutil -e|-i -n<exp filename> [-w<work_dir>] [-l<log>] -u<userID> -p<password> [-c<#>] where: <exp filename> is the name of the export file exported to. <work_dir> is a temporary directory used to store files created during the export operation. If this directory is not specified, the files are stored in the current working directory. <log> is the name of the log file where information about the import or export is stored. If the log name is not specified, the information is stored in either import.log or export.log in the current working directory. <userID> is the userID <password> is the user password <#> is the number of object inserts between database commit operations The command line switches are described in Table 6-1.
Table 6-1 Switch -e -i -n Switches and Functions Function Perform an export Perform an import Full file path & file name for Import/Export compressed data file

AppBuilder 2.1.0 Workgroup Repository Administration Guide

6-7

Using the Import/Export Utility

Table 6-1 Switch -w -l -u -p

Switches and Functions (Continued) Function Working directory for temporary files created/deleted by fwyutil Log file name for the fwyutil Import/Export log UserID for the Workgroup Administrator Password for the Workgroup Administrator The number of inserts before a database commit (optional). Use this option if you have a large repository but a small amount of space allocated to the transaction log. This option enables database cleaning during the fwyutil import by triggering a database commit after a specified number of object inserts.

-c

Using the Import Utility

Use the Import tab in Freeway Manager to import data stored in data files into the Windows Workgroup. The information in the EXP file to be imported includes the contents of the Workgroup tables and associated flat files with rule source code and window panel information. Procedure - Importing Data 1. Select Repository > Import/Export in the Freeway Manager window (Figure 6-6).
Import/Export Menu

Figure 6-6

2.

The Import window opens (Figure 6-4). Click the Import tab.

6-8

Administering Repositories

Using the Import/Export Utility

Figure 6-7

The Import Window

3.

Shut down the Workgroup repository.

This operation overwrites any data in the existing repository.

Warning
4. 5. 6.

Type the <userID> and <password> of an SQL Server system administrator. Type the path and filename of the EXP file that contains the data files. If the file already exists, click ... (Browse) to select it and overwrite the file. Click Import.
Information about the import operation is written to the following file: <drive>:\AppBuilder\nt\sys\bin\import.log where <drive> is the drive on which Workgroup repository management software is installed. Subsequent import operations overwrite the information in this file.

Note

Import Example Using the Command Line

To import data from a file called MYEXPORT.EXP in the root directory using a working directory called D:\TEMP, type: fwyutil -i -nD:\MYEXPORT.EXP -wD:\TEMP -lD:\MYIMPORT.LOG -u<userID> p<password>

Using the Export Utility

Use the Export tab to export data from the Workgroup repository into data files. The Export utility creates the data files and then compresses them into a single file with an EXP extension. The data in this
AppBuilder 2.1.0 Workgroup Repository Administration Guide 6-9

Using the Import/Export Utility

file is written in a format that can be read by Workgroup repository management software on other operating system platforms.

Note

Information about the export operation is written to the following file: <drive>:\AppBuilder\nt\sys\bin\export.log where <drive> is the drive on which Workgroup repository management software is installed. Subsequent export operations overwrite the information in this file.

Procedure - Exporting Data 1. Select Repository > Import/Export and click the Export tab. The Export window opens (Figure 68).
The Export Window

Figure 6-8

Warning
1. 2. 3.

Make sure that no changes are being made to the repository during this operation

Type the <userID> and <password> of an SQL Server system administrator. Type the path and name of the EXP file that contains the data files. If the file already exists, click ... (Browse) to select it and overwrite the file. Click Export.

Export Example Using the Command Line

To export data into a file called MYEXPORT.EXP in the root directory using a working directory called D:\TEMP, type the following (substituting your own userID and password for UID and PW):

6-10

Administering Repositories

Maintaining a Repository

fwyutil -e -nD:\MYEXPORT.EXP -wD:\TEMP -lD:\MYEXPORT.LOG u<userID> -p<password>

Maintaining a Repository
Perform maintenance activities for the Workgroup repositories on a regular basis. Specific required activities depend upon the operating and installation environment. For steps to improve the efficiency of repository access and storage, see Appendix A, Performance Tuning.

Performing Repository Maintenance for Oracle

The Workgroup repository does not require any maintenance, other than monitoring the amount of free space available and adding space as required. For more information on maintenance for Oracle, refer to the Oracle Server Administration Guide.

AppBuilder 2.1.0 Workgroup Repository Administration Guide

6-11

Maintaining a Repository

6-12

Administering Repositories

APPENDIX

PERFORMANCE TUNING

AppBuilder 2.1.0 Workgroup Repository Administration Guide

This appendix describes how to improve the efficiency of repository access and storage for SQL Server and Oracle. The following steps are only recommendations. Performance tuning procedures vary from system to system depending on many factors, such as the amount of memory available, hard drive specifications, processor speed, and the type of data being stored. For more information on performance tuning and procedures, consult a qualified Database Administrator (DBA) familiar with your system and database. Performance tuning procedures include: Improving SQL Server Response for Workgroup Tuning Performance for Oracle Reindexing and Packing a Repository Understanding Date Support Adding Applications to Freeway Explorer

Improving SQL Server Response for Workgroup

SQL Server issues have developed when using Workgroup repositories for Windows 2000 with more than one user. The most common problems encountered are performance issues and disk space deficiencies due to frequent filling of the master database SYSLOGS segment. To address these issues, this section provides Workgroup repository enhancement tips, for example, defining temporary database settings (tempDB), modifying various Workgroup and SQL Server settings, management of transaction logs, and scheduling batch jobs. . These recommendations include: Using Temporary Database (tempDB) Increasing Memory Allocation Setting Number of User Connections Changing Windows Process Priority Clearing Transaction Logs (SYSLOGS)

AppBuilder 2.1.0 Workgroup Repository Administration Guide

A-1

Improving SQL Server Response for Workgroup

Using Temporary Database (tempDB)

One way to improve SQL Server response when using a Workgroup is to use the temporary database (tempDB). The temporary database is used for work space to sort and create temporary tables for some join operations. SQL Server provides the option to store the tempDB in RAM, as opposed to writing it to a table. In many situations, this enhances performance significantly. However, if used inappropriately, it can consume memory, making memory unavailable for other system processes, thereby degrading performance. The following guidelines help avoid that occurrence. Procedures - Setting tempDB RAM Storing tempDB in RAM Follow this procedure for storing tempDB in RAM. 1. 2. Store tempDB. The default of tempDB in memory is none. Change this setting to 10 MB or more, depending on available memory. Subsequent duplicate requests are cached in memory instead of being written to the drive and are sent more quickly. A tempDB setting of zero is the default.
Microsoft SQL server has editable settings to optimize performance. Unfortunately, setting the tempDB variable over your maximum RAM will disable SQL server (making the interface required to change it inaccessible). If you allocate more memory than is available, SQL Server will not restart. Follow the steps described in Procedures - Setting tempDB RAM to fix the problem without requiring a rebuild of the master database.

Warning

Modifying tempDB Settings Follow this procedure for modifying tempDB settings. 1. 2. 3. 4. 5. Type <sqlservr -c -f> on the command line to start in single user mode. Go into ISQL. Type <sp_configure "tempdb in RAM"> and execute. Type <sp_configure "tempdb in RAM" ,0> and execute. Type <reconfigure with override> and execute. This will reset it to 0.

Increasing Memory Allocation

To improve SQL Server response when using Workgroup, increase the default memory allocation for SQL Server in the SQL Server configuration parameters. The increase cannot exceed 80 percent of the total memory for the machine.

Note

Default memory is measured in 2 MB increments; not 1MB increments.

A-2

Performance Tuning

Improving SQL Server Response for Workgroup

Procedure - Increasing the Default Memory Allocation 1. 2. 3. 4. 5. Change the setting in Enterprise Manager under:
Console Root\Microsoft SQL Servers\SQL Server Group\Configuration\server_name

Right click and select Properties. Click on the Memory Tab (or from the Management Console, select the machine_name and then Tools from the menu). Select SQL Server Configuration properties. Select the Memory tab.

Setting Number of User Connections

One way to improve SQL Server response when using Workgroup is to set the number of user connections optimally. For Workgroup logins, validate that the User Connections setting is at a high enough level to support all of the AppBuilder client requests. This setting is similar to the available sessions in Workgroup repository settings, averaging three (3) settings per client machine. For example, ten (10) client workstations using AppBuilder should have a user connection setting of at least 45. Procedure - Setting the Number of Users 1. Change the setting in Enterprise Manager under: Console Root\Microsoft SQL Servers\SQL Server Group\server_name 2. 3. 4. 5. Right click and select Properties. Click on the Connection tab (or from the Management Console, select the machine_name and then Tools from the menu). Select SQL Server Configuration properties. Select the Connection tab.

Changing Windows Process Priority

To improve SQL Server response when using Workgroup, increase the priority. Each Workgroup process thread (GRESRVNT.EXE) can have its priority changed from normal to high.

Warning

Windows warns you that changing priority may cause undesirable results including system instability. Proceed with caution.

Procedure - Increasing Windows Priority Increase the priority of the Workgroup on Windows under Task Manager to get more CPU cycles. 1. 2. Select gresrvnt.exe, right click, and choose Set Priority. Select High priority.

AppBuilder 2.1.0 Workgroup Repository Administration Guide

A-3

Improving SQL Server Response for Workgroup

Clearing Transaction Logs (SYSLOGS)

One way to improve SQL Server response when using Workgroup is to clear the transaction logs. The Workgroup Transaction log fills up quickly, as does the Master Transaction log of the master database, impacting Workgroup performance negatively. If the Workgroup log fills, Workgroup performance degrades and speed declines. If the Master log fills, SQL server will not start and may become disabled

Warning

Delete the Workgroup transaction log regularly to avoid performance problems.

If the log is full, SQL Server gives the following error message: Cant allocate space for object syslogs in database <database name> because the logsegment segment is full. If you ran out of space in Syslogs, delete the transaction log. Otherwise, use ALTER DATABASE or sp_extendsegment to increase the size of the segment. Two options are available to correct the error: Clear the log completely or Extend the segment. Procedure - Clearing the Workgroup and Master Transaction Logs 1. 2. To clear the log, delete the Workgroup and Master Transaction Log. Open ISQL/W and type: DUMP TRANSACTION <database name> WITH NO_LOG. Execute the command. This is an unrecoverable log dump.
With successful execution, the system displays a message indicating that the action returned no data. Shut down SQL server and restart to see the effects.

Note

Extending the Workgroup and Master Transaction Log Segments

To extend the segment, use the SQL stored procedure sp_extendsegment.

Clearing the Log to Start SQL

If SQL Server will not start, clear the log using the following procedure: 1. Type: <sqlservr -c -f> on the command line. 2. 3. Go into ISQL. (Type ISQL/? for Help). Type: C:\> ISQL Usa P QDUMP TRANSACTION MASTER WITH NOLOG 4. To stop and restart SQL Server, type: net stop mssqlserver net start mssqlserver

A-4

Performance Tuning

Tuning Performance for Oracle

Tuning Performance for Oracle

The following sections discuss performance tuning steps that improve the efficiency of repository access and storage for Oracle databases. These include: Tuning Disk Storage Optimizing Oracle Instance Parameters More information on tuning performance for Oracle can be found on the Internet at the Oracle Web site. The following document may also be helpful to users who want to learn more about Oracle database tuning. Oracle Tuning, Release8 A58246-01

Tuning Disk Storage

A simple way to improve efficiency of repository access and storage for Oracle databases is to tune the disk storage. Oracle enables key data files to be spread across several disks. Consequently, when multiple users access the repository, connection to the database occurs across different physical disk drives. Disk contention can occur, however, if there is a conflict between the Oracle data files and the Workgroup files. Minimize disk contention by using disk allocation planning during installation. For optimal results, use separate physical disk drives for the following: Workgroup Installation Software Choose the drive where Workgroup repository management software is installed at installation. Workgroup Repository File Storage The default drive and directory for Workgroup repository file storage is <freeway_user_home>/freeway/ FILES. Change this location by editing the HPS.INI file created during installation. The parameter to change in HPS.INI is FILE_DIR, located in the [FREEWAY] section of the INI file.

Note

Do not select a directory unless it already exists.

Do not change this setting after a repository has been unarchived and used, or data may be lost. However, this setting can be changed after Workgroup repository management software is installed and before the repository is restored. Oracle Data Files for the Oracle Instance When installing the Oracle database, minimize disk contention by spreading Workgroup data files across physical disks. Three disk devices are recommended for the data files for HPS_TS and HPSIDX_TS tablespaces. The provided script, crtables.sql, enables different physical disk devices for the tablespaces to be specified. Using logical partitions is supported but does not boost performance as successfully as using physical partitions.

Optimizing Oracle Instance Parameters

One way to improve efficiency of repository access and storage for Oracle databases is to optimize the instance parameters. Change Oracle instance parameters that affect the performance of repository access

AppBuilder 2.1.0 Workgroup Repository Administration Guide

A-5

Tuning Performance for Oracle

by modifying the initialization file init<ORACLE_SID>.ORA, located in the <ORACLE_HOME>/dbs directory. After the parameters are modified, shut down the Oracle instance and restart for the values to take affect. For more information, refer to the Oracle Server Administrators Guide. Set the following parameters to small, medium, or large values. These values are based on the size of the instance. For Workgroup repository management software, set these values based on the size of the Workgroup repository.
Table A-1 Parameter DB_FILE_MULTIBLOCK_READ_COUNT DB_BLOCK_BUFFERS SHARED_POOL_SIZE PROCESSES DML_LOCKS LOG_BUFFER SEQUENCE_CACHE_ENTRIES SEQUENCE_CACHE_HASH_BUCKETS Values for Oracle Instance Parameters Small 8 200 3500000 50 100 8192 10 10 Medium 16 550 6000000 100 200 32768 30 23 Large 32 3200 9000000 200 500 163840 100 89

Monitoring the instance during peak usage helps determine the impact of modifying the initialization parameters for the instance. There are three areas that affect the performance of the instance: Library Cache Parameters Buffer Cache Parameters Disk I/O Parameters

Library Cache Parameters

The library cache is an area of shared memory that Oracle uses to hold SQL requests and access plans common to users currently connected to Oracle. An SQL request executes faster if its access plan is in the cache. If the access plan is not in the cache, the request executes more slowly because the access plan has to be calculated by the Oracle access optimizer. Modify the library cache parameter, SHARED_POOL_SIZE. This parameter controls the amount of memory allocated for caching the library and the data dictionary.

Buffer Cache Parameters

The buffer cache is an area of shared memory that Oracle uses to store information that is frequently requested. SQL requests execute faster when this information is in the cache. Modify the buffer cache parameter, DB_BLOCK_BUFFERS. This parameter controls the System Global Area (SGA) the Oracle database server uses for storing and processing data in memory. When data is requested, the server puts that data into memory so it can access the data more rapidly the next time it is requested. If the setting is too low, the server flushes the least recently-used data from memory too soon. So the next time it is requested, the server reads it from disk rather than memory, thereby slowing performance. On the other hand, if the value is set too high the system has insufficient memory to operate efficiently.

A-6

Performance Tuning

Tuning Performance for Oracle

Disk I/O Parameters

Modify the disk input/output parameter, SORT_AREA_SIZE. This parameter allocates memory for sorting. The number of bytes allocated for this parameter governs the amount of memory each user has for sorting. If the server cannot perform the sort in memory, it allocates temporary segments on disk for holding intermediate runs, increasing I/O. Set the value of this parameter high enough to prevent the constant generation of temporary segments and simultaneously reserve enough memory for other processes. The v$sysstat table tallies the percentage of sorts the server performs in memory and on disk. Using ESTAT/BSTAT helps find sorting that is performed in memory. Be careful increasing this parameter because it is a per user value. In a per user value, the size of the value is set by the DBA.

Checking the Size of the Data Files for an Oracle Instance

To check the percentage used by the Oracle tablespaces, execute the following SQL query: SELECT SUBSTR( D.TABLESPACE_NAME, 1, 15 ) TSPACE, D.BYTES / 1024 / 1024 TOT_MB, D.BYTES / 2048 ORA_BLKS, SUM( E.BLOCKS ) TOT_USED, ROUND( SUM( E.BLOCKS )/( D.BYTES / 2048 ),4) * 100 PCT_USED FROM SYS.DBA_EXTENTS E, SYS.DBA_DATA_FILES D WHERE D.FILE_ID = E.FILE_ID GROUP BY D.FILE_ID, D.TABLESPACE_NAME, D.BYTES; This query displays the percentage used by each data file for a tablespace.

Note
Table A-2 TSPACE SYSTEM RBS TOOLS HPS_TS HPS_TS

Data files that have not been used do not appear. Oracle Tablespace Parameters TOT_MB 15 4 5 7 6 7 6 ORA_BLKS 7680 2048 2560 3584 3072 3584 63072 TOT_USED 3873 1430 45 1460 420 415 1225 PCT_USED 50.53 69.82 1.76 40.74 13.67 11.58 39.88

HPSIDX_TS HPSIDX_TS
:

Table 1-3 Heading TSPACE TOT_MB

Oracle Parameter Definitions Definition The name of the tablespaces Total MB allocated for the instance data file Number of Oracle blocks allocated for the instance data file Number of Oracle blocks used by the instance data file Oracle blocks used divided by total number of Oracle blocks allocated

ORA_BLKS TOT_USED PCT_USED

Note

Because the Workgroup repository uses multiple data files for the same tablespace, there will be multiple listings of the tablespace name in the query output.

If the tablespace is approaching 100 percent, then add another data file to the tablespace. See the Oracle Server Administrators Guide for details on how to add a data file to an existing tablespace.

AppBuilder 2.1.0 Workgroup Repository Administration Guide

A-7

Reindexing and Packing a Repository

Reindexing and Packing a Repository

The Workgroup Repository has packing and reindexing utilities. These utilities provide a method to clean up repositories in use for extended periods of time. Reindexing a Repository and Packing a Repository describe specific procedures for repository maintenance using reindex and pack utilities.

Warning

Ensure that a reliable backup of the repository is completed and available before running a Workgroup utility.

Reindexing a Repository
Reindexing a repository drops and recreates all of the current indexes placed on Workgroup repository tables. It is recommended that you reindex repositories that have been used for long periods of time or just restored using the fwyutil command. The Workgroup administrator manages reindexing using the following procedures:

For Windows 2000 systems:

Use the Freeway Manager interface to reindex a repository. 1. 2. Select Start > Programs >AppBuilder >Freeway > Freeway Manager. From the menu, select Pack & Reindex. The Pack & Reindex window opens (Figure 1-1).
Pack & Reindex Dialog

Figure 1-1

3. 4. 5. 6.

The Database Pack & Reindex dialog requires a user login ID and password. Select the check box for Pack or Reindex for your repository database. Type in or use the browser button to search for your working directory. Click Execute.

Packing a Repository
Packing a repository deletes all the rows in the Workgroup tables that are marked as deleted and all rows not marked as the most recent. Normally, these rows are not literally deleted from the database when the

A-8

Performance Tuning

Understanding Date Support

objects are deleted from the repository. By packing the database, these rows are actually deleted out of the tables, freeing up drive space.

For Windows 2000 systems

1. 2. Use the Reindexing a Repository procedure and select the Pack check box. Click Execute.

Understanding Date Support

The AppBuilder DATE data type allows you to store and manage four-digit year dates within an AppBuilder application. The DATE variable has a length of 4 bytes and the value of the variable is the number of days since the date of origin, January 1, 0000. The DATE data type also provides accurate support for leap years.

Using Repository Dates

In AppBuilder, the repositories maintain only the last two YY digits for the year in their audit fields. In most cases, it does not impact the migration, since most comparisons are based on an equality rather than greater or lesser than criteria.

Migrating Data between Dates

To migrate data residing in a Workgroup repository on Windows 2000, use the migration function of Freeway Explorer. To migrate all objects between 99/10/01 - 00/03/31 (October 1, 1999 through March 31, 2000), the migration is handled in two stages: The first migration specifies After 99/10/01 (October 1, 1999 through December 31, 1999). The second migration specifies Before 00/03/31 (January 1, 2000 through March 31, 2000). The Workgroup migration process evaluates the object date maintained field.

Note

If you have developed unique repository utility applications using the Workgroup APIs, you will need to provide support for handling the two-digit year field because the repositories only store the last two YY digits of the year.

Adding Applications to Freeway Explorer

Freeway Explorer allows you to integrate tools that you have created into Freeway Explorer. To create a tool that is compatible with Freeway Explorer, you must use MFC Visual C++ 5.0 and the Freeway API. See Creating Add-in DLLs for more information.

AppBuilder 2.1.0 Workgroup Repository Administration Guide

A-9

Adding Applications to Freeway Explorer

Adding a Function Name

Use the Add-in Function Registration window to add functions from a Freeway compatible DLL file. Procedure - Adding a Function Name To add functions: 1. Select Tools > Add-ins... (Figure 1-2). The Add-in Function Registration window opens.
Edit Menu Figure 1-2

2.

Select Edit > Add (Figure 1-3).

Add-in Function Registration Window

Figure 1-3

3.

Select a DLL file that is compatible with the Freeway Add-in format and click Open. The functions contained in the DLL directory appear in the Available Functions window.
DLL List

Figure 1-4

4.

If the DLL file you select is not compatible, an error dialog will alert you (Figure 1-5).
DLL Incompatible Error Message

Figure 1-5

A-10

Performance Tuning

Adding Applications to Freeway Explorer

5.

Select the function names you want to add and click Select. The selected functions appear in the Add-in Function Registration window.
Available Functions Window

Figure 1-6

6.

Select File > Exit to save the functions you have added.

Deleting a Function Name

Use the Add-in Function Registration window to delete functions. 1. To delete a function name from the Add-in Function Registration window, select the function name and select Edit > Delete.

Creating Add-in DLLs

You can add your own tools (in the form of DLLs) to Freeway Explorer. For example, you can write a tool that accesses a Workgroup session or that uses Workgroup repository objects. To create a DLL that is compatible with Freeway Explorer, you must use MFC Visual C++ 5.0 and the Freeway API. Furthermore, you must make sure that the program has the following three functions: 1. 2. 3. GetAllFunctions()(This function must appear once in each created DLL.) <functionName>Init()(These two functions must both appear for each Add-in tool <function name>Function() you define in the DLL.)

Each function must have the following C-compatible function definition (refer to the DLL Add-in Samples): extern "C" void <some kind of export> <function_name> [<args>]

AppBuilder 2.1.0 Workgroup Repository Administration Guide

A-11

Adding Applications to Freeway Explorer

GetAllFunctions()
This function must be laid out exactly as it appears in the DLL Add-in Samples. For each process that the DLL contains, four conditions must be met: a. You must allocate a FunctionHeader object (see fwyaddin.h). b. You must allocate and assign an MFC CString object with the <functionName>. This <functionName> is used to derive the names of associated functions. For example, if the function name is Mystring, then the associated function names would have to be MystringInit and MystringFunction c. You must allocate and assign an MFC CString object with the description of the function. d. You must add the FunctionHeader object to the CPtrArray that was passed to GetAllFunctions. As you add FunctionHeaders to the CPtrArray, they are passed back to Freeway Explorer, and presented to the user when he selects this DLL.

<functionName>Init()
This function takes an argument of AddInStruct (see fwyaddin.h). The function populates the following information: Function Type Function Menu Name Function Sub-menu Name Function Location on the Sub-menu Name Function Type All functions take a session pointer and the Freeway Explorer's CWnd * as arguments; but some functions may also need a seed object pointer as an argument. These functions can be broken down into the types described in Function Types:
Table A-4 Type 1 Type 2 Type 3 Function Types Action takes no objects as arguments The function takes an fwyHANDLEobject as an argument The function takes a bag of fwyHANDLEobjects as an argument.

In the sample DLLs, AppFolderImport is of Type 1, because it needs no arguments, whereas CreateNewBrowser is a Type 2 because it takes one object as an argument. TEST is a Type 3 because it uses a CArray of <objects>. Function Menu Name The menu name if it will be a menu item; the pop-up menu name if it will be a sub-menu item. For example, AppFolderImport appears in the tools menu, so it's title is in this parameter. However, MigrationExportCreate is a sub-menu item under the Migration Export sub-menu, so the sub-menu title goes in this parameter.

A-12

Performance Tuning

Adding Applications to Freeway Explorer

Function Sub-menu Name An MFC CString MUST be allocated here, even if it is a null string. For example, the function AppFolderImportInit is available from the tools menu, but does not have any sub-menu choice; nevertheless, a null string must appear in: functionStructure->subname=new Cstring() Function Location on the Sub-menu Name If you have three items on a sub-menu, you must set the order (beginning with 0) for each of them. For example, Migration Export has 3 submenus: Create, Open, and Remove. The functionStructure>locations= identifier for these submenus would respectively have to be 0, 1, and 2.

<function name>Function()
This function takes whatever arguments are listed in the Function Type. It then kicks off the specified add-in function. See DLL Samples.

Additional Information
When you select a window choice from the Freeway Explorer Tools menu, the name of that window dynamically appears at the bottom of the Tools menu. If you are linking a tool (and not a background process) as an add-in, and you want the tool name to appear at the bottom of the Tools menu after your tool is started, do the following: 1. 2. 3. Make sure your window has initialized. Make sure your function has a valid HWND. Perform the following send message to Freeway Explorer:

parent->SendMessage( WM_USER + 100, (WPARAM)0, (LPARAM)this ); where 'this' is an MFC CWnd pointer. To remove the same function from the bottom of the Tools menu, send the following message to Freeway Explorer: parent->SendMessage( WM_USER + 101, (WPARAM)this ); where ' this' is an MFC CWnd pointer.

DLL Add-in Samples

The following is sample C++ code that illustrates the structure that an add-in DLL must have to be compatible with Freeway Explorer: /******************************************************************** #include <stdio.h> #include "stdafx.h" #include "afxtempl.h" #include "fwyaddin.h" / *********************************************************************

AppBuilder 2.1.0 Workgroup Repository Administration Guide

A-13

Adding Applications to Freeway Explorer

Function: Purpose: Lets user know what functions are contained in Add-in DLL Notes: ********************************************************************/ extern "C" void __declspec(dllexport) GetAllFunctions( CArray *bag ) { //Return all function names and descriptions FunctionHeader *header = new FunctionHeader; header->functionName = new CString( "AppFolderImport" ); header->description = new CString( "Function imports application folders or files in the CDIF format"); bag->Add( header ); header = new FunctionHeader; header->functionName = new CString( "CreateNewBrowser" ); header->description = new CString( "Function brings up a new instance of the Browser tool"); bag->Add( header ); header = new FunctionHeader; header->functionName = new CString( "TEST" ); header->description = new CString( "A test program"); bag->Add( header ); header = new FunctionHeader; header->functionName = new CString( "MigrationExportCreate" ); header->description = new CString( "Function creates a new, unpopulated Freeway Migration object"); bag->Add( header ); } /******************************************************************** Function: Purpose: Notes: ********************************************************************/ extern "C" void __declspec(dllexport) AppFolderImportInit( AddInStruct *functionStructure ) { functionStructure->type = 1; functionStructure->name = new CString("App&lication Folder/CDIF Import..."); functionStructure->subname = new CString(""); functionStructure->location = 0; } /******************************************************************** Function: CreateNewBrowser Purpose: Notes: ********************************************************************/ extern "C" void __declspec(dllexport) CreateNewBrowserInit( AddInStruct *functionStructure ) { functionStructure->type = 2;

A-14

Performance Tuning

Adding Applications to Freeway Explorer

functionStructure->name = new CString("&Open Browser..."); functionStructure->subname = new CString(""); functionStructure->location = 0; } /******************************************************************** Function: Purpose: Notes: ********************************************************************/ extern "C" void __declspec(dllexport) TESTInit( AddInStruct *functionStructure ) { functionStructure->type = 3; functionStructure->name = new CString("TEST..."); functionStructure->subname = new CString(""); functionStructure->location = 0; } /******************************************************************** Function: Purpose: Notes: ********************************************************************/ extern "C" void __declspec(dllexport) AppFolderExportCreateInit( AddInStruct *functionStructure ) { functionStructure->type = 1; functionStructure->name = new CString("A&pplication Folder Export"); functionStructure->subname = new CString("&Create..."); functionStructure->location = 0; } /******************************************************************** Function: Purpose: Notes: ********************************************************************/ extern "C" void __declspec(dllexport) AppFolderImportFunction( CWnd *parent, void* session ) { CCdifImport *impFrame = new CCdifImport( parent, session ); int rc = impFrame->Create( 0, "Application Folder/CDIF Import", WS_VISIBLE | WS_OVERLAPPEDWINDOW ); } /******************************************************************** Function: CreateNewBrowser Purpose: Notes: ********************************************************************/ extern "C" void __declspec(dllexport) CreateNewBrowserFunction( CWnd *pMainParent,

AppBuilder 2.1.0 Workgroup Repository Administration Guide

A-15

Adding Applications to Freeway Explorer

void *session,

fwyHANDLEobject object ) { new CBrowser( pMainParent, session, object ); } /******************************************************************** Function: Purpose: Notes: ********************************************************************/ extern "C" void __declspec(dllexport) TESTFunction( CWnd *parent, void* session, CPtrArray *array ) { int index; int count; index = array->GetSize(); for( count = 0; count < index; count++ ) { fwyHANDLEobj obj = (fwyHANDLEobj)array->GetAt( count ); } }

fwyaddin.h
The following header file is supplied with Freeway Explorer: ******************************************************************** #ifndef FUNCTION_H #define FUNCTION_H #include <stdio.h> #include "stdafx.h" #include "afxtempl.h" typedef struct tagFunctionHeader { CString *functionName; CString *description; } FunctionHeader; typedef struct tagAddInStruct { int ID; //id of the menu pick ULONG dll; //pointer to the dll (for later deletion) char* function; //pointer to the function char* idleFunc; CString *fName; int type; CString *name; CString *subname; int location; //pointer to the function //function name //type of function //menu name //sub-menu name //if sub-menu, where in sub-menu

A-16

Performance Tuning

Adding Applications to Freeway Explorer

int successFlag; //is everything okay with this object int assigned; //Has this object been assigned an menu item } AddInStruct; typedef struct tagIdleFunctionStruct { char *function; char *rootWindow; } IdleFunctionStruct; typedef unsigned long typedef unsigned long ); typedef char CPtrArray *); typedef void #endif //FUNCTION_H

(*addInTool) (*addInToolWithObject)

( CWnd *, void * ); ( CWnd *, void *, long

*(*addInToolWithObjects)( CWnd *, void *, (*idleFunction) ( char * );

AppBuilder 2.1.0 Workgroup Repository Administration Guide

A-17

Adding Applications to Freeway Explorer

A-18

Performance Tuning

APPENDIX

B
Entity Event

CDIF FORMAT AND SAMPLES

AppBuilder 2.1.0 Workgroup Repository Administration Guide

This appendix describes the Case Data Interchange Format (CDIF) and provides samples of AppBuilder Information Model objects expressed in CDIF format. The entity types identified are: Attribute (or Property) Data type

Logical process Relationship State Transition Descriptive text for all object types In addition, the following relationship types are required to connect the entity types: Attribute is-typed-by data type Depends-on logical process Is-composed-of logical process Is-described-by attribute Is-preconditioned-by state Is-related-via relationship

CDIF Layout
The CDIF file layout consists of a header section followed by a contents section. The header section identifies the vendor and company. The contents section contains the objects being transferred. Each instance in the content section consists of its type, a unique ID (used for the purpose of the transfer only), and the transfer IDs of any objects it refers to. All references must be backwards in nature; that is, an object cannot refer to an object that has not been defined previously.

AppBuilder 2.1.0 Workgroup Repository Administration Guide

B-1

Sample CDIF Files

Generically, the content layout is: CDIF,SYNTAX "SYNTAX.1" "01.00.00",ENCODING "ENCODING.1" "01.00.00" ( HEADER ( USES ( CHARACTERSET PrintableASCII ) ( TEXTFORMAT Unformatted ) ) ( SUMMARY ( VendorCompany "Level 8 Technologies" ) ) ) ( MODEL ( <object type> <cdif transfer id> <optional parent transfer id> <optional child transfer id> ( <property name> <value of property> ) ( <...other properties>..> ) ( <...other objects...> ) )

Sample CDIF Files

The following CDIF files represent exports from AppBuilder. Note that the ShortName property value has been assigned. In an actual import, this property should not be set because it is generated automatically during the import procedure. See the following example files: Entity to Relationship (a) Entity to Relationship (b)

Entity to Relationship (a)

CDIF,SYNTAX "SYNTAX.1" "01.00.00",ENCODING "ENCODING.1" "01.00.00" ( HEADER ( USES ( CHARACTERSET PrintableASCII ) ( TEXTFORMAT Unformatted ) ) ( SUMMARY ( VendorCompany "Level 8 Technologies" ) ) ) ( MODEL ( "ENTITY" 16411 ( Name "CUSTOMER" ) ( ChangeNumber 0 ) ( ShortName "ZBV5NSN" ) ( Ent_Type "0" ) ( Exp_Min_Rows "00000" ) ( Exp_Max_Rows "0000000000" )

B2

CDIF Format and Samples

Sample CDIF Files

( ( ( ( (

Exp_Duration "1" ) Ave_Wkly_Inserts "0000" ) Ave_Wkly_Deletes "0000" ) Ave_Wkly_Updates "0000" ) Exp_Rows "0000000000" )

) ( "RELATIONSHIP" 16431 ( Name "ZBV5PSN" ) ( ChangeNumber 0 ) ( ShortName "ZBV5PSN" ) ( Cmpx_Indicator "0" ) ( Exp_Min_Rows "00000" ) ( Exp_Max_Rows "0000000000" ) ( Act_Period "1" ) ( Ave_Wkly_Inserts "0000" ) ( Ave_Wkly_Deletes "0000" ) ( Ave_Wkly_Updates "0000" ) ( Exp_Rows "0000000000" ) ) ( "IS_RELATED_VIA_RELATIONSHIP" 10043092 16411 16431 ( Sep_Id 1 ) ( SequenceNumber 0 ) ( ChangeNumber 0 ) ( Big "Y" ) ( Cardinal "1" ) ( Option "N" ) ( Dependent "N" ) ( Abstract "N" ) ( Role "places" ) ( Min_Cardinality "00000" ) ( Max_Cardinality "0000000000" ) ) ( "ATTRIBUTE" 16441 ( Name "FIRST_NAME" ) ( ChangeNumber 0 ) ( ShortName "ZBV5QSN" ) ( Attr_Derived "1" ) ) ( "IS_DESCRIBED_BY_ATTRIBUTE" 10043112 16411 16441 ( Sep_Id 0 ) ( SequenceNumber 10 ) ( ChangeNumber 0 ) ( Option "N" ) ) ( "DATA_TYPE" 16451 ( Name "NAME30" ) ( ChangeNumber 0 ) ( ShortName "ZBV5RSN" ) ( Type_Type "5" ) ( Type_Len "00030" ) ( Type_Frac "00" ) ) ( "ATTRIBUTE_IS_TYPED_BY_DATA_TYP" 10043122 16441 16451 ( Sep_Id 0 )

AppBuilder 2.1.0 Workgroup Repository Administration Guide

B-3

Sample CDIF Files

( SequenceNumber 10 ) ( ChangeNumber 0 ) ) ( "TEXT" -553 16411 ( Filetype 0 ) ( SPECIALATTR ( Filename #[ This text describes the customer entity. ]# ) ) ) )

Entity to Relationship (b)

CDIF,SYNTAX "SYNTAX.1" "01.00.00",ENCODING "ENCODING.1" "01.00.00" ( HEADER ( USES ( CHARACTERSET PrintableASCII ) ( TEXTFORMAT Unformatted ) ) ( SUMMARY ( VendorCompany "Level 8 Technologies" ) ) ) ( MODEL ( "ENTITY" 16421 ( Name "ORDER" ) ( ChangeNumber 0 ) ( ShortName "ZBV5OSN" ) ( Ent_Type "0" ) ( Exp_Min_Rows "00000" ) ( Exp_Max_Rows "0000000000" ) ( Exp_Duration "1" ) ( Ave_Wkly_Inserts "0000" ) ( Ave_Wkly_Deletes "0000" ) ( Ave_Wkly_Updates "0000" ) ( Exp_Rows "0000000000" ) ) ( "RELATIONSHIP" 16431 ( Name "ZBV5PSN" ) ( ChangeNumber 0 ) ( ShortName "ZBV5PSN" ) ( Cmpx_Indicator "0" ) ( Exp_Min_Rows "00000" ) ( Exp_Max_Rows "0000000000" ) ( Act_Period "1" ) ( Ave_Wkly_Inserts "0000" ) ( Ave_Wkly_Deletes "0000" ) ( Ave_Wkly_Updates "0000" ) ( Exp_Rows "0000000000" ) )

B4

CDIF Format and Samples

Sample CDIF Files

( "IS_RELATED_VIA_RELATIONSHIP" 10043102 16421 16431 ( Sep_Id 1 ) ( SequenceNumber 0 ) ( ChangeNumber 0 ) ( Big "N" ) ( Cardinal "N" ) ( Option "Y" ) ( Dependent "N" ) ( Abstract "N" ) ( Role "provided-for" ) ( Min_Cardinality "00000" ) ( Max_Cardinality "0000000000" ) ) ( "ATTRIBUTE" 16461 ( Name "ORDER_NUMBER" ) ( ChangeNumber 0 ) ( ShortName "ZBV5SSN" ) ( Attr_Derived "1" ) ) ( "IS_DESCRIBED_BY_ATTRIBUTE" 10043132 16421 16461 ( Sep_Id 0 ) ( SequenceNumber 10 ) ( ChangeNumber 0 ) ( Option "N" ) ) ( "DATA_TYPE" 16471 ( Name "NUMERICKEY" ) ( ChangeNumber 0 ) ( ShortName "ZBV5TSN" ) ( Type_Type "2" ) ( Type_Len "00015" ) ( Type_Frac "00" ) ) ( "ATTRIBUTE_IS_TYPED_BY_DATA_TYP" 10043142 16461 16471 ( Sep_Id 0 ) ( SequenceNumber 10 ) ( ChangeNumber 0 ) ) ( "TEXT" -1403 16421 ( Filetype 0 ) ( SPECIALATTR ( Filename #[ This text describes the ORDER entity. ]# ) ) ) ) 3.3 Logical process CDIF,SYNTAX "SYNTAX.1" "01.00.00",ENCODING "ENCODING.1" "01.00.00" ( HEADER ( USES ( CHARACTERSET PrintableASCII ) ( TEXTFORMAT Unformatted ) )

AppBuilder 2.1.0 Workgroup Repository Administration Guide

B-5

Sample CDIF Files

( SUMMARY ( VendorCompany "Level 8 Technologies" ) ) ) ( MODEL ( "LOGICAL_PROCESS" 16511 ( Name "PROCESS_ORDER" ) ( ChangeNumber 0 ) ( ShortName "ZBV5XSN" ) ( Description "Process the order for customer" ) ( LogPro_Type "1" ) ( LogPro_Mode "2" ) ) ( "LOGICAL_PROCESS" 16531 ( Name "ORDER_FROM_MANUFACTURING" ) ( ChangeNumber 0 ) ( ShortName "ZBV5ZSN" ) ( Description "Issue order to manufacturing" ) ( LogPro_Type "1" ) ( LogPro_Mode "2" ) ) ( "IS_COMPOSED_OF_LOGICAL_PROCESS" 10043322 16511 16531 ( Sep_Id 0 ) ( SequenceNumber 10 ) ( ChangeNumber 0 ) ) ( "DEPENDS_ON_LOGICAL_PROCESS" 10043312 16511 16511 ( Sep_Id 0 ) ( SequenceNumber 0 ) ( ChangeNumber 0 ) ( Description "Nested orders" ) ) ) 3.4 Event CDIF,SYNTAX "SYNTAX.1" "01.00.00",ENCODING "ENCODING.1" "01.00.00" ( HEADER ( USES ( CHARACTERSET PrintableASCII ) ( TEXTFORMAT Unformatted ) ) ( SUMMARY ( VendorCompany "Level 8 Technologies" ) ) ) ( MODEL ( "EVENT" 16571 ( Name "MANUFACTURING_COMPLETE" ) ( ChangeNumber 0 ) ( ShortName "ZBV53SN" ) ( Event_Description "Built items orders" ) ( Event_Class "0" ) ) ( "TRANSITION" 16561

B6

CDIF Format and Samples

Sample CDIF Files

( Name "ZBV52SN" ) ( ChangeNumber 0 ) ( ShortName "ZBV52SN" ) ) ( "EVENT_CAUSES" 10043472 16571 16561 ( Sep_Id 0 ) ( SequenceNumber 0 ) ( ChangeNumber 0 ) ) ( "STATE" 16541 ( Name "PROCESSING_ORDER" ) ( ChangeNumber 0 ) ( ShortName "ZBV50SN" ) ( Description "Order is being processed" ) ( State_Type "2" ) ) ( "IS_PRECONDITIONED_BY_STATE" 10043402 16561 16541 ( Sep_Id 0 ) ( SequenceNumber 0 ) ( ChangeNumber 0 ) ) ( "STATE" 16551 ( Name "READY_TO_SHIP" ) ( ChangeNumber 0 ) ( ShortName "ZBV51SN" ) ( Description "Order ready to be shipped" ) ( State_Type "2" ) ) ( "RESULTS_IN_STATE" 10043412 16561 16551 ( Sep_Id 0 ) ( SequenceNumber 0 ) ( ChangeNumber 0 ) ) )

AppBuilder 2.1.0 Workgroup Repository Administration Guide

B-7

Sample CDIF Files

B8

CDIF Format and Samples

CHAPTER

USING FREEWAY MANAGER AND UTILITIES

AppBuilder 2.1.0 Workgroup Repository Administration Guide

Freeway Manager is the application used for Workgroup repository management and administration by the Workgroup Administrator. A number of tasks can be performed using the Freeway Manager interface, such as viewing the domain, starting and stopping the service, and broadcasting messages to users. This appendix provides a detailed description of the Freeway Manager interface and tasks, including: Using Freeway Manager The Freeway Manager Interface Workgroup Repository Browser Workgroup Status Utility Workgroup User List Utility Performing a Manual Rollback These utilities are recommended for Workgroup Administrator use only. For more information about controlling repository permissions, see Chapter 4, Managing Repository Security.

Using Freeway Manager

Use the Freeway Manager to: View domains, workgroups, and repositories connected to the LAN Start and stop the Workgroup service on a local or remote Workgroup repository Display usage information about connected users Send broadcast messages to connected users Import or Export repository Archive or Restore repository Pack and Reindex repository

AppBuilder 2.1.0 Workgroup Repository Administration Guide

C-1

The Freeway Manager Interface

Procedure - Starting Freeway Manager To start Freeway Manager: 1. Select Start > Programs > AppBuilder > Freeway > Freeway Manager from the menu on the desktop (Figure 3-1). The Freeway Manager startup window opens.
Starting Freeway Manager

Figure 3-1

2.

In the Startup Control tab, type in your user ID and password. Click Done.
Freeway Manager Startup Window

Figure 3-2

The Freeway Manager Interface

The Freeway Manager interface contains menu items and buttons that you use to administer the Workgroup repository. Figure 3-3 shows the menu items in the interface.
Figure 3-3 Freeway Manager Menu

About Freeway Manager Information Freeway Server Archive/Restore Local Freeway Server Import/Export

The menu items provide selections to view server and repository controls.

C-2

Using Freeway Manager and Utilities

The Freeway Manager Interface

Server Menu
Figure 3-4 shows the menu items that you select to access server controls.
Figure 3-4 Server Menu Items

Server Browser
Displays a limited hierarchy browser that lists the Workgroup servers and their current state (installed, running, stopped, etc.).

Server Control
Displays the Workgroup Service window for the Workgroup repository. The Connection Control (Figure 3-10) dialog provides start and stop, status, and report capabilities.

Local Server Control

Displays the Workgroup Service window for the local Workgroup repository.

Broadcast Message
Sends a message to all users connected to a specified server.

Exit
Closes the Freeway Manager window.

AppBuilder 2.1.0 Workgroup Repository Administration Guide

C-3

The Freeway Manager Interface

Repository Menu
Figure 3-5 shows the options available in the Repository menu.
Figure 3-5 Repository Menu Items

Import/Export
Use these utilities to import or export all the data in the repository to a relatively platform-independent format.

Archive/Restore
Use these utilities when backing up or restoring an entire Workgroup SQLServer repository, including the database and all the surrounding data that is not platform-independent.

Pack/Reindex
Use these utilities to pack or reindex the contents of a repository database. See Reindexing and Packing a Repository on page A-8.

Options Menu
Figure 3-6 shows the selections you use to display the toolbar and the status bar in the Freeway Manager window.
Figure 3-6 Options Menu Items

Toolbar
Displays the toolbar, icons representing menu choices available from the menu pull-downs. Place the mouse pointer over an icon to see a text description in the status bar.

C-4

Using Freeway Manager and Utilities

The Freeway Manager Interface

Status Bar
Displays the status bar, a long rectangular area located at the bottom of the Workgroup Manager window. Status and other messages appear in this area.

Window Menu Items

Figure 3-7 shows the menu items that allow you to set up the position of the windows and icons on your desktop. The repository browsers that are connected are also listed with a check mark indicating the active repository.
Figure 3-7 Window Menu Items

Cascade
Arranges open windows to be visible side by side.

Arrange Icons
Arranges all program item icons into rows.

Help Menu Items

Figure 3-8 shows the menu items contained in the Help menu.
Figure 3-8 Help Menu Items

Contents opens the contents of the AppBuilder documentation set in a web browser. BluePhoenix on the Web provides a link to the company website. BluePhoenix Customer Service links you to the customer service website (Contact BluePhoenix Solutions Customer Support to obtain a user ID and password to access this link.) Product Information provides information about the release of the AppBuilder product.

AppBuilder 2.1.0 Workgroup Repository Administration Guide

C-5

Workgroup Repository Browser

Workgroup Repository Browser

The Workgroup Repository Browser uses the Microsoft Windows Network browser to show all the domains, workgroups, and Workgroup repository machines connected to the LAN. Information related to the Workgroup servers on the LAN is then displayed. Figure 3-9 shows an example of the browser window that lists the servers on the network and their access permissions.
Figure 3-9 The Freeway Manager Browser

You may view the entire Workgroup network using the Browser tool. Additionally, you may start and stop the Workgroup service on remote machines from one central location, given the appropriate level of Windows and SQL Server security. For detailed information on server security, see Chapter 4, Managing Repository Security.

Workgroup and Local Server Control

To start or stop the Workgroup service on a server, double-click on a machine icon in the Browser window. The Workgroup Server Control window appears (Figure 3-10). Using the Startup Control window interface, the selected server can be managed.

Warning

If the security Information for the Workgroup Administrator is validated on the remote machine to control the Workgroup service on the remote machine. The Workgroup Administrator must be defined as an administrator on the remote machine in order to issue a request to start or stop the remote Workgroup service.

C-6

Using Freeway Manager and Utilities

Workgroup Repository Browser

Figure 3-10

Server Control Window

The three tabs in this window allow the administrator to control the repository workgroups: Procedure - Startup Control Status Report Tab Status Details Tab Procedure - Startup Control To start or stop the Workgroup service on the selected server: 1. Select Start > Programs > AppBuilder > Freeway > Freeway Manager (Figure 3-11).
Starting Freeway Manager

Figure 3-11

2. 3.

The Startup Control tab on the dialog displays (Figure 3-10). Type the appropriate <userID> and <password> in the Startup Information box. The userID and password must represent an SQL Server database account with permission to the Workgroup database and membership in the SQL Server group. Alternatively, you can define both the <userID> and <password> as an SQL Server Administrator.

4.

Double-click on the: Green traffic light to start the server Red traffic light to stop the server

Note

The Workgroup server cannot stop if there are users connected to the repository. To stop a server that is currently in use, first use the broadcast message function to request that users log off.

AppBuilder 2.1.0 Workgroup Repository Administration Guide

C-7

Workgroup Status Utility

Status Report Tab Select this tab to display status information about users, sessions, and tools currently active on the selected server machine. Status Details Tab Select this tab to display details about users working in the selected Workgroup repository.

Note

To start or stop the Workgroup service, or view status details on a remote machine, the Windows user account must be a member of the administrator group on the remote machine.

The Workgroup Service

The Workgroup Service is a daemon process, or background executable, that serves as the gateway to the Workgroup repository database. Clicking on the Workgroup stoplight initializes the Workgroup process and the connection to an SQL Server. The Startup Control screen prompts for a userID and password. This userID must be defined in the native database management system. The daemon must be active before any client workstations can attach to the Workgroup. Each Workgroup repository user has its own individual doorway to the repository represented by a session.

Workgroup Status Utility

The Workgroup Status utility displays the status of uncommitted changes within the active repository. It accomplishes this by searching the repository database for locked objects and then displaying information about the sessions in which these objects became locked. Included in this information are recommended actions to perform to recover the objects. Procedure - Invoking the Workgroup Status Utility (UNIX only) To invoke this utility, type the following at the command line: grestate [-t<tipfile>] -u<userID> -p<password> where:
<tipfile> <userID> <password> The name of the Workgroup tip file. If the HPSINI variable is set, this value is not required. The Workgroup administrators userID The Workgroup administrators password

Sample Status Output

The following is sample output produced by the status utility: Initializing statics ... Login as fwyadmin ... Login successful. Attaching to database... Extracting the entries in the tip file ...

C-8

Using Freeway Manager and Utilities

Workgroup User List Utility

Extracting the locked objects in the repository ... Evaluating the locked objects in the repository ...
Table 3-1 Session 3 14 23 42 58 64 Sample Output and Recommended Actions Process 19193 8051 13019 19310 5887 State Alive Alive Alive Alive Dead User JERRY JODY CHRIS ROBIN TERRY Status No Changes Changes Changes No Changes Changes Action to Perform Logoff and Rollback None None Logoff and Rollback Rollback Only Rollback Needed

In Table 3-2, the Recommended Action column gives recommended steps to perform a recovery. Explanations of the messages are also presented.
Table 3-2 Actions to Perform Messages Action to Perform Message None

Explanation The connection to the repository is still active and there are uncommitted changes in the repository. The connection to the repository is still active. Although there are no recorded changes, the repository contains locked objects. Although the connection to the repository is recorded as active, no connection can be found. Additionally, there are locked objects in the repository. Locked objects have been found, but they cannot be identified with any recorded connection.

Recommended Action No recovery actions are needed nor should they be attempted. The named user should log off and the DBA perform a manual rollback (see Performing a Manual Rollback.

Logoff & Rollback

Rollback Only

Perform a manual rollback.

Rollback Needed

Perform a manual rollback.

Workgroup User List Utility

The Workgroup User List utility lists the users and tools currently connected to the repository. Run the utility on the server machine. Procedure - Invoking the Workgroup User List Utility (UNIX only) To invoke this program, type the following at the command line: greusers

AppBuilder 2.1.0 Workgroup Repository Administration Guide

C-9

Performing a Manual Rollback

Sample User List Output

Table 3-3 is sample output produced by the User List utility program:
Table 3-3 Session 1 2 3 5 6 10 27 Sample Workgroup User List Process 24684 12976 18488 19253 23509 13814 11529 User CHRIS TERRY BOBBY BOBBY KELLY KELLY TERRY Tool Preparation Workbench Preparation Workbench Construction Workbench Construction Workbench Preparation Workbench AppBuilder Job Scheduler Construction Workbench

The column headings are defined in Table 3-4.

Table 3-4 User Output Heading Definitions Description The session number for the user connection The operating system process number The Workgroup user The tool the Workgroup user is using

Heading Session Process User Tool

Workgroup Status Report

For Windows, use Freeway Manager to find out which users are currently connected using the Status Report Tab.

Performing a Manual Rollback

In addition to the situations described in Table 3-2, perform a rollback when: The state of a session is Dead. No information is given for a session. For example, in the sample output in Sample Status Output, users JERRY and ROBIN should log off and so the Workgroup Administrator can perform a rollback on sessions #3 and #42. Procedure - Performing a Rollback (UNIX only) To perform a rollback on a session in UNIX, at the command line, type: grerblk -i<session number> -u<userid> -p<password>

C-10

Using Freeway Manager and Utilities

Performing a Manual Rollback

where: <session number> <userid> <password> The number of the session to roll back The Workgroup administrators userID The Workgroup administrators password

Broadcasting Messages
Use the following procedure to broadcast messages to the users within the development environment. For example, you can notify users that the server is down, make specific requests, or deliver project information to developers. The broadcast mechanism allows the you to send a message to all the connected users of the designated Workgroup repository. Procedure - Broadcasting Messages to Users To broadcast a message to all users connected to a specified server: 1. 2. Select a Workgroup server machine in the Workgroup Server Browser window. Select Server>Broadcast Message from the Freeway Manager window (Figure 3-12).
Broadcast Message Action

Figure 3-12

3.

The Broadcast Message window appears with the name of the server in the Broadcast to Server field. Type the message you want to broadcast to users in the box and click Send (Figure 3-13).
Broadcast Message Dialog

Figure 3-13

Your message is sent.

AppBuilder 2.1.0 Workgroup Repository Administration Guide

C-11

Performing a Manual Rollback

C-12

Using Freeway Manager and Utilities

Index

INDEX
AppBuilder 2.1.0 Workgroup Repository Administration Guide

A
Actions to Perform messages C-9 add-in samples A-13 add-ins to Freeway Explorer A-9 ANAIMP.OUT tracing option 5-9 Analyze data migration phase 5-2 importing an object 5-15 analyze with merge in imports 5-18 ANALYZE.OUT tracing option 5-9 application folder features 5-31 functions 5-31 import 5-30 migrations using 5-31 to migrate data 5-26 Archive/Restore 6-1 archiving HPSINI command 6-4 repositories 6-2 using command line 6-3 using the tab 6-4 with DBM_DATABASE 6-4 archiving data 6-2 attribute entity types B-1 Audit to check lock status 3-5 automatic object locking 3-1

buffer cache parameters A-6

C
cache parameters A-6 cascading locks 3-3 Case Data Interchange Format B-1 CDIF 5-31 CDIF CDF extension for 5-31 command line export for Windows 5-32 command line import for Windows 5-32 definition 5-31 format and samples B-1 format for exported files 5-31 functions 5-31 impact analysis capability 5-31 import and export capabilities 5-31 importing and exporting using 5-31 layout B-1 NT export command parameters 5-32 sample files B-2 security permissions 5-31 Windows import command parameters 5-32 CDIFIN.EXE import command line format 5-32 CDIFOUT.EXE export command line format 5-32 changing group access 4-10 clearing the log to start SQL A-4 Commit action 2-13 Compare on and off setting 5-20 configuring native security for the SQL server 4-17 Conflict import status category 5-20 connection alias using Freeway Client Configuration 1-9 connections setting number of users A-3

B
broadcasting messages C-11 broadcasting updates 3-7 browser description 2-8 menus 2-8 toolbar 2-10

AppBuilder 2.1.0 Workgroup Repository Administration Guide

Create action definition 4-4 import status category 5-20 creating projects, groups, users, and super users 4-5

D
data type DATE A-9 entity types B-1 database tempDB A-2 DataBase Management System (DBMS) 4-15 date migration A-9 Date and Time filters 5-8 DATE data type A-9 date support settings A-9 debugger Edit menu 2-9 defaults permission levels

entity entity types B-1 entity types list of CDIF types B-1 event entity types B-1 Export data migration phase 5-2 description 5-25 menu option 5-8 utility 6-9 export using command line 6-10 EXPORT.OUT generated during migration 5-10 tracing option 5-9 extending the Workgroup and Master Transaction logs A-4

F
FIL extension export files 5-3 File menu object browser 2-9 file-naming conventions between host and client 5-25 Freeway also referred to as Workgroup 1-1 Freeway Client Configuration to create or delete alias 1-9 Freeway Explorer overview 1-8 starting 2-1 Freeway Manager interface C-2 menu C-2 starting C-2 Freeway Security Logical Model 4-1 functions adding a name A-10 deleting a name A-11 requirements for creating DLLs A-11 FWYUTIL utility 6-7

permissions default levels 4-18

projects, groups, userID and password 4-15, 4-18 Delete action definition 4-4 import status category 5-20 descriptive text for all object types entity types B-1 direct import 5-14, 5-22 disk contention in Oracle installation A-5 disk I/O parameters A-7 disk storage tuning for Oracle A-5 DLL adding function names A-10 creating add-ins A-11

E
Edit menu debugger 2-9 Enterprise repository description 1-2 entities creating migration 5-10 viewing child 2-12 viewing parent 2-12

G
GET_SELECTED_FIELD default component 4-14 global access setting 4-12 global user access to projects 4-12 GRESRVNT.EXE process thread A-3

ii

AppBuilder 2.1.0 Workgroup Repository Administration Guide

group in security model 4-2 Group-Project relationship 4-2 Groups access to multiple projects 4-12 creating procedure 4-6 viewing member and users 4-9 groups creating 4-5 PUBLIC 4-13

H
hierarchy three-tier 1-5 two-tier 1-5 HPS_EVENT_VIEW default security object 4-14 HPSINI archive command 6-4

LOAD.OUT tracing option 5-9 locks cascading 3-3 checking status 3-4 checking status using Audit 3-5 displaying messages 3-3 exclusive 3-1 exclusive, shared, and cascading 3-1 shared 3-2 understanding types 3-1 LOG files 5-23 logical process entity types B-1 logs clearing for SQL A-4 clearing workgroup and transaction A-4

M
mainframe repository description 1-2 memory increasing allocation A-2 Merge import and analyze controls 5-18 option example 5-18 using in a direct or a selective import 5-18 Merge option 5-17 messages broadcast C-11

I
Import data migration phase 5-2 description 5-25 import CDIF 5-30 direct 5-14 direct or selective description 5-18 migration object 5-15 on or off status category 5-20 performing a direct 5-22 preparing the target repository for 5-15 selective 5-14 status 5-19 status categories 5-20 status commands 5-20 using command line 6-9 window 6-8 Import utility 6-8 IMPORT.OUT tracing option 5-9 Import/Export utility 6-7 importing and exporting data 6-7

K
keywords using search wizard 2-6

L
library cache parameters A-6 Load data migration phase 5-2
Index iii

migration action menu options 5-8 and Freeway security 5-25 between repositories 5-24 creating an object - Load 5-6 creating entities 5-10 creating entities for export 5-10 export action menu 5-7 export results sample 5-24 export toolbar 5-3 exporting objects 5-3 four phases 5-1 from older versions 5-26 import analyze with merge 5-17 import toolbar 5-14 importing an object - Analyze 5-15 importing objects procedure 5-21 MIGFILES 5-1 output filenames 5-23 overview 5-1 performing an import 5-14 performing export 5-3 performing import phase 5-18 renaming PC files 5-25 results 5-23 setting export options 5-8 setting object scope 5-11 using results 5-23 migration tools application folder 5-1 modifying the default Freeway security model 4-18

objects changing access in a project 4-10 default security 4-14 importing 5-14 viewing parent/child relationships 3-6 optimizing Oracle instance parameters A-5 options Merge 5-17 Options menu object browser 2-9 Oracle checking data file size A-7 data files for instance A-5 instance parameters A-5 performance tuning A-1, A-5 repository maintenance 6-11 tablespace parameters A-7 values for instance parameters A-6 OUT files 5-23 output files from migrations 5-23 ownership verifying 4-4

P
packing repositories A-8 parameters disk I/O A-7 PASSWORD default password 4-15 performing a manual rollback C-10 performing a rollback 6-6 Permissions allowable actions 4-4 default levels 4-15 managing multiple 4-12 setting 4-3 permissions Freeway system administrator 4-16 implicit global read 4-15 Personal repository description 1-2 procedures performance tuning A-1 Project filters 5-8 project verifying 4-4 project hierarchy defining member access 4-3 Projects creating procedure 4-6

N
native security 4-15

O
Object import actions 5-19 Object Browser description 2-8 toolbar 2-10 using 2-8 viewing child entities 2-12 object browser File menu 2-9 Options menu 2-9 object locking automatic 3-1 object properties viewing and editing 2-10 object types querying and loading 2-5

iv

AppBuilder 2.1.0 Workgroup Repository Administration Guide

projects creating 4-5 global user access 4-12 group access 4-12 in security model 4-2 SYSADM default 4-15 viewing SYSADM 4-16 property entity types B-1 PUBLIC group 4-13, 4-15 default security object 4-14 implicit permissions in 4-14

rollback manual procedure C-10 performing 6-6 RUNSTATS.SQL accessing the statistics file A-4

S
Scope definition 4-3 migration options 5-11 setting 4-3 scope selection options 4-11 security assigning super users 4-8 configuring native for SQL 4-17 default objects 4-14 defining authority 4-5 defining native 4-15 group definition 4-2 managing with subgroups 4-13 projects definition 4-2 setting in development 1-3 user definition 4-2 security model creating an ID 4-8 description 1-3 modifying the default 4-18 sample 1-4 sample scenarios 1-4 understanding 4-1 SEER1 default project 4-15 default security object 4-14 SEER2 default project 4-15 default security object 4-14 selective import 5-14, 5-19 toolbar 5-19 session properties viewing and modifying 2-3 sessions commit action 2-13 settings date support A-9 shared locks 3-2 SmartScope object types 5-12 setting options 5-12 SQL clearing logs to start A-4 configuring native security for 4-17 improving server response A-1 performance tuning A-1 server memory allocation A-2
Index v

R
recovery actions messages C-9 recommended steps for C-9 reindexing procedure A-8 Relate action definition 4-4 relationship entity types B-1 relationship types required to connect entity types B-1 relationships group-project 4-2 viewing child 2-12 viewing parent/child 3-6 repository actions using Explorer 1-8 administration 1-3, 6-1 broadcast messages C-11 changing priority on Windows A-3 connecting to target 5-15 connection to 1-9 date migration A-9 descriptions 1-2 import/export function 1-6 maintenance 6-11 menu in Freeway Manager C-4 menu options 1-9 non-hierarchical structure 1-6 packing A-8 reindexing A-8 sample configurations 1-7 three-tier hierarchy 1-5 two-tier hierarchy 1-5 types 1-2 workgroup hierarchies 1-5 workgroup on multiple servers 1-8 Repository Security Logical Model 4-1 Restore utility 6-4 RETURN_CODE default field 4-14

state entity types B-1 status Freeway Manager output C-8 status details in server browser window C-8 status report in server browser window C-8 Subgroups creating 4-13 subgroups creating 4-13 super user assigning 4-8 super users creating 4-5 Switches and Functions table 6-7 SYSADM default project 4-15 SYSLOGS clearing transaction logs A-4

Users creating procedure 4-7 setting global access 4-12 users creating 4-5 utilities Archive/Restore 6-1 Export 6-9 FWYUTIL 6-7 Import 6-8 Import/Export 6-7 restore 6-4

V
verifying ownership and active project 4-4 View log file menu option 5-8 viewing the default SYSADM project 4-16

W
Workgroup installation software for Oracle A-5 repository description 1-2 repository file storage A-5 server browser C-6 server control C-6 service daemon C-8 status report using Freeway Manager C-10 status utility C-8 user list utility C-9 Workgroup repositories archiving 6-2

T
tables Switches,Functions 6-7 tempDB default in memory A-2 using to improve performance A-2 toolbars object browser 2-10 tools adding A-9 transaction logs extending segments A-4 Transaction Logs (SYSLOGS) A-4 transition entity types B-1

U
Update action definition 4-4 import status category 5-20 user in security model 4-2 user connections setting number A-3 user list viewing using Freeway Manager C-10 user list output sample C-10 USERID default user 4-15

vi

AppBuilder 2.1.0 Workgroup Repository Administration Guide