Sct4 System Tailoring Vol.1

ServiceCenter
Version 4.0
System Tailoring
Volume 1
March 2001
SCT-4-ENG-01013-00012
Peregrine Systems, Inc. 3611 Valley Centre Drive San Diego, CA 92130
Copyright 1998-2001 Peregrine Systems, Inc. or its subsidiaries All Rights Reserved. Information contained in this document is proprietary to Peregrine Systems, Incorporated, and may be used or disclosed only with written permission from Peregrine Systems, Inc. This book, or any part thereof, may not be reproduced without the prior written permission of Peregrine Systems, Inc. This document refers to numerous products by their trade names. In most, if not all, cases these designations are claimed as Trademarks or Registered Trademarks by their respective companies. Peregrine Systems and ServiceCenter are registered trademarks and InfraTools and AssetCenter are trademarks of Peregrine Systems, Inc. or its subsidiaries. This document and the related software described in this manual is supplied under license or nondisclosure agreement and may be used or copied only in accordance with the terms of the agreement. The information in this document is subject to change without notice and does not represent a commitment on the part of Peregrine Systems, Inc. The names of companies and individuals used in the sample database and in examples in the manuals are fictitious and are intended to illustrate the use of the software. Any resemblance to actual companies or individuals, whether past or present, is purely coincidental.
This edition applies to version 4.0 of the licensed program ServiceCenter
Preface
Welcome to the ServiceCenter System Tailoring Guide - Volume 1. The System Tailoring Guide is a set of two volumes covering the various aspects of tailoring the ServiceCenter system. Each volume is broken out into sections, containing several chapters each, that deal with aspects of tailoring. The main sections of this guide are: Volume one Database Manager - Chapters 1 through 7 Database Dictionary - Chapters 8 through 10 Format Control - Chapters 11 through 20 Forms Designer - Chapters 21 through 29 Link/Join - Chapters 1 through 5 System Language - Chapters 6 and 7 Creating a Live user Interface - Chapters 8 through 12 Display Application - Chapters 13 through 17 System Tools - Chapters 18 through 24
Volume two
Topics covered in the System Tools chapters include: Macros Audits Clocks DDE support System events Sequential Numbers.
Knowledge Requirements
While these volumes explain to the various aspects of ServiceCenter system tailoring, a certain level of knowledge of ServiceCenter is presumed. These manuals are designed for a system administrator. For more basic information on ServiceCenter applications and system administration, please refer to: ServiceCenter Users Guide ServiceCenter System Administration ServiceCenter Application Administration. If you have questions, please contact Peregrine Systems, Inc., using the information on the following pages.
Contacting Peregrine Systems, Inc.

For technical support on this or any other product from Peregrine Systems, Inc. please refer to the Customer Support Web site at:
http://support.peregrine.com/
ii
System Tailoring, Vol. 1
Contents
Knowledge Requirements .................................................................................................Preface-ii Contacting Peregrine Systems, Inc. ..................................................................................Preface-ii
Chapter 1: The Document Engine

Accessing the Document Engine .................................................................................................1-2 Objects .........................................................................................................................................1-2 Fields on the Objects panel..........................................................................................................1-3 The Object Info Tab...............................................................................................................1-3 The Locking Tab....................................................................................................................1-5 Variable/Global Lists Tab ......................................................................................................1-6 The Alerts Tab.......................................................................................................................1-7 The Approvals Tab ................................................................................................................1-8 States ...........................................................................................................................................1-9 Creating States......................................................................................................................1-9 Fields on the States panel...................................................................................................1-10 Processes ..................................................................................................................................1-11 Creating Processes .............................................................................................................1-11 The Process Panel .....................................................................................................................1-12 The Initial Expressions tab ..................................................................................................1-12 The RAD tab........................................................................................................................1-13 The Final Expressions tab...................................................................................................1-14 Standard Variables.....................................................................................................................1-14
Chapter 2: Introduction to the Database Manager

Administration Mode ....................................................................................................................2-2 Accessing a Record from the Database Manager .......................................................................2-2
Contents
Chapter 3: Record Use

Retrieving Records from Within a Database................................................................................ 3-1 Administration Mode ............................................................................................................. 3-1 Retrieving records using relational and logical operators ............................................................ 3-2 Relational operators ............................................................................................................. 3-2 Logical operators ............................................................................................................... 3-3
Retrieving Records via the P4/QBE Method ...................................................................................... 3-5 Retrieving records using the starts with (#) relational operator ................................................... 3-5 Retrieving records using the equal to (=) relational operator....................................................... 3-6 Retrieving records using the greater than (>) relational operator ................................................ 3-7 Retrieving records using the less than (<) relational operator ..................................................... 3-9 Retrieving records using the not ( MVS, ~ UNIX) relational operator ...................................... 3-10 Retrieving record using the like relational operator ................................................................... 3-10 Retrieving all records in a database .......................................................................................... 3-12 Retrieving records using more than one field ............................................................................ 3-13 Retrieving records using array fields ......................................................................................... 3-15 Menu controls ............................................................................................................................ 3-17 Clearing an initial record ..................................................................................................... 3-17 Performing IR Expert queries.............................................................................................. 3-17 Retrieving Records via the Query Window....................................................................................... 3-18 Accessing the query window ..................................................................................................... 3-18 Using the query window............................................................................................................. 3-19 Retrieving records with a simple query expression ................................................................... 3-20 Creating a stored query ...................................................................................................... 3-23 Stored query options........................................................................................................... 3-25 Retrieving records with a complex query expression ................................................................ 3-25 OR/AND statements .......................................................................................................... 3-25 Isin statements.................................................................................................................... 3-26 not statements .................................................................................................................... 3-27 Using functions in a query ......................................................................................................... 3-27 Greater than/less than(>/<) queries ................................................................................... 3-27 Identification of characters anywhere in a field value ........................................................ 3-29 Specifying length of character strings in query .................................................................. 3-30
ii
Chapter 4: Single Record Functions

Adding a record............................................................................................................................4-1 Duplicating an existing record ......................................................................................................4-1 Updating an existing record .........................................................................................................4-2 Deleting a record..........................................................................................................................4-2 Printing a record...........................................................................................................................4-4 Advanced Operations .........................................................................................................................4-6 Recovering from record/key conflicts ...........................................................................................4-6 Record level options.....................................................................................................................4-7 Expand array options ............................................................................................................4-9 Format Control Settings ....................................................................................................................4-11
Chapter 5: Multiple-Record Functions

Adding Multiple Records .....................................................................................................................5-2 Mass Adding records using a literal value....................................................................................5-2 Mass Adding Records Using a Variable Value ............................................................................5-6 Updating Multiple Records ................................................................................................................5-10 Updating multiple records with a literal value .............................................................................5-10 Updating multiple records with a variable value .........................................................................5-12 Mass Add/Update Function Errors ....................................................................................................5-16 Invalid duplicate or NULL key ....................................................................................................5-16 Deleting Multiple Records .................................................................................................................5-18 Printing Multiple Records ..................................................................................................................5-19 Counting records........................................................................................................................5-20 Unloading ServiceCenter Data .........................................................................................................5-22 Unloading a single record from a database ...............................................................................5-22 Unload messages ...............................................................................................................5-25 Unload form fields ...............................................................................................................5-27 Unload complication messages...........................................................................................5-29 Unloading multiple records from one database..........................................................................5-29 Unload complication messages...........................................................................................5-32 Unloading multiple records from a single file using value-list.....................................................5-33
Contents iii
Unload complication messages .......................................................................................... 5-37 Unloading records from multiple databases .............................................................................. 5-38 Part IUnload from the first file.......................................................................................... 5-39 Part IIUnload from the second file ................................................................................... 5-41 Unloading a QBE only (no data records) to Excel ..................................................................... 5-44 Unloading a Database Dictionary only (no data records) .......................................................... 5-45 Unloading a ServiceCenter Report Writer report ....................................................................... 5-48 Part IReport structure unload .......................................................................................... 5-48 Part IIReport record unload ............................................................................................. 5-50 Unload complication messages .......................................................................................... 5-52 Part IIIFormat Control...................................................................................................... 5-53 Part IVLink records.......................................................................................................... 5-55 Unload complication messages .......................................................................................... 5-55 Loading ServiceCenter Databases................................................................................................... 5-58 Executing the load as a foreground process ............................................................................. 5-58 Load complication messages.............................................................................................. 5-60 Executing the load as a background process ............................................................................ 5-62
Chapter 6: Database Record Auditing

Understanding Auditing ...................................................................................................................... 6-2 Accessing the Audit Specifications File .............................................................................................. 6-3 Audit specifications table fields.................................................................................................... 6-4 Accessing the Audit Log File .............................................................................................................. 6-7 Audit log fields ........................................................................................................................... 6-8 Defining an Audit Specifications Entry................................................................................................ 6-9 Field name verification............................................................................................................... 6-11 Invoking Audit Processing ................................................................................................................ 6-13 Format Control........................................................................................................................... 6-14 Fields .................................................................................................................................. 6-16 Trigger setup.............................................................................................................................. 6-17 Lookup Audit Log Entries ................................................................................................................. 6-19 Run-time example...................................................................................................................... 6-19
iv System Tailoring, Vol. 1
Chapter 7: File Maintenance

Resetting a Database from Database Manager ...........................................................................7-1 Scheduling a database reset........................................................................................................7-3 Regenerating Database Keys from Database Manager .....................................................................7-5 Scheduling a database regeneration ...........................................................................................7-6
Chapter 8: Unload Script Utility

Creating an Unload Script ...................................................................................................................8-2 Commonly scripted files ..............................................................................................................8-6 Protecting formats .......................................................................................................................8-7 Examples...............................................................................................................................8-7 Editing an Unload Script ....................................................................................................................8-9 Validating an Unload Script...............................................................................................................8-11 Unloading records from an Unload Script .........................................................................................8-13 Purging Records from an Unload Script ..........................................................................................8-15
Chapter 9: Introduction to the Database Dictionary

Understanding the Database Dictionary ............................................................................................9-2 Accessing the Database Dictionary ....................................................................................................9-3 From Forms Designer .................................................................................................................9-3 Menu and command access .......................................................................................................9-5
Chapter 10: Adding and Modifying

Adding a New Field ...........................................................................................................................10-1 Forming field names...................................................................................................................10-1 Scalar fields................................................................................................................................10-2 Valid field types ...................................................................................................................10-4 Arrays .........................................................................................................................................10-5 Structures..........................................................................................................................................10-9 Fields within structures............................................................................................................10-11
Contents v
Arrayed structures............................................................................................................. 10-14 Alias Fields ..................................................................................................................................... 10-19 Adding an alias field................................................................................................................. 10-20 Adding a Key .................................................................................................................................. 10-26 Adding a key as the first key.................................................................................................... 10-26 Inserting a key between other keys .................................................................................. 10-29 Adding keys to bottom of the key list ................................................................................ 10-32 Modifying a Field ........................................................................................................................... 10-36 Modifying field types: character (scalar) <-> array................................................................... 10-36 Mass Update..................................................................................................................... 10-39 Changing data types: character <-> number ........................................................................... 10-39 Mass Update..................................................................................................................... 10-41 Modifying a Key .............................................................................................................................. 10-42 Modifying keys: nulls & duplicates <-> unique......................................................................... 10-42 Modifying keys: single <-> concatenated................................................................................. 10-44 Deleting a Field............................................................................................................................... 10-47 Deleting a Key ................................................................................................................................ 10-50
Chapter 11: Advanced Operations

Copying a Database Dictionary ........................................................................................................ 11-1 Copying Database Dictionary record only ................................................................................. 11-1 Copying Database Dictionary record and data records ............................................................. 11-2 Renaming a Database Dictionary Record ........................................................................................ 11-5 Deleting a Database Dictionary Record .......................................................................................... 11-7 Resetting the Database and All Records.......................................................................................... 11-8 Scheduling the reset ........................................................................................................... 11-9 Information Pooling......................................................................................................................... 11-11 Modifying pool settings ............................................................................................................ 11-11 Searching for a Field ...................................................................................................................... 11-13
vi
Chapter 12: Notification Engine

The Notification File ...................................................................................................................12-2 Fields on the Notifications Definition Panel .........................................................................12-4 Editing a Notification Record......................................................................................................12-4 Adding new fields to a Notification Record.................................................................................12-6 Notification FlowChart .........................................................................................................12-8 Messages ...................................................................................................................................12-9 Fields on the message panel ............................................................................................12-10 Message Type..........................................................................................................................12-11 Fields on the Message Type Panel ...................................................................................12-11 On Call Scheduling .........................................................................................................................12-12 Fields on the Oncall Schedule Panel .......................................................................................12-13 Creating an oncall schedule.....................................................................................................12-14 Modifying an oncall schedule ...................................................................................................12-15 Oncall Flow .................................................................................................................................................12-16 Daily On Call Records.....................................................................................................................12-17 Example: On Call Schedule .....................................................................................................12-18 Default Notification Definitions .................................................................................................12-20
Chapter 13: Introduction to Format Control

Overview ...........................................................................................................................................13-1 Knowledge Requirements ..........................................................................................................13-2
Chapter 14: What is Format Control?

Format Control Processes ................................................................................................................14-3 Initializations...............................................................................................................................14-3 Validations..................................................................................................................................14-3 Calculations................................................................................................................................14-3 Additional File Queries ...............................................................................................................14-3 Security ......................................................................................................................................14-4 Subroutines ................................................................................................................................14-4 Views..........................................................................................................................................14-4 Additional Options ......................................................................................................................14-4
Contents vii
Selecting a Process View ......................................................................................................... 14-4 Creating Expressions ....................................................................................................................... 14-6 Definitions .................................................................................................................................. 14-6 System Functions ...................................................................................................................... 14-6 Boolean (Logical) Fields ............................................................................................................ 14-7 File Variable............................................................................................................................... 14-8
Chapter 15: Getting Started

Accessing Format Control ................................................................................................................ 15-1 Access from Forms Designer .................................................................................................... 15-1 Direct Access............................................................................................................................. 15-2 Adding a Record............................................................................................................................... 15-3
Chapter 16: Format Control Processes

Initializations ..................................................................................................................................... 16-3 Fields ......................................................................................................................................... 16-4 Form Name................................................................................................................................ 16-4 Format Control Record .............................................................................................................. 16-4 Modifying a Format Control Record......................................................................................... 16-12 Validations ...................................................................................................................................... 16-13 Fields ....................................................................................................................................... 16-14 Examples ................................................................................................................................. 16-15 Required Fields................................................................................................................. 16-15 Specific Values ................................................................................................................. 16-16 Range of Values ............................................................................................................... 16-16 Conditional Values ............................................................................................................ 16-17 Fields in an Arrayed Structure .......................................................................................... 16-18 Calculations ................................................................................................................................... 16-21 Fields ....................................................................................................................................... 16-22 Examples ................................................................................................................................. 16-23 Simple calculations ........................................................................................................... 16-23 Moving Characters in a Field ............................................................................................ 16-24
viii
Calculations on Fields in Arrayed Structures ....................................................................16-24 Counting Tickets of Differing Severity Levels in a Report Writer Report...........................16-25 Counting Open Problem Tickets in a Report Writer Report ..............................................16-26 Denulling an Array.............................................................................................................16-26 Using Calculations in Reports ...........................................................................................16-26 Additional File Queries ....................................................................................................................16-29 Fields........................................................................................................................................16-29 Examples ................................................................................................................................16-32 Report Information.............................................................................................................16-32 Validation...........................................................................................................................16-33 Security ...........................................................................................................................................16-35 Fields........................................................................................................................................16-36 Fields on the Standard Tab ...............................................................................................16-36 Fields on the Advanced Tab..............................................................................................16-39 Subroutines .....................................................................................................................................16-41 Fields........................................................................................................................................16-42 Parameters ..............................................................................................................................16-43 Examples .................................................................................................................................16-44 Fingerprinting ....................................................................................................................16-44 Additional Options ...........................................................................................................................16-53 Fields........................................................................................................................................16-55 Example ...................................................................................................................................16-58 Opening Prompt Form.......................................................................................................16-58 Designate Files to Be Called .............................................................................................16-59 User Interaction .................................................................................................................16-59 Views ..............................................................................................................................................16-62 Fields........................................................................................................................................16-63 Example ............................................................................................................................16-63
Chapter 17: Array Maintenance

Arrayed Structures ............................................................................................................................17-1 as.options ...................................................................................................................................17-3 Parameters..........................................................................................................................17-3
Contents ix
Example .............................................................................................................................. 17-4 as.copy ...................................................................................................................................... 17-8 Parameters ......................................................................................................................... 17-8 as.delete .................................................................................................................................... 17-9 Parameters ......................................................................................................................... 17-9 as.insert ................................................................................................................................... 17-10 Parameters ....................................................................................................................... 17-10 as.move ................................................................................................................................... 17-11 Parameters ....................................................................................................................... 17-11 Example................................................................................................................................... 17-12 Create a Format Control Record....................................................................................... 17-12 Test the Form.................................................................................................................... 17-13 as.get.name ............................................................................................................................. 17-15 Parameters ....................................................................................................................... 17-15 as.sort ...................................................................................................................................... 17-15 Parameters ....................................................................................................................... 17-16 Example ............................................................................................................................ 17-17 Sorting Simple Arrays ..................................................................................................................... 17-23 Example................................................................................................................................... 17-23 Create a Form................................................................................................................... 17-23 Create a Format Control Record....................................................................................... 17-24 Add Data to Your Test Form ............................................................................................. 17-26
Chapter 18: Sequential Numbering for Format Control

Data Types ....................................................................................................................................... 18-2 Parameters ....................................................................................................................................... 18-3 Simple Sequential Numbers ............................................................................................................. 18-5 Create the Form......................................................................................................................... 18-5 Create a Database File.............................................................................................................. 18-6 Create a Format Control Record ............................................................................................... 18-7 Add a Record to the Database .................................................................................................. 18-9 Number File ............................................................................................................................. 18-10 Fields ................................................................................................................................ 18-11
Prefixes and Suffixes ......................................................................................................................18-13 Create a Format Control Record ..............................................................................................18-13 Add a Data Record...................................................................................................................18-15
Chapter 19: Posting

Link Records .....................................................................................................................................19-2 Fields..........................................................................................................................................19-2 Link Line Definition File ..............................................................................................................19-4 Fields...................................................................................................................................19-5 System Tray ........................................................................................................................19-6 Posting Variables .............................................................................................................................19-7 Setting up Posting via Format Control Subroutines or Additional Options........................................19-9 Fields..........................................................................................................................................19-9 Parameters........................................................................................................................19-10 Examples ........................................................................................................................................19-11 Automatic Updates via Format Control Subroutines ................................................................19-11 Identify Field Input Values .................................................................................................19-11 Create the Link Record .....................................................................................................19-13 Create the Format Control Record ....................................................................................19-16 Open a Change Request...................................................................................................19-19 Manual Posting via Format Control Additional Options............................................................19-24 Create the Link Record .....................................................................................................19-25 ................................................................................... Create the Format Control Record19-25 Modify a Hardware Change Request ................................................................................19-30 Confirming the Posting Routine ...............................................................................................19-33 Manual Posting with Confirmation.....................................................................................19-35
Chapter 20: Error Messages Chapter 21: Special Processing Considerations

Incident Management .......................................................................................................................21-1 Change Management .......................................................................................................................21-2
Contents xi
Master Format Control Record .................................................................................................. 21-2 Detail Format Control Record .................................................................................................... 21-3 Approval Format Control Record ............................................................................................... 21-3 Eventout Records ............................................................................................................................. 21-4 Page Messages ................................................................................................................................ 21-6 Incident Management Alert Records ............................................................................................... 21-7
Chapter 22: Common Applications Called from Format Control

Applications ...................................................................................................................................... 22-2 fill.fc............................................................................................................................................ 22-2 Parameters ......................................................................................................................... 22-2 Variables Supported ........................................................................................................... 22-2 post.fc ........................................................................................................................................ 22-2 Parameters ......................................................................................................................... 22-3 getnumb.fc ................................................................................................................................. 22-3 Parameters ......................................................................................................................... 22-3 message.fc ................................................................................................................................ 22-4 Parameters ......................................................................................................................... 22-5 validate.fields ............................................................................................................................. 22-6 Parameters ......................................................................................................................... 22-6 database .................................................................................................................................... 22-7 Parameters ......................................................................................................................... 22-7 query.stored............................................................................................................................... 22-7 Parameters ......................................................................................................................... 22-7 axces.page ................................................................................................................................ 22-8 Parameters ......................................................................................................................... 22-8 axces.write................................................................................................................................. 22-9 Parameters ......................................................................................................................... 22-9 axces.fax.................................................................................................................................. 22-10 Parameters ....................................................................................................................... 22-10 fingerprint................................................................................................................................. 22-11 Parameter ......................................................................................................................... 22-11 sort.array.................................................................................................................................. 22-11 Parameters ....................................................................................................................... 22-11
xii
Determining Parameters .................................................................................................................22-13
Chapter 23: Introduction to Forms Designer

Knowledge Requirements .................................................................................................................23-2
Chapter 24: Dynamic View Dependencies

Specifying property conditions ...................................................................................................24-3 Field comparisons ...............................................................................................................24-3 Field value matching ...........................................................................................................24-4 Dynamic functions ...............................................................................................................24-4 Other examples ..........................................................................................................................24-5
Chapter 25: Forms Designer Elements

What is Forms Designer? .................................................................................................................25-1 The Drawing Canvas ........................................................................................................................25-2 Structure of the canvas ..............................................................................................................25-3 Sizing your forms on the canvas ................................................................................................25-4 Positioning multiple objects ........................................................................................................25-4 The Tools Palette ..............................................................................................................................25-5 The Properties Window.....................................................................................................................25-6 The Form Wizard ..............................................................................................................................25-7
Chapter 26: The Forms Design Process

Accessing Forms Designer ...............................................................................................................26-1 Preview of the Forms Design Process ..............................................................................................26-4
Chapter 27: The Properties Window

Using the Properties Window ....................................................................................................27-1 Sizing the Properties Window ....................................................................................................27-2 Selecting a property ...................................................................................................................27-2 Entering a value manually..........................................................................................................27-2
Contents xiii
Entering a Value from the Edit Area list..................................................................................... 27-3 Understanding Properties ................................................................................................................ 27-4 Common properties .................................................................................................................. 27-4 Font Properties ......................................................................................................................... 27-5 Box Properties .......................................................................................................................... 27-6 Object-specific properties .......................................................................................................... 27-7
Chapter 28: The Tools Palette

Pointer .............................................................................................................................................. 28-2 Label................................................................................................................................................. 28-4 More About Labels..................................................................................................................... 28-7 Text Box ........................................................................................................................................... 28-8 Button ............................................................................................................................................. 28-12 Bevel............................................................................................................................................... 28-16 Frame ............................................................................................................................................. 28-19 Multi-Line Text Box ......................................................................................................................... 28-23 Fill Box ............................................................................................................................................ 28-26 Picture ............................................................................................................................................ 28-30 Check Box ...................................................................................................................................... 28-33 Radio Button................................................................................................................................... 28-37 Combo Box ..................................................................................................................................... 28-41 Marquee ......................................................................................................................................... 28-47 Subformat ....................................................................................................................................... 28-50 Chart............................................................................................................................................... 28-55 More about the Input property ................................................................................................. 28-57 More about column colors ....................................................................................................... 28-58 Table............................................................................................................................................... 28-59 More about tables .................................................................................................................... 28-66
xiv System Tailoring, Vol. 1
Tab ..................................................................................................................................................28-67 More about tabs .......................................................................................................................28-69 Wrapping Label ...............................................................................................................................28-70 More About Wrapping Labels...................................................................................................28-74 OLE Container ................................................................................................................................28-75 More about OLE Containers ....................................................................................................28-78
Chapter 29: The Form Wizard

Accessing the Form Wizard ..............................................................................................................29-2 Creating a Form Using the Form Wizard ..........................................................................................29-4
Chapter 30: Tutorial: Creating a New Form

The Practice Form ............................................................................................................................30-2 Placing design objects on the practice form...............................................................................30-2 Creating the Form .............................................................................................................................30-3 Saving the Form and Creating a File ..............................................................................................30-10 Saving the form ........................................................................................................................30-10 Creating a File ..........................................................................................................................30-11 Modifying an Existing Form.............................................................................................................30-13 Using the Options menu...........................................................................................................30-15
Chapter 31: Designer Tips

Form Style Guidelines.......................................................................................................................31-2 Understanding ServiceCenter screen layouts ............................................................................31-2 ServiceCenter default fonts ........................................................................................................31-2 Using the Courier font ................................................................................................................31-3 Style guidelines ..........................................................................................................................31-3 Rules of good screen design......................................................................................................31-4 ServiceCenter and Bitmaps ..............................................................................................................31-6 Adding a bitmap to an object......................................................................................................31-6
Contents xv
Graphics and Animation ................................................................................................................... 31-8 Optimum performance and image appearance ......................................................................... 31-8 Text and graphics ...................................................................................................................... 31-8
xvi
Chapter 1 The Document Engine

The Document Engine provides a means to customize ServiceCenter without touching the RAD layer of the product and provide consistent behavior across modules for standard actions, such as list, view and search. Prior to ServiceCenter 4.0, system administrators and implementers had to set behavior for users and groups for each module using Format Control or the modules own security. The result would often be different behavior across modules for like actions. The Document Engine provides a central point for setting privileges and behavior across modules. The Document Engine controls behavior with Objects. An Object, cm3profile for example, is referenced whenever a form is opened and determines behavior for the state of the form, (open, list, search, etc.) regardless of the module one is starting from. Implementers can therefore change behavior easily for standard actions across ServiceCenter in one place with one Object. The Document Engine comprises Objects, States, and Processes to centralize tasks. Peregrine ships default Objects, States, and Processes. The Document Engine is designed to meet the needs of most customers out of the box, yet still retain flexibility. Before making changes to any Objects, States, or Processes, Peregrine recommends making a backup of the files you modify. The relation between Objects, States, and Processes is hierarchical: Objects are made up of States and Processes, and are called from the module. States dictate to the Object what to do under a set of circumstances. For instance, States can determine an action, such as Save, given a users access privileges. States are made up of Processes. Processes use RAD expressions to perform work.
Implementers can use the 80 or so Processes shipped with ServiceCenter to build their own States and Objects.
The Document Engine
1-1
Accessing the Document Engine

To access the Document Engine: 1. Start a ServiceCenter Client and log in as an administrator. 2. Click the Utilities tab in the ServiceCenter main window. 3. Click the Tools button. 4. Click the Document Engine tab. From here, you can access the three areas that control the Documentation Engine: select either Objects, States, or Processes.
Objects
Objects are a base set of definitions that determine behavior of screens and panels and set the definitions and governing rules for behavior. Objects should correspond on a one-to-one basis with dbdicts. Each file within ServiceCenter can have an associated Object record, although it is not required. If a file does not have an associated Object record, the Default Object is used.
Objects Shipped with ServiceCenter

There are 24 pre-defined Objects shipped with this version of ServiceCenter. For a list of the Objects shipped with ServiceCenter, perform a true search from the Objects panel.
Creating Objects
To create an Object: 1. Access the Document Engine panel. See Accessing the Document Engine for steps. 2. Click Objects. The Objects panel opens. 3. Using the tabs on the Objects panel, fill in the fields required to create an Object that will perform the functions you desire. See the field descriptions that follow.
1-2
Figure 1-1. Object Info Tab
Fields on the Objects panel

There are five tabs available on the Objects panel. The field descriptions below all use the omcq Object panel as an example.
The Object Info Tab

General properties and Object behavior are specified with the fields under the Object Info tab. File Name - Enter a file name for the object. We recommend using the dbdict name that this object corresponds to. Common Name - Enter a common name for the object. The common name can be a simple name, such as request, or a number that corresponds to a number in the sc.message file Unique Field - The Unique Field for the Object should match the corresponding dbdict unique key field. Description Field - Enter a short description of the Object, if desired.
The Document Engine
1-3
Profile Application - Enter the RAD application or profile that determines if a user can perform certain functions, such as add, delete, and so on. For example, rm.environment. Profile Variable - This field is optional. Enter a variable that can be accessed any time this Object is called, without accessing the environment record. For example, $G.ocmq.environment. Open State - Enter the State to use upon opening. For example, rmq.view. List State - Enter the State to use for listing results. For example, rmq.list. Default State - Enter the default State of the Object. For example, rmq.view. Search State - Enter the State to use for searching. For example, rmq.search. Browse State (text mode only) - Defines the State to use when records use locking. Essentially, this field defines a read-only State. Number Record Name - This field is optional. Define a number class inside the object, which can be referred to in a Process or RAD code. Category File Name - Enter the file name that links with the category file associated with this Object, if applicable. When displaying a record of this type, if a field called category exists, then the Object will go to the Category file and select a record with a corresponding name. If found, the system will store the Category File Name as a variable: $L.catagory Phase File Name - Enter the file name that links with the phase file associated with this Object, if applicable. When displaying a record of this type, if a field called phase exists, then the Object will go to the Phase File and select a record with a corresponding name. If found, the system will store the Phase File Name as a variable: $L.phase. Paging File - Enter the name of the file to store pages in. Pages are created every time a record is updated, creating a detailed audit trail.
1-4
The Locking Tab

The locking panel is used to determine the locking behavior for the Object.
Figure 1-2. The Locking Tab
Use Locking - Select this check box to enable locking. Lock Parent Record - Locks the parent record. Selecting this feature locks the record you are on, and the records parent. Parent Id Field - Enter a field name in the current record that contains the ID of the parent. Parent File Name/Object - The name of the file that contains the parent record.
The Document Engine
1-5
Variable/Global Lists Tab

The Variable/Global Lists Tab is where you set local variables and global list properties. Global lists are built and stored in memory and available to the Object for as long as the Object persists.
Figure 1-3. The Variable/Global Lists Tab
Local Variables - Enter a list of local variables that are not part of the base function, but can be used in Processes. Local variables are defined by the user and must exist prior to being called. Local variables are assigned to the Object you are creating and are available to all Processes and States associated with the Object. Local variables are not available to other Objects. Global Lists - Global lists, once created, are available to all Processes. Global lists can be run on login, if it exists in the global list file. Global lists are available every time you access the Object.
1-6
The Alerts Tab

The Alerts tab is where you set variables and conditions for alerts. Any object that has a unique key can use these alerts.
Figure 1-4. The Alerts Tab
Alert Location - Specify the location to store alerts. You can enter one of the the following: phase: Store alerts in the Phase record defined on the Object Info tab. category: Store alerts in the category file defined on the Object Info tab. record: Store alerts in the record itself.
Alert Condition - Enter a logical condition to determine whether or not to process the alert. For example, open in $L.file~=false Alert Field Name - Enter the field name that contains the actual alert name, as defined by Alert Location. Alert Status Field - Enter the field in the current record in which to put the alert status, after the alert is processed. Alert Update Process - Enter additional functions that the system will
The Document Engine 1-7
perform after the alert runs. Log Alerts? - If selected, then alerts are logged to the Alertlog file. Process Alerts Against Parent? - If you have selected the Locking Parent Record field on the Locking/Revisions tab and you select this checkbox, then when the alert is activated it will register against the parent record.
The Approvals Tab

The Approvals Tab is where approval and notification options are set for the Object. Approvals are defined in the ApprovalDef file.
Figure 1-5. The Approvals Tab
Denial Type - There are three pre-defined denial types: immediate: The record is denied as soon as one member of the approving group issues a denial. quorum - The record is denied or approved, based on majority opinion. one - Only one approval needed.
Approval FC - Enter the Format Control record to run after approval.

1-8 System Tailoring, Vol. 1
Approval Process - Enter the Process that runs when the record is approved. Denial Process - Enter the Process that runs when the record is denied. Single Approval Notification - Enter the notification that will evaluate against the record. Single Denial Notification - Enter the notification that will evaluate against the record. Single Retractions Notification - Enter the notification that will run when retracting a previous action. Final Approval Notification - Enter the notification that will evaluate against the record. Final Denial Notification - Enter the notification that will evaluate against the record. Log Approvals? - Select this check box to log approvals.
States
States are called by Objects, and defined by Processes. ServiceCenter ships with over 40 pre-defined States.
Creating States
To create a new State: 1. Access the Document Engine. See Accessing the Document Engine on page 1-2 for steps. 2. Using the tabs on the States panel, fill in the fields required to create a State that will perform the functions you desire. See the field descriptions later in this chapter. To modify an existing State: 1. Access the Document Engine. See Accessing the Document Engine on page 1-2 for steps. 2. Enter the name of the State you want to modify in the State field, or press Search to search for the State.
The Document Engine
1-9
Figure 1-6. The States Panel
Fields on the States panel

State - Enter the name of the State. Display Screen - Enter the Display screen to associate with the State. Format - Enter the Format that the record will be displayed in. This format is stored as a phase or category, and can be a variable. Input Condition - The Input Condition determines whether or not the record is read only. Enter False for read only condition, otherwise enter True. Initialization Process - Enter the name of a Process to run prior to running the State. Display Action- The action parameter that comes from a display action, after input from user. Process Name - The Process that the State will call. Condition - Enter an expression. If True, then the process will run.
1-10
Save First - Choose to run the save Process, before you run this State. Enter True to save first, otherwise enter False.
Processes
Processes are the smallest discreet units of work available to the Document Engine and are the level where the data is manipulated. Users can create their own Process or use one of the 80 Processes that ship with ServiceCenter. The Process panel consists of pre-RAD, RAD, and post-RAD expressions, entered on the Initial Expressions, RAD, and Final Expressions tabs, respectively. Expressions are written using standard ServiceCenter expressions.
Creating Processes
To create a Process: 1. Access the Document Engine. See Accessing the Document Engine for steps. 2. Using the tabs on the Process panel, fill in the fields required to create a Process that will perform the functions you desire. See the field descriptions later in this chapter. To modify an existing Process: 1. Access the Document Engine. 2. Enter the name of the Process you want to modify in the Process Name field, or press Search to search for the Process.
The Document Engine
1-11
The Process Panel

The Process panel is where you define new Processes, or edit exiting Processes. Process Name - The name of the process. Run Standard Process when complete? - If selected, then the system runs a standard process after completing the current action or Process.
The Initial Expressions tab

Initial expressions run prior to the RAD code defined on the RAD tab and are written using standard ServiceCenter expressions. Enter any initial RAD expressions on the first available line of the table.
Figure 1-7. The Process panel
1-12
The RAD tab
Figure 1-8. The RAD tab
Expressions Evaluated before RAD call - Enter an expression to run prior to the RAD arrays defined later on this panel. RAD Application - Enter the name of the RAD application to associate with this record. Condition - Enter a condition associated with the RAD Application field. Names - Enter the parameter names to be passed to the RAD application. Values - Enter parameter values to pass to the RAD application. Post RAD Expression - Enter a RAD expression that will run upon completion.
The Document Engine
1-13
The Final Expressions tab

Final expressions are associated with the base action from the state record. Final expressions run after this process is complete and are written using standard ServiceCenter expressions. Next Process - Enter the Name of the next Process to run, if applicable. Condition - Enter a condition associated with the Next Process field.
Standard Variables
The following is list of available Standard Variables: $L.action - the display action value from the display option. $L.sql - the current query $L.sort - the current sort order $L.exit - internal exit parameter $L.file - The current file variable $L.mult - Flag that is true if there are multiple records in the $L.file variable $L.env - The current environment record $L.object - The object record $L.file.save - A copy of the record in its original state $L.category - The category record (if available) $L.phase - The phase record (if available) $L.bg - Background flag Variables that are available in View mode (when viewing a single record) $L.fc - associated format control record
1-14
Chapter 2 Introduction to the Database Manager

Chapters 2 through 8 of the System Tailoring Guide cover the Database Manager. The Database Manager application, with its form and associated Database Dictionary, allows you to access and manage the database at three levels: Single-record leveladd, update, delete, retrieve, load, and unload individual records. Multiple-record levelperform all the single-record functions on a subset of the records in a database. File levelrebuild the keys to a database file or empty a database file.
The chapter breakdown for the Database Manager application is: Chapter 2, Introduction to the Database Manager - Provides a brief description of the follow-on chapters and describes accessing the Database Manager. Chapter 3, Record Use - Covers retrieving records within a database using the PEREGRINE FOUR/QBE (Query-by-Example) and via the Query Window. Chapter 4, Single Record Functions - Describes performing singlerecord functions (add, update, delete, print). Chapter 5, Multiple-Record Functions - Describes performing multiple-record functions (add, update, delete, print), as well as unloading data from ServiceCenter and loading data into ServiceCenter. Chapter 6, Database Record Auditing - Covers database auditing Chapter 7, File Maintenance - Describes file maintenance functions. Chapter 8, Unload Script Utility - Covers creating an unload script utility.
Introduction to the Database Manager
2-1
Administration Mode
When logging in with System Administrator rights (SysAdmin capability word), users will see an Administration Mode checkbox. The ServiceCenter Database Manager now runs in two modes, standard and administrative. In standard mode, behavior is determined by whatever security you have in place. Request management, for example, would use Request security. The standard database would use Format Control. In standard mode, an administrator does not necessarily see all options. Options that are potentially troublesome for the system, mass-updates, regenerating keys, etc., are kept out of sight, so as to prevent accidental usage. In Administration Mode, (the checkbox selected) a system administrator will have rights to ALL options. Administration Mode can be thought of as similar to root privileges on UNIX systems. Administration Mode is powerful in that you can make changes that affect the system as a whole, and as a result, can be dangerous. Peregrine recommends that day to day administration work be done in standard mode. Only users with the SysAdmin capability word defined in their Operator file will see the Administration Mode checkbox.
Accessing a Record from the Database Manager
1. Log in as an administrator. Use FALCON in the default system. 2. Access the Toolkit tab in the home menu. 3. Click Database Manager.
2-2
The Database Manager dialog box is displayed.
Figure 2-1. Database Manager Dialog box
4. To open a record, enter the name of a form in the Form field or a file in the File field. You also can leave the fields blank to return a list of all records. 5. Click Search. If you left the fields blank or more than one record matches the search criteria, a QBE list is displayed. Select one of the listings. A blank form is displayed. 6. Enter any information that you might know. For example, you might enter known information in key fields such as names of operators, names of devices, or problem numbers. Note: Searches against fields that are not keyed will slow your search. 7. Click Search. A record list is displayed along with the highlighted record. If multiple records are available, click on the record that you want to see.
2-3
Introduction to the Database Manager
2-4
Chapter 3 Record Use

Retrieving Records from Within a Database
Records are found based on particular user-provided search criteria (query). Two methods are used to query records from a ServiceCenter database. Simple queries are defined via the QBE (Query-by-Example) method. More complex queries are defined via the Query Window method. Queries are logical expressions that evaluate to either true or false against each record (i.e the record matches the search criteria or not). If true, the record is retrieved. If false, the record is not retrieved, and an error message is displayed. Database Manager searches for records that match the query (using either method) and displays a list of matching records on a QBE list. A QBE list is a specific form displaying pertinent field values from each record found in the search. If a customized QBE list format for this list is not created by the user, ServiceCenter will create one (<filename>.qbe) based on key fields defined in the database dictionary for this file. (Refer to the Introduction to Forms Designer, page 23-1 for instructions on creating a QBE list format.) The user then selects a record from this list by positioning the cursor on the desired record and double-clicking or pressing Enter. If the search criteria uniquely defines only one record, that record is displayed using the form used to define the search, or the one defined by a form name in the record depending on format control. If the search criteria does not find any records, the message No records found to satisfy QBE search argument(s) is returned.
Administration Mode
When logging in with System Administrator rights (SysAdmin capability word), users will see an Administration Mode checkbox. The ServiceCenter Database Manager now runs in two modes, standard and administrative. In standard mode, behavior is determined by whatever security you have in place. Request management, for example, would use Request security. The standard database would use Format Control. In standard mode, an
Record Use 3-1
administrator does not necessarily see all options. Options that are potentially troublesome for the system, mass-updates, regenerating keys, and so on, are kept out of sight, so as to prevent accidental usage. In Administration Mode, (the checkbox selected) a system administrator will have rights to ALL options. Administration Mode can be thought of as similar to root privileges on UNIX systems. Administration Mode is powerful in that you can make changes that affect the system as a whole, and as a result, can be dangerous. Peregrine recommends that day to day administration work be done in standard mode. Only users with the SysAdmin capability word defined in their Operator file will see the Administration Mode checkbox. Placing the capability word AlwaysAdmin in a users operator file puts that user in Administration Mode by default.
Retrieving records using relational and logical operators

Both the QBE Method and the Query Window Method require the use of relational operators and logical operators.
Relational operators
A relational operator makes a comparison, then generates results based on whether the comparison is true or false. The relational operators are defined in the table below:
Table 3-1. Relational Operators Relational Operator # Definition starts with (Starts with is used if no other relational operator is specified, starts with (#) is the default) does not start with
# (MVS) ~# (UNIX) = = (MVS) ~= (UNIX) <> >< <
equal to not equal to
less than
3-2
Table 3-1. Relational Operators Relational Operator <= or =< > >= or => isin like less than or equal to greater than greater than or equal to is element in is similar to (This operator is used only when querying character fields and enables wildcard searches on these fields.) Definition
Note: Queries using the equal to relational operator are more efficient than queries using other relational operators and should be used whenever possible. Queries using the equal to relational operator are valid on all types of fields, although the equal to operator is seldom useful when querying date/time fields. Use the greater than (>) operator when querying on date/time fields since these values include seconds which make the equal to (=) operator impractical. For example, if you are querying for records in the problem file that were opened at 11 a.m. on June 1st. It is unlikely a record was opened exactly at 11 a.m. (i.e., 11 hours, 00 minutes, 00 seconds), so an equal to query is not advisable. However, querying with >06/01/92 11:00 in the open.time field retrieves every record opened after 11 a.m., starting with 1 second after 11 a.m.
Logical operators
A logical operator evaluates one or two boolean (true/false) expressions and determines whether the entire expression is true or false, based on the operator. Logical Operators, syntax choices, and their symbols are as follows:
Table 3-2. Logical Operators Logical Operator NOT AND OR NOT and AND OR or Syntax Symbol (MVS) ~ (UNIX, WinNT) & |
The relational and logical operators are demonstrated throughout this chapter.
Record Use
3-3
ServiceCenter uses keys, identifying fields in files, to select data efficiently. If a partially-keyed or non-keyed query is detected in Database Manager, the operator is warned so that the search can be abandoned. The ability to perform partially-keyed queries and the ability to modify search interval parameters is controlled via partial.key system capability words. Capability WordDescription
partial.key partial.key.msg.skip mod.time.limit
Allows operator to execute a partially keyed or non-keyed query. Allows operator to bypass the partial key warning screen. Allows operator to modify the default time limit for partially keyed or non-keyed database searches.
Used in combination, these capability words help control performance degradation due to inefficient queries. Refer to the ServiceCenter System Administrators Guide for more information on capability words.
3-4
Retrieving Records via the P4/QBE Method

P4 (PEREGRINE FOUR)/QBE (Query-by-Example) is a standard feature for accessing records in a database. It is most frequently encountered at prompts where a form or file name is required. To retrieve records via a QBE search: 1. Enter the desired values on any form displaying a Filename, Fieldname or other prompt. 2. Press Enter. The query will be processed looking for similar examples, based on the values the user enters at the prompt fields. These QBE search values can be made more efficient through the use of relational operator characters recognized by the P4 Database.
Retrieving records using the starts with (#) relational operator

The following example demonstrates retrieving all enduser records with the field that begins with the letter O. 1. Access the Database Manager. 2. Enter a form name in the Form field. For example, use capability. 3. Click Search. 4. Select a record from the QBE list, if one is displayed. Following the example, select capability in the Format Name column. 5. Enter a letter in a field For example, enter O in the Capability field. 6. Click Search. Note: Database Manager automatically assumes that values entered into character type fields are intended for a starts with query and prefixes the value entered ("O") with the # symbol. However, this is not true if the value that has been entered contains any wildcard characters ("*" or "?"). In that case a like query is generated. If you want to do a starts with query containing a wildcard character, enter a # character in front of the value Database Manager performs the starts with search and displays the record list of matching records, if any, using the capability form. Notice that all values listed under the Capability heading start with O in figure 3-1 on page 3-6.
Record Use 3-5
starts with O /#O
Figure 3-1. . Record List
7. Click on the listing for the record that you want to see.
Retrieving records using the equal to (=) relational operator

The following example demonstrates retrieving all device records where the location field is equal to Del Mar. Note: Queries using the equal to relational operator are more efficient than queries using other relational operators and should be used whenever possible. Queries using the equal to relational operator are valid on all types of fields, although seldom useful when querying date/time fields. 1. Access the Database Manager. 2. Enter the form name =device in the Form field. 3. Click Search. The device form is displayed. 4. Enter =Del Mar in the location field. 5. Click Search. Database Manager performs the equal to search and displays the record list of matching record(s), if any, using the device form.
The matching records are displayed.
Figure 3-2. Result of using equal to
Note: Since the = operator was prefixed to the value being searched for (Del Mar), the Database Manager searches the device file for any records that have the EXACT value entered (Del Mar). Notice, all values listed under location have the EXACT value of Del Mar. 6. Click on the record that you want to view.
Retrieving records using the greater than (>) relational operator

The greater than (>) operator can be used for any field type. It is most frequently used when querying on date/time fields because these values include seconds which make using the equal to (=) operator impractical. For example, if you are querying for records in the problem file that were opened at 11 a.m. on June 1st, it is unlikely that a record was opened exactly at 11 a.m. (i.e. 11 hours, 00 minutes, 00 seconds). An equal to query therefore
Record Use 3-7
is not advisable. However, querying with >06/01/92 11:00 in the open.time field retrieves every record opened after 11 a.m., starting with 1 second after 11 a.m. The following example will demonstrate retrieving all enduser records with the logical.name field value greater than a character value of d. 1. Access the Database Manager. 2. Enter the form name =device in the Form field. 3. Click Search. The device form is displayed. 4. Enter >d in the Asset field. 5. Click Search. Database Manager performs the greater than search, and displays the QBE list of matching record(s), if any, using the device form. The matching records are displayed.
Figure 3-3. Result of using greater than
6. Click on the record that you want to view.
3-8
Retrieving records using the less than (<) relational operator

The following example demonstrates the retrieval of all device records where the IP Address field value is less than a character value of 196. 1. Access the Database Manager. 2. Enter the form name =device in the Form field. 3. Click Search. The device form is displayed. 4. Enter <196 in the IP Address field. 5. Click Search. Database Manager performs the less than search and displays the record list of matching record(s), if any, using the device form. The matching records are displayed.
Figure 3-4. Result of using less than
6. Click on the record that you want to view.
Record Use
3-9
Retrieving records using the not ( MVS, ~ UNIX) relational operator

The not operator is used with one of the other relational operators to exclude certain records from a query. For example: =ibm (MVS) ~=ibm (UNIX and Windows NT) #ibm (MVS) n#ibm (UNIX and Windows NT) Note: The symbol is used in the MVS environment, whereas the UNIX equivalent symbol is ~. As the = was not entered in the query, the search assumes the query is not starts with the value i, rather than querying with not equal to. The following example demonstrates retrieval of all enduser records EXCEPT those with a value in the vendor field starting with the character i. 1. Access the Database Manager. 2. Enter the form name enduser in the Form field. 3. Click Search. The enduser QBE list is displayed. 4. Select the appropriate enduser record from the list. 5. Enter i or ~i (depending on your system) in the vendor field. 6. Click Search. Database Manager performs the not starts with search, and displays the record list of matching record(s), if any, using the enduser.qbe format. 7. Click on the record that you want to view.
Retrieving record using the like relational operator

The following example demonstrates retrieval of all contacts records that have a "e" as the second letter of their last name. 1. Access the contacts database from the support tab in the system administrators home menu. 2. Enter ?e* into the field labelled Last Name and click search. The database manager performs the search and displays the record list of matching records. In this case the records matched the query: last.name like "?e*" See figure 3-5.
3-10
Figure 3-5. Wildcard query using the Like operator
Because the database manager found two wildcard characters in the last name that was entered, it automatically generated a like query. If you want to find all records that start with ?e* you have to enter #?e*. The leading # character indicates that you want to perform a starts with query. The wildcard characters * and ? represent any character. So if you want to search for these characters literally, you have to prefix these characters with the \ character. For example, if you want to find all records that start with any character followed by an e and then followed by a * character, you have to enter ?e\* into the field labelled Last Name. This still generates a like query (because the ? is a wildcard character) but verifies that the last name ends with a literal *. From the above record list no record in this example be displayed. Instead, records with a last name of Ae*, be*, ?e* or *e* would be retrieved and displayed by the database manager. Because like queries perform a completely different comparison when reading the data records, they do not automatically perform a starts with query as well. In the last example, only records are displayed with exactly three characters in the last name. If you want to see all records that start with any character followed by e* and then have any number of any characters you
Record Use 3-11
have to enter ?e\**. The characters *, ? and \ as they are described here can be modified to any other character by using the parameter wildcardcharacters in the sc.ini file residing on the ServiceCenter server.
Retrieving all records in a database

The following example demonstrates retrieval of all device records. This is a true query. All records in the device file will match the search criteria. 1. Access the Database Manager. 2. Enter the form name =device in the Form field. 3. Click Search. The device form is displayed. When Search is run from a BLANK form, a true query is performed, which returns a list of all records for that file. 4. Press Enter now with no values in any of the fields. Database Manager performs the search and displays the record list of the records using the device format. In this example, the list contains all device records. 5. Click on the record that you want to view.
3-12
Figure 3-6. Result of retrieving all records
Retrieving records using more than one field

The following example demonstrates retrieval of all device records with a logical.name (asset) starting with p and an IP address greater than 196.76.209. installed. 1. Access the Database Manager. 2. Enter the form name =device in the Form field. 3. Click Search. The device form is displayed. 4. Enter the value p in the Asset field 5. Enter the value >196.76.209 in the IP Address field. 6. Click Search. A record list of matching records is displayed. When a partially-keyed query is executed, ServiceCenter searches the file for a specified interval or until the screen buffer is filled, then stops and displays the records retrieved so far.
Record Use
3-13
Figure 3-7. Result of a multiple field query
7. Click on the record that you want to view Reminder: A warning screen, indicating an attempt to initiate a partiallykeyed query may be displayed, depending on your operator and user profile, which in some cases restricts users from initiating inefficient queries.
If you receive a warning screen regarding an inefficient query, perform the following steps: 1. Enter a time interval. 2. Click Search again to continue the search. Database Manager performs the search and displays the record list of matching records, if any, using the device format. In this example, the list contains device records which met the search of both criteria.
3-14
Important: Database Manager always forms QBE queries on scalar (nonarrayed) fields with the logical operator AND.
Retrieving records using array fields

The following example demonstrates retrieval of all operator records with the execute capability words of SysAdmin or problem management. 1. Access the Database Manager. 2. Enter the form name operator in the Form field. 3. Click Search. The operator form is displayed. 4. Select the Startup tab to display the operator start-up parameters. 5. Enter =SysAdmin in the first field of the Execute Capabilities array. 6. Enter =problem management in the second field of the Execute Capabilities array.
Figure 3-8. Operator record Startup tab
7. Click Search. Database Manager performs the search and displays the record list of matching record(s), if any, using the operator.qbe format. In this example, the records found met the search of cap.exec="SysAdmin" or cap.exec="problem management".
Record Use
3-15
Important: Database Manager always forms QBE queries on array fields with the logical operator OR.
The record list is displayed containing the records that match the search criteria. See Figure 3-9.
Figure 3-9. Operator Record List
Note: The position of an element (any of the input lines) within an array is irrelevant when it comes to queries. Even though the preceding query was formed with =SysAdmin in element 1 and =problem management in element 2, it retrieves operator records with either value in any position in the array.
3-16
Menu controls
Clearing an initial record
If you need to redo an incorrect record or need otherwise to clear all data from an initial record form, this data can be quickly and completely removed with a Clear command. To clear all data from an initial screen: 1. Pull down the Options menu, 2. Select Clear. 3. Click Back to return to the initial option keys.
Performing IR Expert queries

If the user wants to run a more intelligent query against the database, the query can be more accurately defined within Database Manager by using the IR Expert utility (Intelligent Retrieval engine), via the IR Query option. To exercise IR Expert to pass a query, use the following steps: 1. Pull down the Options menu, 2. Select IR Query. Refer to the Data Administration Guide for more information on IR Expert. 3. Click Back or Exit to return to the initial option keys.
Record Use
3-17
Retrieving Records via the Query Window

The Query Window method permits you to retrieve records by entering a query expression directly into the query pop-up window and pressing Enter. Database Manager searches for records that match your query and displays a list of matching records. If the search criteria uniquely defines one record, Database Manager displays the record itself instead of a list. The expression entered into the query window is a logical expression - one that has a value of either true or false. Its value is calculated for each record examined by the query, and it retrieves only those records whose expressions evaluate to true. Note: Access to the query window is controlled by one or more capability words. Refer to the ServiceCenter Administrators Quick Start Guide for detailed information on capability words.
Accessing the query window

1. Access the Database Manager. 2. Enter the form name =operator in the Form field. 3. Click Search. The operator form is displayed. 4. Select Options > Advanced Search from the menu bar. Several options are available, depending on the users execution capabilities: If the user has query window access, the query window pops up immediately at the bottom of your screen. If the user has stored query access and stored queries have been defined, a list of them is displayed. If the user has access to both, the query window pops up and buttons defining query options are displayed on the main form.
3-18
The query window and query buttons are shown below.
Figure 3-10. Advanced Search Window
Using the query window

The following example demonstrates retrieval of all device records with logical name starting with the character value p. 1. Access the Database Manager. 2. Enter the form name =device in the Form field. 3. Click Search. The device form is displayed. 4. Select Options > Advanced Search from the menu bar. A blank query.prompt format is displayed. 5. Enter the query expression logical.name#"A".
Figure 3-11. Search window
6. Press the Execute Search button.
Record Use
3-19
Database Manager performs the starts with search and displays the QBE list of matching record(s), if any, using the enduser.qbe format. Notice all values listed under the logical.name heading start with A. 7. Click on the record that you want to view.
Figure 3-12. Device Record
Retrieving records with a simple query expression

The Query Window method is most useful when performing simple queries in situations where a QBE query cannot be performed. For example, the desired field exists in the database dictionary record of the file, but it is not displayed on the form, or the input field on the format is not long enough to contain the desired value. The query.window application used in Database Manager, Incident Management, and Inventory Management allows specification of sort fields.
Important: To use this function, a user must have query.window capability to open the Query Window. defined in the operator record.
1. Access the Database Manager. 2. Enter the form name =operator in the Form field. 3. Click Search. The operator form is displayed. 4. Access the Startup tab. 5. Enter menu.manager in the Initial Application RAD Name field. 6. Select Options > Advanced Search from the menu bar. The query.prompt format is displayed with the query application.name#"menu.manager" (application.name field input value starts with menu.manager). 7. Enter full.name as the first sort field. 8. Enter name as the second sort field.
Figure 3-13. Operator form with Advanced Search
9. Select Options>Select Sort.

Record Use 3-21
The keylist form is displayed with a list of keys defined for the selected file. See figure 3-14. This feature is particularly useful in ensuring fullykeyed queries. 10. Enter the key number (3 for this example). Selecting 3 places the application.name key in the query.
Figure 3-14. Keylist form
Note: Entering 2 in this example would pass the sort command on the same query as entered in steps 7 and 8, using full.name and name. 11. Press Enter.
Figure 3-15. Search Window with new sort field
You are returned to the query window. The Sort Fields field in the query.prompt window changes to agree with the key definition selected from the keylist window, application.name in this example.
3-22
12. With the new query.prompt values, click the Store button on the main form to store this query directly in the querystored file. The query was built by entering information in fields in the form. Note: The cursor remains busy (such as an hour-glass) when moved from the Advanced Query form to the menu bar. This option is available to users with access privilege capability words of QueryAdmin or query.stored.mod in their operator profile. Both the query and sort fields are copied.
Creating a stored query

To save the updated query as a stored query: 1. Enter a query name in the Name field of the Stored Query Maintenance form. See figure 3-16. 2. Enter the appropriate Access List information (left blank in the figure below). The ServiceCenter users or groups entered in this list are allowed to use this stored query. If the list is left blank, all users can use this query.
Figure 3-16. Stored Query Maintenance form
3. Click Add in the toolbar of the Operator File form to add the query to the querystored file. The user is returned to the query.prompt format with the message Query added to querystored file at the bottom of the screen.
Record Use 3-23
4. At this point, you can click Search to run the query you have created, or use one of the other toolbar button options to modify or choose another query. Note: From the toolbar in the Query Stored form, you can also select Query to display a list of stored queries available for display in the query window, or you can select Clear to clear the information fields from the query.prompt format. 5. For this example, select Query. 6. Double click on the query name to select the desired item from the list. For this example, select operator.SysAdmin. See figure 3-17.
Figure 3-17. Stored query list
The stored query record is displayed.
Figure 3-18. Stored query record
This form provides additional options that allow the user to ensure a fullykeyed query is established. 7. Click Select from the toolbar to choose this query to run as it appears against the opened operator form.
3-24
8. You can also scroll through the records for the other stored query records by using Next and Previous. 9. The Append and Insert options, also displayed in the toolbar, provide you with the option of tailoring your query, using multiple stored queries at the same time. See Stored query options on page 3-25 for details
Figure 3-19. Stored Query Option buttons
Stored query options

The options available for a stored query are:
Option key F1 Function Append using & Definition This option adds another query to the end of your original query with the word AND separating the two queries. This option adds another query to the end of the original query with the word OR separating the two queries. This option inserts another query at the beginning of the original query with the word AND separating the two queries. This option inserts another query at the beginning of the original query with the word OR separating the two queries.
F2
Append using |
F3
Insert using &
F4
Insert using |
Retrieving records with a complex query expression

OR/AND statements
The Query Window method must be used to perform queries that involve combinations of logical operators that are not available using the QBE query method. The following example demonstrates the following complex query against the contacts file: Company is either ACME or GENERICOM and the Contact Name starts with b. 1. Access the Database Manager: Toolkit tab>Database Manager. 2. Enter the form name contacts in the Form field and press Enter. 3. Select the contacts file from the returned list and press Enter.
Record Use
3-25
4. Select Options > Advanced Search from the menu bar. 5. Enter the query expression (company="GENERICOM" or company="ACME") and contact.name#"B" in the query window as shown in figure 3-20. 6. Press the Execute Search button.
Figure 3-20. Search window with complex query expression
Note: Logical operators are executed in the following order: NOT, AND, OR. When the operators have equal precedence, they execute from left to right. This query may result in a partially-keyed search. a. If so, enter a time limit for running the query. b. Press Enter to search again. Database Manager performs the starts with search and displays the record list of matching records, if any, using the enduser.qbe format. Notice all values listed under the logical.name heading start with a. 7. Select the enduser device record that you want to view. If the same expression is added without parentheses: company=GENERICOM or comapny=ACME and contact.name#B Since the AND operator takes precedence over OR, this query would retrieve records satisfying a condition very different from the above example: company is GENERICOM OR company is ACME and contact.name starts with B
Isin statements
The following example shows how the above example can be solved, too. Repeat the steps as described in the above example until step 5. Enter the following query expression:
company isin {"GENERICOM", "ACME"} and contact.name#"B"

Click the Search button. The database manager displays all records whose logical name starts with B and whose company is either GENERICOM or ACME. This query expression is equivalent to the first query in the above example.
not statements
The following example demonstrates retrieval of all enduser records with a company value other than GENERICOM and assumes the not symbol is not available on the keyboard. 1. Enter the query expression not (company="GENERICOM") in the query window as shown in figure 3-21. 2. Press the Execute Search button.
Important: Leave a space between not and left parenthesis ( .
Figure 3-21. Search window using not
Database Manager performs the not equal to search and displays the record list of matching record(s), if any, using the contacts.qbe form. 3. Click on the record that you want to view from the list.
Using functions in a query

Greater than/less than(>/<) queries
You must use the query window to perform queries that involve functions. Refer to the System Language topic in Volume 2 of the System Tailoring Guide for a list and description of available functions.
Record Use
3-27
The following example demonstrates retrieval of all operator records with passwords updated within the past 100 days. The same query could be done in the opposite direction for all operators created more than 365 days ago. 1. Access the Database Manager. 2. Enter the form name =operator in the Form field. 3. Click Search. The operator form is displayed. Do not enter any additional information into any of the fields on the form. 4. Select Options - > Advanced Search from the menu bar. 5. Enter the query password.date>tod() - 100 00:00 in the query window. 6. Press the Execute Search button. Database Manager performs the search and displays the record list of matching record(s), if any, using the operator.qbe format. 7. Click on the record that you want to view.
3-28
Figure 3-22. Search results
Identification of characters anywhere in a field value

The following example demonstrates retrieval of all operator records with the character string xy occurring anywhere in the operator name. As always, wildcards are permitted and can be included in the search parameters. 1. Access the Database Manager. 2. Enter the form name =operator in the Form field. 3. Click Search. The operator form is displayed. 4. Do not enter any additional information into any of the fields on the form.
Record Use 3-29
5. Select Options > Advanced Search from the menu bar. 6. Enter the query expression index("xy", name)>0 in the Query field. 7. Press the Execute Search button.
Figure 3-23. Search window identifying characters
Database Manager performs the search and displays the record list of matching records, if any, using the operator.qbe format. 8. Click on the record that you want to view from the list. In this case, the query did not find any records and returns the following message.
Specifying length of character strings in query

The following example demonstrates retrieval of all operator file records with names longer than 5 characters. 1. Access the Database Manager. 2. Enter the form name =operator in the Form field. 3. Click Search. The operator form is displayed. 4. Do not enter any additional information into any of the fields on the form. 5. Select Options > Advanced Search from the menu bar. 6. Enter the query lng(name)>5 in the query window. (note the lowercase L at the begining of the query) 7. Press the Execute Search button.
3-30
Figure 3-24. Search window specifying length of character string
Database Manager performs the search and displays the record list of matching record(s), if any, using the operator.qbe format. In this example, the records found met the search any current operator records with an operator name longer than five characters 8. Click on the record that you want to view from the list.
Record Use
3-31
3-32
Chapter 4 Single Record Functions

The Database Manager function allows the user to perform add, update, delete, print, and unload functions on individual records within a database.
Adding a record
The following example demonstrates adding a record to the contacts file. 1. Access the Database Manager. 2. Enter contacts in the Form field and press Enter. 3. Select the contacts file from the record list and press Enter. 4. Enter the following required values. (Under the Business Information tab)
Table 4-1. Field Contact Name Company Record Value HOSKINS,BOB Acme
5.
Click Add.
Database Manager adds the record, retains the input from the screen displayed and responds with the following message: contacts record added.
Duplicating an existing record

The following example demonstrates adding a new record to the contacts database that is a near duplicate of an existing record. For this example, all information except the Primary asset and Contact Name will be the same. 1. Access the Database Manager: Toolkit tab>Database Manager. 2. Enter contacts in the Form field and press Enter.
Single Record Functions
4-1
3. Select the contacts file from the record list and press Enter. A blank contacts file is displayed. 4. Click search and select BUTLER,RICHARD from the returned list. 5. Click the Business Information tab. 6. Enter a new name in the Contact Name field. 7. Enter a new Primary asset for this record. 8. Delete the Employee ID. You can either add your own at this point or leave this field blank. 9. Click Add. 10. The new contact file is added to the database. Database Manager adds the record, retains the input from the screen displayed and responds with the following message: contacts record added.
Updating an existing record

The following example demonstrates updating an existing contacts record for Heather Chan who has a Primary asset of Acmepc014 and changing the value to Acmepc012. 1. Access the Database Manager: Toolkit tab>Database Manager. 2. Enter contacts in the Form field and press Enter. 3. Select the contacts file from the record list and press Enter. A blank contacts file is displayed. 4. Click search and select CHAN,HEATHER from the returned list. 5. Click the Business Information tab. 6. Replace the current value in the model field with Acmepc012. 7. Click Save Database Manager saves the record and responds with the following message: contacts record updated.
Deleting a record
The following example demonstrates deleting the contact record we added for Bob Hoskins (on page 4-1.) 1. Access the Database Manager: Toolkit tab>Database Manager.
4-2
2. Enter contacts in the Form field and press Enter. 3. Select the contacts file from the record list and press Enter. A blank contacts file is displayed. 4. Query on the existing record by entering Bob Hoskins in the name field, and click Search. Or, click Search and select the record from the returned list. 5. Click Delete. A prompt is displayed asking you to confirm the action.
Figure 4-1. Deleting an enduser record
6. Click Yes to continue with the record deletion. The following message is displayed in the status bar: contacts record deleted.
4-3
Printing a record
The following example demonstrates printing an existing contacts record for Richard Butler. 1. Access the Database Manager: Toolkit tab>Database Manager. 2. Enter contacts in the Form field and press Enter. 3. Select the contacts file from the record list and press Enter. A blank contacts file is displayed. 4. Click Search and select Richard Butler from the returned list. 5. Select Options > Print.
Figure 4-2. Printing a record
Database Manager responds with a print prompt message if your Printer Settings specify you are using the CLIENT printer. Note: If you are using the SERVER printer you may be prompted to select the specific printer to use. A spooling message is then presented at the bottom of the screen, e.g., Rpt spooled and sched as no: nnnnn (ServiceCenter Print Job). See the Printer Setup section in the System
4-4
Administrators Guide for information on using CLIENT or SERVER printers. The entire record is then printed on the printer defined in the operator record for the current operator. If Active Notes in enabled, the following message is displayed: Report <nnn> printed; (ServiceCenter Print Job).
4-5
Advanced Operations
Recovering from record/key conflicts
The following table lists possible record/key conflict errors, a description of each one, and recovery actions.
Table 4-2. Possible Error Messages Error Record contains invalid duplicate key. Description Occurs on add and update functions when a record already exists in the database dictionary with a unique or no duplicates key that is identical to one on the record being added or updated. 1. Recovery If caused by an add function, either rename the record or select the existing record and update it. If caused by an update function, delete the existing record and then add the new one. If duplicates should be accommodated on the database, the keys must be changed within the database dictionary record for this file to allow duplicates in the file for the field(s) in question. Once the dictionary has been changed, you may add or update the record. Enter data into the field(s) defined as no nulls or unique keys and add or update the record. If nulls should be accommodated on the database, the keys must be changed within the database dictionary record for this file to allow nulls in the file for the field(s) in question. Once the dictionary has been changed, you can add or update the record.
2.
3.
Record contains invalid null key.
Occurs on add and update functions when a key is defined in the database dictionary as no nulls or unique and that key for the record being added is null (blank).
1.
2.
4-6
Table 4-2. Possible Error Messages (Continued) Error This record has been changed since you selected it. Description Occurs on update and delete functions when the selected record is no longer current, i.e., the record was updated by another task after you selected it and before you attempted the update or deletion. Occurs on update and delete functions when the selected record has been deleted, i.e., the record was deleted by another task after you selected it and before you attempted the update or deletion. Recovery Reselect the record and proceed with the update or deletion.
The record has already been deleted.
1.
If caused by a delete function, the record has already been deleted and no further action is needed. If caused by an update, the record must be re-added by pressing Add. The record will be added just as it appears on your screen.
2.
Record level options

Several advanced user options exist once a record has been selected. These options are available from the Options menu. Expand Arrayexpands an array field. It opens a window and expands the array, enabling line editing options. This option is most useful in non-GUI versions of ServiceCenter. 1. Locate a field to expand (comments in the contacts form is used in this example). Note: The Expand Array option only works with array fields. Attempts to expand all other fields will return an error message. Use the Magnifying Glass button to expand non-array fields. 2. Place the cursor in the array field. 3. Select Options > Expand Array.
4-7
A new form appears with an extended version of the selected field.
Figure 4-3. Expanded array form
4. The user can now make any necessary additions to the data list or edit data relevant to the particular field. Note: When in an application, the Magnifying Glass can also be used to expand array and scalar (non-array) field alike. This button expands any field (array or scalar), and is more useful with the multi-line text box construction of the GUI versions of ServiceCenter.
4-8
Expand array options
Endchecks for differences and prompts for confirmation. Mark starting lineused to mark the first line of a block to be moved, copied, or deleted; re-displays window to mark last line, then enables move, copy to the line the cursor is on, or delete; move in this case removes the original lines. Insert spaceinserts a space at the start of the line the cursor is on. Delete spacedeletes the first space on the line the cursor is on. Truncateremoves all line values below the line the cursor is on. Insert lineinsets a blank line above the line the cursor is on. Delete lineremoves the line the cursor is on from the array. Copyselects the line the cursor is on and prompts to insert or replace insert places a copy of the field at the specified line, including shifting other
4-9
fields down if necessary, retaining original line, replace replaces line the cursor is on. Movesame as Copy, except it removes the original value from the selected line. Clearremoves all lines in array.
4-10
Format Control Settings

The options and contents of the Options menu in this and all applications are determined by a combination of the RAD application currently executing, Format Control, Additional Options, (only in Database Manager and selected other applications) and Display settings. Options can be created to allow for extended user capabilities and data gathering, including additional views and find/fill functions. For more information on format control maintenance, refer to the Format Control and Display Application sections, starting with Chapter 13.
4-11
4-12
Chapter 5 Multiple-Record Functions

The Database Manager functions which add, update, delete, and print single records can be performed on multiple records as well. The four Mass functions (Mass Add, Mass Update, Mass Delete, Mass Unload) become available whenever a query produces a record list, i.e., the desired function acts upon the records in the QBE list. Note: Depending on whether you have the record list option active, through the Record list option in the View menu, you will either receive a QBE listUnload/Export Utility of records prior to viewing the contents of a record, or the records returned will be listed in a table above the format displaying the contents of the first record in the list. If the record list view is not active, the Mass functions are available only from the QBE in the Options menu. If the record list view is active, the Mass functions are available at anytime while viewing records in the List Options menu.
Multiple-Record Functions
5-1
Adding Multiple Records

Having accessed a list of records from a ServiceCenter file, the Mass Add function allows you to add a block of records to the database. The new records are exact duplicates of those in the original record (or QBE) list. Exact duplicates can only be added to a database which has keys defined as nulls&duplicates or no nulls in the database dictionary, otherwise an invalid duplicate key error message is received for every record. To avoid this error when executing a Mass Add against a file with unique or no duplicates type keys, processing statements should be executed during the Mass Add to manipulate the contents of the new records. Mass Add processing statements reference $file to access fields on records in the QBE list. For example, name in $file or 1 in action in $file. Refer to the System Language section in the System Tailoring Guide for examples of processing statements. Note: Format Control, if present for the current form, is executed for ADD=true processing. Refer to the Format Control section of the System Tailoring Guide for detailed information.
Mass Adding records using a literal value

The following example demonstrates duplicating all enduser records with a location value of alh100, retaining the same information in each record with the exception of changing the location value to br002. Since logical.name is a unique key in the enduser file, unique logical.name values must be assigned to the new records. For this example, the value -b is appended to the source logical.name values to maintain uniqueness. 1. Access the Database Manager. 2. Enter the form name enduser in the Form field. 3. Click Search. 4. Select appropriate enduser record from returned QBE. Database Manager displays the enduser form.
5-2
5. Enter the desired location value preceded by =. For this example, enter =alh100.
Figure 5-1. Querying for records to duplicate
6. Click Search. Database Manager performs the equal to search and displays the record list of matching record(s), if any. Note: If the query produces no matching records, a message is displayed. In order to receive the Mass function buttons, use an appropriate query to return a list of more than one record. 7. Select List Options -> Mass Add to start the process of duplicating the records shown in the list.
Figure 5-2. Calling Mass Add action
5-3
Database Manager displays the Mass Add/Update Instruction screen. 8. Click Cancel to abort the Mass Add. 9. To proceed with the Mass Add, leave the first input field blank. Statements in this field are executed once at the beginning of the add. 10. Enter the following assignment statements on the Instructions for action on EACH RECORD lines:
logical.name in $file=logical.name in $file+"-b" which appends -b to the end of all logical.name values. location in $file="br002" which alters the location value to br002.
These statements will be executed against every record as it is added. 11. Click Execute. Note: The Mass Add function is performed in foreground, which means the session is devoted to the add task until completed.
Figure 5-3. Mass Add action specifications
5-4
Upon completion, terminal control is returned to the user with a message indicating the number of records added. If no audit specification record exists for the enduser file, the following message is displayed: WARNING: An Audit Specifications Record was not found for enduser.
Figure 5-4. Querying for duplicate records, based on modified location
To retrieve the newly added records, Return to the enduser form. 12. Enter =br002 in the location field, and click Search. Database Manager performs the equal to search and displays the record list of matching record(s), if any, using the enduser.qbe format. Note: The logical name values are the same as the original records with -b appended, and the location values are now br002. All other values remain the same as the original.
5-5
Figure 5-5. Record duplicates with modified logical.name and location values
The original records listed before the Mass Add remain in the enduser file with no changes to the original data.
Mass Adding Records Using a Variable Value

The following example demonstrates duplicating all enduser records with a location value of alh100 with all the same information in each record, except changing the location value to br001. Since logical.name is a unique key in the enduser file, unique logical.name values must be assigned to the new records. For this example the logical.name values in the new records become brlu suffixed with a sequential number starting with 100 (e.g., brlu100, brlu101, etc.). 1. Access the Database Manager. 2. Enter the form name enduser in the Form field. 3. Press Enter. A blank enduser form is displayed. 4. Enter the desired location value. For this example enter alh100. 5. Press Enter. All matching records are displayed in a record list.
5-6
Note: If the query produces no matching records, a message is displayed. In order to receive the Mass function buttons, use an appropriate query to produce a record list of more than one record. 6. Select List Options > Mass Add to start the process of duplicating the records shown in the record list.
Figure 5-6. Calling Mass Add action
Database Manager displays the Mass Add/Update Instruction screen. 7. Click Cancel to abort the Mass Add. 8. To proceed with the Mass Add, enter the following assignment statement in the Instructions to be executed ONCE at the beginning of Mass Add/update line.
$sequential.number=100
This condition sets the start point for the variable at 100 and will be executed only once for the entire function. 9. Enter the following statements on the Instructions for action on EACH RECORD lines:
location in $file=bru100which sets the location value in the new records to bru100. logical.name in $file="brlo"+str($sequential.number)which appends -b to the end of all logical.name values. $sequential.number+=1which sets the instruction to add one (1) to all future numbers created from this variable.
These statements are executed against every record as it is added. 10. Click Execute.
Multiple-Record Functions 5-7
Note: The Mass Add function is performed in foreground, which means your session is devoted to the add task until completed.
Figure 5-7. Mass Add instructions
Upon completion, terminal control is returned to you and the following message is displayed in the status bar: <nnn> records added to the enduser file where nnn is the number of records added. 11. Click the Message button to view additional messages. 12. Return to the enduser form. 13. Enter bru100 in the location field, and press Enter.
5-8
Figure 5-8. Querying for new records
The records you have just added are displayed in a record list. Note: The logical.name values listed consist of brlu + 100, 101, etc. Also, the location values listed are now br001. All other field values remain unchanged from the original.
Figure 5-9. Duplicated record with modified name and location values
The original records listed before the Mass Add remain in the enduser file with no changes to the original data.
5-9
Updating Multiple Records

Having accessed a record list of records from Database Manager, the Mass Update function allows the user to enter one or more processing statements which modify the contents of each record in the list. Mass Update processing statements reference $file to access fields on records in the list. For example, name in $file or 1 in action in $file. Refer to the System Language section of the System Tailoring Guide for examples of processing statements. Note: Format Control, if present for the current form, is executed for UPDATE=true processing. Refer to the Format Control section of the System Tailoring Guide for detailed information.
Updating multiple records with a literal value

The following example demonstrates modifying the primary.contact field value to Tony Jones for all enduser records with a location value of alh100. 1. Access the enduser form. 2. Enter the desired location value. For the example, enter alh100. 3. Click Search. All matching records are displayed in a record list. Note: If the query produces no matching records, a message is displayed. In order to receive the Mass function buttons, use an appropriate query to produce a record list of more than one record.
5-10
4. Select List Options > Mass Update from the menu bar to start the process of updating the records shown in the record list.
Figure 5-10. Selecting Mass Update option
The initial format is re-displayed with new option buttons. 5. Enter tony jones in the primary contact field 6. Click Simple update.
Figure 5-11. Defining Mass Update field value
Terminal control is returned to the user with the enduser form and the message nnn records updated in the enduser file where nnn is the number of records updated.
5-11
The newly updated records are displayed in the record list.
Figure 5-12. Displaying records with Mass Updated field value
Updating multiple records with a variable value

The following example demonstrates assigning a sequential number to the fixed asset number field for all enduser records starting with number 100. 1. Access the enduser form. 2. Leave all fields blank. 3. Press Enter.
5-12
Database Manager performs the full search and displays the record list of matching records, if any, using the enduser.qbe form. Note: In this example, a true query has been passed, which produces a list of all enduser records in the database. 4. Select List Options > Mass Update to start the process of updating the records listed. The initial format is re-displayed. 5. Do not enter values in any field. 6. Click Complex update.
Figure 5-13. Displaying records with Mass Updated field value
Database Manager displays the Mass Add/Update Instruction screen. 7. To abort the Mass Update, click Cancel. 8. To proceed with the Mass Update, enter the following assignment statement in the Instructions to be executed ONCE at the beginning of Mass Add/update line as shown. See Figure 5-14 on page 5-14.
$fixed.asset=100
9. This instruction will be executed only once for the entire action. 10. Enter the following assignment statements on the first two Instructions for action on EACH RECORD lines as shown.
$fixed.asset.no in $file=str($fixed.asset) $fixed.asset+=1

These instructions will be executed for each record updated.
5-13
11. Click Execute. Note: The Mass Update action is performed in foreground, which means the session is devoted to the update task until completed.
Figure 5-14. Defining Mass Update action
5-14
Upon completion, terminal control is returned to the user with the message nnn records updated in the enduser file, where nnn is the number of records updated.
Figure 5-15. Updated record list message
5-15
Mass Add/Update Function Errors

Invalid duplicate or NULL key
If an error is encountered in any Mass Add or Mass Update function, the user is prompted to fix the error or skip to the next record. For example: 1. Enter d in the logical name field of the enduser form, and click Search. This query selects all records from the enduser file that begin with d. 2. Select List Options > Mass Update from the menu bar to begin updating the records shown in the record list.
Figure 5-16. Updating record list
The initial format is re-displayed (Figure 5-13) 3. On the displayed format, enter newdev in the logical name field. 4. Click Simple update. The first update is accepted because it is unique; the second is rejected since it is seen as a duplicate and the record is displayed for modification.
5-16
.At this point, a user has several options concerning the outcome of this
Figure 5-17. Record updating error
process: Modify the logical name field value (for example, to newdev2), then click Retry. The following message is displayed in the status bar: This record has changed since you selected it. Click the message button to view all the messages. You are warned if no audit specification record for the enduser file exists. If the command is successful, the following message is displayed: <n> records updated in the enduser file. Click Skip and skip the update on this specific record. Click the message button to view all the messages from this action.
5-17
Deleting Multiple Records

The following example demonstrates deleting all enduser records with a location value of br002. 1. Access the enduser form. 2. Enter the desired location value. For this example use br002. 3. Press Enter. Database Manager performs the begins with search and displays the QBE list of matching record(s), if any, using the enduser.qbe format. Note: If the query produces no matching records or only one matching record, then a QBE list is not displayed. In order to receive the Mass function buttons, use an appropriate query to return a list of more than one record. 4. Select List Options > Mass Delete from the menu bar to remove the records shown in the QBE list from the database.
Database Manager confirms the delete request with a prompt screen. 5. To cancel, click No. 6. To confirm the delete, click Yes. Note: Database Manager deletes all records in the list. The Mass Delete function is performed in the foreground, which means your terminal is devoted to this function until complete. Upon completion, terminal control is returned to the user with a blank enduser.qbe form with the message nnn records deleted from the enduser file, where nnn is the number of records deleted.
5-18
Printing Multiple Records

The following example demonstrates printing all enduser records with a location value starting with alh100. 1. Access the enduser form. 2. Enter the desired logical name value. For this example use alh100. 3. Press Enter. Database Manager performs the equal to search and displays the list of matching record(s), if any. Note: If the query produces no matching records or only one matching record, then a QBE list is not displayed. In order to receive the Mass function buttons, use an appropriate query to return more than one record. 4. Select List Options > Print List to print the records shown in the list. The following printing dialog box is displayed.
Figure 5-18. Print confirmation window for Server printer settings
5. Select from the following printing option: Note: The following options are all present if your printer setup specifies that you are to use the server printer. Only the first two are present if your settings indicate that you are using a client printer: Print List Onlyprints the list exactly as shown with a total count at the bottom. Print All Recordsprints the corresponding records of all items listed Backgroundprints the selection in the background, leaving terminal session free for other operations. 6. Select a printer from the drop-down list or click the printer button to display a list of system printers.
5-19
Figure 5-19. Available system printers
7. Double-click a printer to select it. 8. Select the number of copies you want to print. 9. Click OK. Note: This function, when performed in the foreground, means your terminal session is devoted to printing the records. Upon completion, terminal control is returned to you with a blank enduser format with the message Rpt spooled & sched as no. nnn.
Counting records
The Count (count recds) menu option is a convenient, quick way to determine the number of records in a QBE list. By selecting any record and clicking Count the user can get a clear picture of how many records are contained in a particular list. 1. Access the enduser form. 2. Leave all fields blank. 3. Press Enter. Database Manager performs the full search and displays the record list of matching record(s), if any. Note: In this example, a true query has been passed, which produces a list of all enduser records in the database. The enduser format is displayed with a record list at the top, and the Count (count recds) option in the List Options menu.
5-20
4. Select List Options > Count (count recds).
Figure 5-20. Record count option
The user is prompted as to whether all records in the list are to be counted. 5. Cancel the count call by clicking No. 6. Confirm by clicking Yes. After confirming the process, the records are counted and the following message is displayed in the status bar: There are <n> records in this list.
5-21
Unloading ServiceCenter Data

The Database Manager unload and load functions allow the user to write records to and read records from an external MVS, UNIX or Windows NT file. The contents of the external dataset or file are generally indecipherable to any software other than ServiceCenter, therefore the user needs to use the Import/Export functions to transfer data to or from a source other than ServiceCenter. Refer to the Export and Import section of the Data Administration Guide for more information. The unload function writes data from the current ServiceCenter system to an external dataset or file (as specified by the user) for future loading into the same or another ServiceCenter system via the load function. Load options governing how ServiceCenter later loads the data are also included in the unload file. Note: The unload file is saved to the servers Run directory unless otherwise specified. If you cannot locate the exported file on the client machine, refer to the server Run directory. The unload function always writes out the database dictionary of the record(s) being unloaded. When the file is loaded at a later date, records are directed automatically to the database specified in the unloaded database dictionary, i.e., records unloaded from a database are loaded into a database of identical name. This section discusses the various options available within the Database Manager for unloading records from one ServiceCenter file at a time. In addition, the ServiceCenter Unload Script Utility lets you unload unrelated or related records from many ServiceCenter files at once. The unloaded data formats are identical, whether you use Database Manager Export/Unload or the Unload Script Utility, and the same Datebase Manager Load process is used to load data unloaded via either method. See Creating an Unload Script on page 8-2 for more details.
Unloading a single record from a database

You may want to copy one particular enduser database record from your production ServiceCenter environment into your development system. Accomplishing this involves an unload of the desired record from production, followed by a load from within the development system. 1. Access the enduser form. 2. Use the following steps to select one record from the enduser database to unload:
5-22
a. Enter =a101a01 in the logical name field, and click Search. Note: You can still single out one record to be unloaded even if a record list is returned by first selecting the specific record to view, and then following the instructions in this section. The Export/Unload option only performs on a single record when selected from the Options menu. The corresponding record with this logical name appears.
Figure 5-21. Preparing to unload a record
3. Select Options > Export/Unload. Unload parameters fall into two categories: Those which control how data is written to an external dataset (unload options). Those which control how the same data is to be read back into ServiceCenter via the load utility (load options). Both categories of options are set prior to the actual unload. Unload options control the immediate allocation of the external dataset and the format of the data written to the external dataset. The load options are written to the external dataset along with the unloaded record(s). These load options remain dormant until the external dataset is accessed by the Load utility, at which time they control how the unloaded data is read back into ServiceCenter. See Unload messages on page 5-25. 4. To continue with this example, using the default unload parameters, enter the fully-qualified dataset name to which ServiceCenter will write this single enduser record.
5-23
a. Enter <qualifier>.example1, where <qualifier> conforms to your standard naming conventions for MVS datasets. or b. Enter <path>.example1, where <path> conforms to your standard naming conventions for UNIX or Windows NT files. 5. Click Unload/export to begin the unload.
Figure 5-22. Configuring unload settings
5-24
Unload messages
Table 5-1. Unload Message Message Invalid unload append/create parameter. Select one export format: binary.text or formatted text. Invalid unload dbdict load parameter. Unload mode must be export. Description Parameter must be append or create for the unload append/create input field. Valid entries are binary, text, and formatted text for the unload mode input field. Valid entries are create, replace, and remove for the unload dbdict input field. When an export descriptor record is specified, the unload type must be export for the unload mode input field. Valid entries are update and add only for the record load input field. Occurs when the unload function is accessed without the proper parameters (i.e., from the call panel). Access the unload function from Database Manager instead. Unload requires an external file name. When unloads are accessed via Purge/Archive, the unload format must be binary. Refer to Base
Invalid unload record load parameter. No file is available to load.
No unload file name. The unload format must be binary for Purge/Archive.
Utilities Guide, Chapter 14, Purge/ Archive.

<database name> file unloaded to external file: <MVS file or UNIX filename>. config record: <config name> is not set up to be used for database unloads. Unload processing the named database to the named MVS dataset or UNIX file complete. The true/false field Used for database loads/ unloads: on the configuration record database load/unload.mvs is set to false. It must be set to true. Refer to the Users Quick Start Guide for information on configuration records. Another task has exclusive control over the named external dataset. The unload utility found two or more hardware configuration records named database load/ unload.mvs. There should only be one such record. Refer to the Users Quick Start Guide for information on configuration records.
External file: <MVS.FILENAME> or <UNIX.filename> is locked; try again later. Invalid number of records found in config file.
5-25
Table 5-1. Unload Message (Continued) Message The config record (database load/unload) is missing. Description The hardware configuration record database load/unload.mvs, database load/unload.unix, or database load/unload.winnt required for database loads and unloads has been deleted or renamed. It must be replaced. The hardware configuration record database create.mvs or database create.unix required for the dynamic allocation of an external MVS dataset or UNIX/NT filename has been deleted or renamed. It must be replaced. The unload utility generates this message every hundredth record it attempts to unload. Unload processing nn records from the named ServiceCenter database to the named MVS dataset or UNIX/NT file completed. ServiceCenter could not connect to the named external file. Often, a dataset that cannot be allocated lacks a certain high-level qualifier required by a security facility such as Top Secret, RACF, or ACF2. This message occurs in two distinct situations: (1) The unload utility attempted to connect to a non-existent external dataset causing the message to be generated. However, the unload utility will attempt to dynamically allocate the external MVS dataset or UNIX/NT filename. If the dynamic allocation is successful, confirmation messages will follow. In this situation, it does not indicate an error condition. (2) The unload utility attempted to connect to a non-existent external dataset causing the message to be generated. The subsequent attempt to dynamically allocate the external MVS dataset or UNIX/NT filename failed causing the message to be generated a second time. Other error messages will follow indicating the error condition.
The config record (database create) is missing.
<nn> records unloaded so far from <database name> file. <nn> records from <database name> unloaded into external file: <MVS.FILENAME> or <UNIX/ NT.FILENAME>. <database name> file CANNOT be unloaded to external file: <MVS.FILENAME> or <UNIX/ NT.FILENAME>.
Unable to allocate.
5-26
Table 5-1. Unload Message (Continued) Message Application:file.unload has completed with errors; check other messages. Invalid unload options specified for unload, no records unloaded. Description An error exit was taken; check the message log for the error message indicating which exit. Since the unload options were invalid, no records were unloaded.
Unload form fields

External File Namefully qualified name of the external file to which you want the information written. In the MVS environment, you must enter an existing high level qualifier, or the process will wait on execution for action at the system console. In the UNIX and Windows NT environment, the full path name should be entered if the file is being written to a directory other than the one in which the ServiceCenter files are located. Membername of the member if the external file is an MVS partitioned dataset. Otherwise, leave the field blank. Unload Typedetermines the output format of the data, based on the system to which the data will be written. Options include mswin, winnt, unix, mvs, sun and other common platforms. In the current release, the system takes care of this automatically, depending on the platform where the unload file resides. Append to Existing Filedefault is yes, which indicates that the exported information will be appended to any existing file of the same name, indicated in the External File Name field. If a file of the same name does not exist, one will be created. If the field is set to no, any existing file of the same name will be replaced with the exported information or, if none exists, a file of that name will be created. Use Data Mapdefault is no. If yes, Datamap executes for every record that is unloaded. Refer to the RDBMS Database Administration section of the Data Administration Guide. Prompt Data Mapdefault is no. If yes, and Use Datamap is yes, the Datamap application will display the standard Datamap confirmation screen for every record that is unloaded. Refer to the RDBMS Database Administration section of the Data Administration Guide. Suppress Messagesallows you to ignore all messages produced during the print process, including the final confirmation message. Note: In an MVS environment, remember that you cannot append to a partitioned dataset (PDS) member. When a member is defined, the application ALWAYS creates a new dataset without respect to the parameter entered.
Export Mode
Binarywrites the file in ServiceCenter internal binary formatted mode, which can only be read by the Database Managers Load facility. TextWrites the file in ServiceCenter internal text mode. Exported text can be read by humans, unlike Binary mode. However, it is not formatted for data transfer to external applications. It is only readable by another ServiceCenter system, using the Database Managers Load facility. Formatted TextExports information in a format that can be read by external programs, and structured to match an existing ServiceCenter text (not GUI) format. Form Namename of the format that describes the information to be exported via the Formatted Text Unload/export option. If the format does not exist, you will be prompted to create it.
Import Mode
Use Current File Descriptionused when loading ServiceCenter internal binary or text formatted information. In later releases it is also used in the Export and Import (load) utilities.
Important: When loading a file exported with the above checkbox activated, the file is loaded using the database dictionary file name of the new database dictionary into which the records will be loaded (imported), rather than the file name referenced at the time the file was created.
Update Duplicate Recordsused when loading ServiceCenter internal binary or text formatted information. It is not used in the Export and Import (load) Utilities. Activating this checkbox automatically updates any records in the current file with values from the loaded file when unique key values (e.g. logical.name, number, etc.) between the records are the same. The unload is executed as a foreground process, meaning that the ServiceCenter terminal session will be devoted to executing the unload and terminal control is returned after the unload has completed. The Database Manager unload form remain on-screen while the unload is processed. Upon completion, the enduser record is re-displayed along with several possible messages displayed at the bottom of the screen (unload messages are also written to the msglog file). In UNIX and Windows NT the following message is displayed in the status bar: <n> records from enduser unloaded to: <unload file name>, <HH:MM:SS> elapsed.
5-28
After a successful unload, the file is available for loading it into another system. Refer to Loading ServiceCenter Databases on page 5-58.
Unload complication messages

A successful unload of records generates the following messages when unloading to an external dataset that does not already exist: * unable to allocate * enduser file unloaded to external file: <system.filename> <nn> records from enduser unloaded to: <system.filename> HH:MM:SS elapsed A successful unload generates the following messages when unloading to preallocated external dataset: *enduser file unloaded to external file: <system.filename> <nn> records from enduser unloaded to: <system.filename> HH:MM:SS elapsed The following messages are generated when ServiceCenter cannot connect to the named external file: *enduser file CANNOT be unloaded to external file: <system.filename> *unable to allocate unable to allocate Often, a dataset that cannot be allocated lacks a certain high level qualifier required by a security facility such as Top Secret, RACF, or ACF2. Check with your internal Systems Programmer or Security Officer for the required qualifier, and try the unload again.
Unloading multiple records from one database

A user may want to copy several enduser database records from your production ServiceCenter environment into development. Accomplishing this via the QBE method involves using a QBE format to select the desired records and unloading them from production. 1. Access the enduser form. 2. Bring up a list of enduser records to be unloaded. In this example, only the records with the model field equal to 3286 are to be unloaded. a. Enter =3286 in the model field. b. Press Enter.
5-29
A record list of enduser records satisfying the query is displayed.
Figure 5-23. Unloading a list of records
3. Select List Options -> Mass Unload to begin the unload process for this list of records.
5-30
The default unload/export screen is displayed with a prompt requesting unload parameters.
Figure 5-24. Setting multiple record unload configuration
Unload parameters fall into two categories: Those which control how data is written to an external dataset (unload options). Those which control how the same data is to be read BACK into ServiceCenter via the load utility (load options). Both categories of options are set prior to the actual unload. Unload options control the immediate allocation of the external dataset and the format of the data written to the external dataset. The load options are written to the external dataset along with the unloaded record(s). These load options remain dormant until the external dataset is accessed by the Load Utility at which time they control how the unloaded data is read back into ServiceCenter. 4. To continue with this example using the default unload parameters, enter the fully-qualified dataset name to which ServiceCenter will write this single enduser record.
a. Enter <qualifier>.example2, where <qualifier> conforms to your standard naming conventions for MVS datasets. or b. Enter <path>.example2, where <path> conforms to your standard naming conventions for UNIX or Windows NT files. 5. Click Unload/export to begin the unload. The unload is executed as a foreground process, meaning that the ServiceCenter terminal session will be devoted to executing the unload and terminal control is returned after the unload has completed. The Database Manager unload form remains on-screen while the unload is processed. Upon completion, the enduser list is re-displayed along with several possible messages displayed at the bottom of your screen (unload messages are also written to the msglog file). Note: When scrolling unload messages from a list, enter a scroll setting of half or page, otherwise a scroll setting of recd causes the list itself to be scrolled, causing the unload messages to be lost. After a successful unload, the file is available for loading it into another system. Refer to the Loading ServiceCenter Databases on page 5-58.

A successful unload of records generates the following messages when unloading to an external dataset that does not already exist: * unable to allocate * enduser file unloaded to external file: <system.filename> <nn> records from enduser unloaded to: <system.filename> HH:MM:SS elapsed A successful unload generates the following messages when unloading to preallocated external dataset: *enduser file unloaded to external file: <system.filename> <nn> records from enduser unloaded to: <system.filename> HH:MM:SS elapsed The following messages are generated when ServiceCenter cannot connect to the named external file: *enduser file CANNOT be unloaded to external file: <system.filename> *unable to allocate unable to allocate Often, a dataset that cannot be allocated lacks a certain high level qualifier required by a security facility such as Top Secret, RACF, or ACF2. Check with your internal Systems Programmer or Security Officer for the required qualifier, and try the unload again.
5-32
Unloading multiple records from a single file using value-list

A user may want to copy several enduser database records from a production ServiceCenter environment into a development environment. Accomplishing this via the Value-List method involves entering the list of desired records, unloading them from production, then loading them from within the development system. The Value-List method is superior to the query method in situations where a list of desired records cannot be generated practically via a query. For example, a user may want to unload enduser records with the following logical names: a101a01 a101a03 a102a02 a105a03 a106b01 a106b02 a106b03 d100-1
The only queries capable of producing such a list (exclusive of other logical.names) are complex and awkward, whereas the Value-List method allows the user to enter the field name and the list of values for that field name to specify the list of records to export or unload. 1. Access the enduser form. 2. Without querying for records at this point, select Options > Export/ Unload. 3. Enter logical.name in the Field Name field. 4. Enter the desired logical.name values in the Field Values array. Use logical.name values that are appropriate to the database. For this example, enter the following logical name field values: a101a01 a101a02 a102a03 a105a03
5-33
Figure 5-25. Value list record selection
5. Click Unl Records. This displays the list of records which met the search criteria defined on the previous screen. 6. Verify that this list is accurate.
5-34
7. Select List Options -> Mass Unload from the menu bar, to begin the process of unloading the list of records.
Figure 5-26. Selection for multiple record unload
5-35
The unload utility screen is displayed with a prompt requesting unload parameters.
Figure 5-27. Configuring multiple record unload
Unload parameters fall into two categories: Those which control how data is written to an external dataset (unload options), and Those which control how the same data is to be read BACK into ServiceCenter via the load utility (load options).
Both categories of options are set prior to the actual unload. Unload options control the immediate allocation of the external dataset and the format of the data written to the external dataset. The load options are written to the external dataset along with the unloaded record(s). These load options remain dormant until the external dataset is accessed by the Load Utility at which time they control how the unloaded data is read back into ServiceCenter.
5-36
8. To continue with this example, using the default unload parameters, enter the fully-qualified dataset name to which ServiceCenter will write this single enduser record. Enter <qualifier>.example3, where <qualifier> conforms to your standard naming conventions for MVS datasets. or Enter <path>.example3, where <path> conforms to your standard naming conventions for UNIX or Windows NT files.
9. Click Unload/export, to begin the unload. Unload options control the immediate allocation of the external dataset and the format of the data written to the external dataset. The load options are written to the external dataset along with the unloaded record(s). These load options remain dormant until the external dataset is accessed by the Load Utility, at which time they control how the unloaded data is read back into ServiceCenter. The unload is executed as a foreground process, i.e. session is devoted to executing the unload, and terminal control is returned only after the unload has completed. The Database Manager unload format remains on-screen while the unload is processed. Upon completion, the enduser record list is re-displayed along with several possible messages displayed at the bottom of the screen (unload messages are also written to the msglog file). Note: When scrolling unload messages from a QBE list, enter a scroll setting of half or page, otherwise a scroll setting of recd will cause the QBE list itself to be scrolled, causing the unload messages to be lost. The M (fixed message) button can also be used to display messages. After a successful unload, the file is available for loading it into another system. Refer to the Loading ServiceCenter Databases on page 5-58.

A successful unload of records generates the following messages when unloading to an external dataset that does not already exist: * unable to allocate * enduser file unloaded to external file: <system.filename> <nn> records from enduser unloaded to: <system.filename> HH:MM:SS elapsed
5-37
A successful unload generates the following messages when unloading to preallocated external dataset: *enduser file unloaded to external file: <system.filename> <nn> records from enduser unloaded to: <system.filename> HH:MM:SS elapsed The following messages are generated when ServiceCenter cannot connect to the named external file: *enduser file cannot be unloaded to external file: <system.filename> *unable to allocate unable to allocate Often, a dataset that cannot be allocated lacks a certain high level qualifier required by a security facility such as Top Secret, RACF, or ACF2. Check with your internal Systems Programmer or Security Officer for the required qualifier, and try the unload again.
Unloading records from multiple databases

A user may want to copy several enduser database records and the entire tpdevice database from a production ServiceCenter environment into a development environment. Accomplishing this efficiently involves an unload of the desired enduser records followed by an unload of the tpdevice records into the same MVS, UNIX, or Windows NT file, followed by a load of the MVS, UNIX, or Windows NT file from within the development system. Records from different databases can be unloaded into the same MVS, UNIX, or Windows NT file, because destination information is included with each unload. The destination information consists of the dbdict of the unloaded database. At load time, the load function examines the unloaded dbdict for a group of records to determine where to route them. Using the example of enduser and tpdevice records mixed within one MVS, UNIX, or Windows NT file, at load time the enduser records are directed to the enduser database and the tpdevice records are directed to the tpdevice database automatically. An important consideration when unloading multiple databases into one MVS, UNIX, or Windows NT file is that at load time, the entire external file is loaded There is no option to selectively choose to load some records and not others.
Important: If the user needs to be selective about when and where records are to be loaded, the records must be unloaded into separate MVS, UNIX, or Windows NT files.
5-38
Part IUnload from the first file

1. Access the enduser form. 2. Bring up a list of enduser records to be unloaded. For this example call up all records for model number 3286. a. Enter =3286 in the model input field, and click Search. Note: Use a query that is appropriate for your database. A list of enduser records satisfying the query is displayed.
Figure 5-28. Initial record list for multiple database unload
3. Select List Options > Mass Unload, to begin the unload process for this list of records. The unload utility screen is displayed with a prompt requesting unload parameters. Unload parameters fall into two categories: Those which control how data is written to an external dataset (unload options), and Those which control how the same data is to be read BACK into ServiceCenter via the load utility (load options). Both categories of options are set prior to the actual unload.
Unload options control the immediate allocation of the external dataset and the format of the data written to the external dataset.
5-39
The load options are written to the external dataset along with the unloaded record(s). These load options remain dormant until the external dataset is accessed by the Load utility at which time they control how the unloaded data is read back into ServiceCenter. 4. Enter the fully-qualified MVS dataset name, UNIX, or Windows NT file name to which ServiceCenter will write these enduser records Enter <qualifier>.EXAMPLE4, where <qualifier> conforms to your standard naming conventions for MVS datasets, UNIX or Windows NT files.
5. De-select the Append to File checkbox, giving it a false value to be sure the records will be unloaded to an empty MVS dataset name, UNIX, or Windows NT file. 6. Click unload/export, to begin the unload.
The unload is executed as a foreground process, meaning the ServiceCenter terminal session is devoted to executing the unload, and terminal control is returned after the unload is completed. The Database Manager unload format remains on your screen while the unload is processed.
5-40
Upon completion, the enduser QBE list is re-displayed along with several possible messages displayed at the bottom of your screen (unload messages are also written to the msglog file). The M (fixed message) button can also be used to display messages. After a successful unload, the file is available for loading it into another system. Refer to the Loading ServiceCenter Databases on page 5-58.
Part IIUnload from the second file

1. Exit back to the Database Manager dialog box. 2. Enter =tpdevice in the Form field.
3. Press Enter. The tpdevice (Teleprocessing Devices) form is displayed.
5-41
4. Pass a true query by pressing Enter to return a list of all records (or use any query to retrieve the desired records.)
Figure 5-29. Unloading a second group of records
5. Select List Options > Mass Unload to begin the unload process on these tpdevice records. This unloads every record in the tpdevice file. The default unload screen is displayed with a prompt requesting unload parameters. Note: In addition to the default unload parameters, the previous external file name is retained (SC.EXAMPLE4). If this file name does not appear, re-enter it as the external file name. 6. The tpdevice records are to be unloaded to this same external dataset, so activate the Append to (Existing) File checkbox, setting its value to true. 7. Click Unload/export, to append the tpdevice records to the end of the MVS dataset, or UNIX or Windows NT file containing the enduser records.
5-42
Figure 5-30. Appending a second group of records to existing unload file
The unload is executed as a foreground process, meaning the ServiceCenter terminal session is devoted to executing the unload, and terminal control is returned after the unload is completed. The Database Manager unload format remains on your screen while the unload is processed.
5-43
Upon completion, the tpdevice QBE list is re-displayed along with several possible messages displayed at the bottom of the screen (unload messages are also written to the msglog file).
Figure 5-31. Confirmation of unload on second block of data records
After a successful unload, the file is available for loading it into another system. Refer to the Loading ServiceCenter Databases on page 5-58.
Unloading a QBE only (no data records) to Excel

A user may want to export only the list of records which meet a particular search criteria to an Excel file. This list is obtained by passing your query into the Database Manager, which returns a QBE list. ServiceCenter Database Manager uses Microsofts (MS) DDE to export the QBE into an Excel format. 1. Access the enduser form. 2. Enter the query values in the appropriate fields to search for records containing specific information. 3. Press the Enter button to pass the query. This query returns a list of records in the enduser file containing values which match the criteria.
5-44
4. Select List Options -> Export to Excel.
Figure 5-32. Unloading data records to Excel
Note: When running Microsoft Office 95 or 97, the Microsoft Excel application opens, and the data from the ServiceCenter record list appears in a table within the Excel application. 5. Save this file in Excel. 6. Return to ServiceCenter to pass additional queries or to perform other functions.
Unloading a Database Dictionary only (no data records)

A user may want to move a database file tested and created in a development ServiceCenter system into a production system. The development database may contain test records, therefore only the database dictionary (the structure of the file) should be migrated and not the records within. The user may also want to use a load to make additions to a production database dictionary file.
Important: As a precautionary measure, backup the unmodified database dictionary file (i.e., the database dictionary which will be replaced on the target ServiceCenter system) before proceeding.
5-45
Both examples involve unloading a database dictionary only. The following example demonstrates unloading the enduser database dictionary without unloading any enduser records. 1. Access the enduser form. 2. Without querying for records at this point, pull down the Options menu. 3. Select the Export/Unload option, to begin the unload process. The unload file form appears, requesting the fields values of the records you wish to unload or export. 4. Enter no values in the Field Values array. These values refer to actual values found in a specific field, as defined in records in this Database Dictionary file. Since you are not going to unload the records, but the structure of the Database Dictionary file, there is no need to specify field values.
Figure 5-33. Unloading a dbdict
5. Click Unl Dbdict.
5-46
The Unload/Export Utility screen is displayed requesting unload parameters.
Figure 5-34. Specifying external unload file
6. To continue with this example, enter the fully-qualified MVS dataset name, or UNIX or Windows NT file name to which ServiceCenter will write the enduser dbdict. Enter <qualifier>.EXAMPLE5, where <qualifier> conforms to the standard naming conventions for MVS datasets or UNIX files.
7. De-select the Append to File check box, giving it a value of false to be sure it is unloaded to an empty MVS dataset or UNIX file. 8. Click unload/export.
5-47
The unload is executed as a foreground process, meaning the ServiceCenter terminal session is devoted to executing the unload, and terminal control is returned after the unload is completed. The Database Manager unload format remains on your screen while the unload is processed. Upon completion, the blank enduser form is re-displayed with a message at the bottom of your screen stating that 0 records were unloaded. This is fine, since none should have been because you were unloading the structure instead of the data records. After a successful unload, the file is available for loading into another system. Refer to Loading ServiceCenter Databases on page 5-58.
Unloading a ServiceCenter Report Writer report

Reports created with the ServiceCenter ReportWriter Utility consist of records from at least two files: report and format with possible Format Control record(s) in the formatctrl file and possible link records in the link file. The following example demonstrates unloading the invoice.approved.acct report using the Database Manager Unloade/Export capability. Another, easier way to unload all records from these four related files is by using the ServiceCenter Unload Script Utility. See Unload Script Utility on page 8-1 for details. 1. Access the Database Manager. 2. Enter =report.prompt.rw at the Form prompt to call up the report record. 3. Press Enter. Database Manager opens displaying the Report Writer prompt. See Figure 5-36 on page 5-49. 4. Enter =invoice.approved.acct in the Report field. 5. Click Search.
Part IReport structure unload

The qualified report record with primary file designation is displayed.
5-48
1. Select Options > Export/Unload to unload the report record.
Figure 5-35. Report Writer prompt
The Unload/Export Utility screen is displayed with a prompt requesting unload parameters. 2. To continue with this example, enter the fully-qualified MVS dataset name, UNIX or Windows NT file name to which ServiceCenter will write the report record Enter <qualifier>.EXAMPLE6, where <qualifier> conforms to your standard naming conventions for MVS datasets, UNIX, or Windows NT files.
3. De-select the Append to File check box, giving it a value of false to be sure it will be unloaded to an empty MVS dataset, UNIX, or Windows NT file.
5-49
4. Click Unload/export.
Figure 5-36. Specifying unload file settings
The unload is executed as a foreground process, meaning the ServiceCenter terminal session is devoted to executing the unload, and terminal control is returned after the unload is completed. The Database Manager unload format remains on your screen while the unload is processed. Upon completion, several possible messages are displayed at the bottom of your screen (unload messages are also written to the msglog file). After a successful unload, the file is available for loading it into another system. Refer to Loading ServiceCenter Databases on page 5-58.
Part IIReport record unload

The next step of the process is to exit from the report form and add records associated with this report from the format file. 1. Return to the Database Manager prompt. 2. To unload forms associated with this report, enter =format in the Form field, and click Search.
5-50
The format form is opened in the Database Manager. The six forms referenced by this report can be unloaded via the Value-List method. 3. Do not place data in any of the fields, essentially not querying any specific records. 4. Select Options > Export/Unload from a blank format form. When the unload form appears, enter name in the Field Name field. 5. Enter the six format names as shown in Figure 5-38 in the Field Values array. 6. Click Unl records.
Figure 5-37. Listing reports to unload
A record list of the selected forms is displayed. 7. Select List Options > Mass Unload to unload the format records. The Unload/Export Utility screen is displayed requesting unload parameters (Figure 5-39). 8. Leave the Append to File checkbox activated since the format records should be appended to this same file. 9. Click Unload/export.
5-51
Figure 5-38. Appending report records to existing unload file.

A successful unload of records generates the following messages when unloading to an external dataset that does not already exist: * unable to allocate * enduser file unloaded to external file: <system.filename> <nn> records from enduser unloaded to: <system.filename> HH:MM:SS elapsed A successful unload generates the following messages when unloading to preallocated external dataset: *enduser file unloaded to external file: <system.filename> <nn> records from enduser unloaded to: <system.filename> HH:MM:SS elapsed The following messages are generated when ServiceCenter cannot connect to the named external file: *enduser file cannot be unloaded to external file: <system.filename> *unable to allocate unable to allocate
5-52
Often, a dataset that cannot be allocated lacks a certain high level qualifier required by a security facility such as Top Secret, RACF, or ACF2. Check with your internal Systems Programmer or Security Officer for the required qualifier, and try the unload again. The unload is executed as a foreground process, meaning the ServiceCenter terminal session is devoted to executing the unload, and terminal control is returned after the unload is completed. The Database Manager unload format remains on your screen while the unload is processed. Upon completion, the format record list is re-displayed along with several possible messages displayed at the bottom of your screen (unload messages are also written to the msglog file).
Part IIIFormat Control

The next step is to unload format control records associated with this report. 1. Return to the Database Manager prompt. 2. Enter =formatctrl in the Form field, and click Search. Note: The format control records referenced by this report can be unloaded via the Value-List method. 3. Without placing data in any of the fields, select Options > Export/Unload. The Unload/Export Utility descriptor screen is displayed requesting unload values (Figure 5-38). 4. Enter name in the Field Name field.
5-53
5. Enter the two format control names as shown in Figure 5-40 in the Field Values array.
Figure 5-39. Specifying Format Control records to unload
6. Click Unl records A record list of the selected format control records is displayed. 7. Select List Options > Mass Unload option to unload the formatctrl records.
5-54
The Unload/Export Utility form is displayed with a prompt requesting unload parameters.
Figure 5-40. Appending report records to existing unload file.
Note: The External File Name value is retained from the previous unload. 8. Leave the Append to File checkbox activated since the formatctrl records are to be appended to this same file. 9. Click Unload/export.
Part IVLink records

The next step is to unload link records associated with this report. Repeat the same process you used to unload the formatctrl records, but access the link file instead. The two link records you need to unload are invoice.header and invoice.detail.

A successful unload of records generates the following messages when unloading to an external dataset that does not already exist: * unable to allocate * enduser file unloaded to external file: <system.filename>
5-55
<nn> records from enduser unloaded to: <system.filename> HH:MM:SS elapsed A successful unload generates the following messages when unloading to preallocated external dataset: *enduser file unloaded to external file: <system.filename> <nn> records from enduser unloaded to: <system.filename> HH:MM:SS elapsed The following messages are generated when ServiceCenter cannot connect to the named external file: *enduser file cannot be unloaded to external file: <system.filename> *unable to allocate unable to allocate Often, a dataset that cannot be allocated lacks a certain high level qualifier required by a security facility such as Top Secret, RACF, or ACF2. Check with your internal Systems Programmer or Security Officer for the required qualifier, and try the unload again. The unload is executed as a foreground process, meaning the ServiceCenter terminal session is devoted to executing the unload, and terminal control is returned after the unload is completed. The Database Manager unload format remains on your screen while the unload is processed.
5-56
Upon completion, the format record list is re-displayed along with several possible messages displayed at the bottom of your screen (unload messages are also written to the msglog file).
Figure 5-41. Messages returned from unload of Format Control report records
The three components of the report (report, format, and format control records) now reside in the external dataset and can be loaded into your development ServiceCenter system via the Load function. Refer to Loading ServiceCenter Databases on page 5-58.
5-57
Loading ServiceCenter Databases

The Load function reads data into the current ServiceCenter system from an existing dataset or file containing data unloaded from a ServiceCenter P4 file system. The Load function will not read any external dataset that is not in ServiceCenter unload format. Note: Load function security is enabled via format control attached to the format.prompt.db form. The options chosen when executing a load of an external dataset are: Name of the external dataset. Run the load in foreground or background. View contents of load file. All other load options were defined when the file was originally unloaded and these options are included in the external dataset itself. These load options govern how the data is loaded and cannot be overridden at load time. The preceding section of this chapter describes how to unload records from a ServiceCenter database or databases into an external dataset or file. The following section describes how to load such a file, or a file created by the ServiceCenter Unload Script Utility, back into ServiceCenter.
Executing the load as a foreground process

The following example demonstrates loading the external dataset SC.EXAMPLE1 created in the section Unloading a single record from a database on page 5-22. 1. Access the Database Manager. 2. Leave all fields in the Database Manager prompt blank. 3. Select Options > Import/Load option. 4. When the new form opens, enter the fully qualified dataset or file name of the external file you wish to load, <qualifier>. EXAMPLE1. 5. If you specified a member for the unload, enter its value in the Member field. 6. Leave the Import Descriptor record field empty. This is used only for imports.
5-58
7. Choose the appropriate message activity level during the load process. Loads that include many large files can generate many messages, so you can choose whether to receive all messages, just totals, or only a single message for the entire load process. 8. To view the contents of the file(s) to be loaded, click List contents.
Figure 5-42. Selecting ServiceCenter unload file to load
The field values for each record unloaded are displayed in a table. This provided you the opportunity to scroll through the data unload to verify it has been formatted properly. 9. If an error has occurred or the incorrect data has been loaded into the file, repeat the unload process again.
Figure 5-43. Contents table of unload file data records
10. Click Back to return to the load/import screen. 11. To run the load processes, click Load fg. Note: The import button functions are described in the Import/Export Utility section of the Data Administration Guide.
The load is executed as a foreground process, meaning the ServiceCenter terminal session is devoted to executing the load, and terminal control is returned after the load is completed. The Database Manager load format remains on your screen while the load is processed. The system first attempts to connect to the external dataset and immediately generates a message if it cannot. If the dataset does not exist, the message Error occurred while loading external file: <qualifier>.EXAMPLE1 is displayed. The same message appears if the dataset exists but cannot be accessed. In an MVS environment, this is usually due to the intervention of a security facility such as Top Secret, RACF, or ACF2 which require a certain high-level qualifier on the dataset name. In a UNIX or Windows NT environment, it can mean that permissions on the directory or file do not allow access for this user. After the external file is successfully connected, the load utility proceeds with loading the contents of the external file. When it is completed, the Database Manager prompt screen is re-displayed with messages indicating the following pieces of data: number of records loaded files records were loaded into Any other load messages appear on the screen and in the msglog file, which can be seen by clicking the M button.
Load complication messages

Usually, several messages are generated by a load. In the MVS environment, the following load messages are produced when loading the dataset <qualifier>.example1: *<qualifier>.example1 file loaded. *File(s) loaded from external file:<qualifier>.example1 1 record loaded into enduser file from external file: <qualifier>.example1 In the UNIX environment, the following load messages are produced when loading the file path>.example1: *<path>.example1 file loaded. *File(s) loaded from external file:<path>.example1 1 record loaded into enduser file from external file: <path>.example1 In the Windows NT environment, the following load messages are produced when loading the file path>.example1: *<path>.example1 file loaded. *# total records processed in 00:00:00 *# records from <path>.example1 updated to enduser
5-60
*# records from <path>.example1 added to enduser *# errors detected loading to enduser from <path>.example1 *# records from <path>.example1 loaded to enduser, 00:00:00 elapsed Loading enduser file for external file: <path>.example1 Note: The on-line message facility displaying the load messages on the screen displays the most recent message first. As you scroll through the load messages on-line, they are therefore displayed in reverse chronological order.
Table 5-2. Load Messages Message <MVS.FILENAME>, <WINNT.FILENAME> or <UNIX.FILENAME> file loaded. File(s) loaded from external file: <MVS.FILENAME>, <WINNT.FILENAME> or <UNIX.FILENAME> <nn> records loaded into <database name> from external file: <MVS.FILENAME>, <WINNT.FILENAME> or <UNIX.FILENAME> Loading <database name> from external file: <MVS.FILENAME>, <WINNT.FILENAME> or <UNIX.FILENAME>. <nnn> records have been loaded so far into the <database name> file. The config record (database load/unload is missing). Description Load processing of the named dataset is complete. Load processing of all the files within the dataset or file completed. Load processing of nn records into the named ServiceCenter database from the named dataset or file completed. Load processing of the named ServiceCenter database from the named dataset or file begins. The load utility generates this message for every hundredth record it attempts to load into the named ServiceCenter database. The hardware configuration record database load/ unload.unix required for database loads and unloads has been deleted or renamed. It must be replaced. Refer to the Quick Start Guides for more information. The load utility found two or more hardware configuration records named database load/ unload.mvs. There should be only one such record. The true/false field Used for database loads/ unloads on the hardware configuration record database load/unload.mvs is set to false. It must be true. The load utility could not access the named external file because another task has exclusive control on it.
Invalid number of records found in config file.
Config record is not set up to be used for database loads.
The external file <MVS.FILENAME>, <WINNT.FILENAME> or <UNIX.FILENAME> is being written to and cannot be read at this time.
5-61
Table 5-2. Load Messages (Continued) Message Invalid end of file encountered in external file <MVS.FILENAME>, <WINNT.FILENAME> or <UNIX.FILENAME>. All null keys:file: <database name>;rec no;<nn> in external file:<MVS.FILENAME>, <WINNT.FILENAME> or <UNIX.FILENAME>. Invalid null key;file:<database name>;rec no:<nn> in external file <MVS.FILENAME>, <WINNT.FILENAME> or <UNIX.FILENAME>. Invalid duplicate key:file:<database name>;rec no:<nn> in external file <MVS.FILENAME>, <WINNT.FILENAME> or <UNIX.FILENAME>. External file <MVS.FILENAME>, <WINNT.FILENAME> or <UNIX.FILENAME> is not in Peregrine Four Unload Format. Description The load utility encountered an incomplete dataset, i.e., the unload which originally created this dataset was interrupted before completion. The load utility attempted to add record number <nn> to the named ServiceCenter database and encountered all null keys. The load utility attempted to add record number <nn> to the named ServiceCenter database and encountered an invalid null key. The load utility attempted to add record number <nn> to the named ServiceCenter database and encountered an invalid duplicate key. The named dataset is not in the proprietary format required by the load utility.
Executing the load as a background process

A background load is executed independently of the terminal session, making the terminal session available for other functions as soon as the load has been scheduled. 1. Select the Toolkit tab in the system administrators home menu. 2. Click Database Manager. The Database Manager dialog box is displayed. 3. Select Options > Import/Load. 4. Enter the fully qualified dataset or file name of the external file you wish to load, <qualifier>. EXAMPLE1 (Figure 5-45). 5. If you specified a member for the unload, enter its value in the Member field. 6. Leave the Import Descriptor field blank (for imports only).
5-62
7. Click Load bg.
Figure 5-44. Identifying ServiceCenter unload file for background load
Note: The import button functions are described in the Import/Export Utility section of the Data Administration Guide. MVS Note: The system first attempts to connect to the external dataset and immediately generates a message if it cannot. If the dataset does not exist, the message Error occurred while loading external file: <qualifier>.example1 is displayed. The same message will appear if the dataset exists but cannot be accessed, usually due to the intervention of a security facility such as Top Secret, RACF, or ACF2, which requires a certain high-level qualifier on the dataset name.
5-63
After the external file is successfully connected, the Schedule Background Load screen displays (Figure 5-46). The Expiration Date value defaults to the current date and time which may be overwritten.
Figure 5-45. Scheduling background load
8. Enter a time in the Repeat Interval field to repeat the load automatically at specified times. The example of 1:00:00 causes the load to occur at intervals of one hour, as well as at the current time (or time shown in the Expiration Date field). 9. Change the path and/or name of the file in the External Filename field if necessary. This value defaults to the entry provided on the previous screen (Figure 545). 10. Click Load BG. The Database Manager prompt screen re-displays with the message Background load schedule to run at <date/time>. Note: Load messages are written to the msglog file when the actual load is executed.
5-64
Chapter 6 Database Record Auditing

This chapter introduces Database Auditing, including how to: Access the Audit Specifications file. Access the Audit Log file. Use Audit Specifications fields. Read Audit Log Fields. Define an Audit Specification entry. Invoke Audit processing. Look up Audit Log entries.
Database Record Auditing
6-1
Understanding Auditing
Auditing allows the user to check specified fields within a file in the ServiceCenter database for any modifications, when records in that file are updated. It tracks record updates when paging (i.e. creating a unique record or page for every update) is not available, and provides an alternative to Paging. Field modifications are detected by comparing the field input values in the original version of a record to the same field values in the updated version of that record. When modifications are detected, an Audit Log entry is generated showing: The name of the modified field(s). The old and new version of the data. The date/time of the modification. The userid of the operator who modified the record.
6-2
Accessing the Audit Specifications File

The Audit Specifications file provides the instructions on how and when to perform an audit. It defines files and fields to be watched by the Audit application. There is one specification record for each ServiceCenter Database Dictionary (dbDict) file. To access the Audit Specifications file use the following procedure: 1. Select the Utilities tab from the administrators home menu. 2. Click Tools. The ServiceCenter Tools menu is displayed.
Figure 6-1. Tools menu in the system administrators home menu
3. Click Audit Specifications to bring up an audit specifications table.
6-3
Figure 6-2. Audit specifications form.
Important: The figure below shows a record that does not exit in the default system. Create it as displayed for the examples in this section. See Defining an Audit Specifications Entry on page 6-9
Note: Navigation may differ slightly between ServiceCenter versions, but Audit Specifications can be called from the command line at the main menu in any version by entering audspec, and pressing Enter.
Audit specifications table fields

Note: You can also open the auditspecs format in Database Manager using techniques described earlier in this guide.
6-4
The Format Control record associated with the auditspecs format executes a routine which validates entries in the Filename and Field Name fields. This validation routine is executed when Audit Specification records are added or updated. It prevents invalid fields or file values from being entered into the system and controls unpredictable run-time results. This routine is described in Defining an Audit Specifications Entry on page 6-9 and Field name verification on page 6-11. Filenamename of a valid ServiceCenter Database Dictionary file upon which Audit will be performed. This is a required field on the table. Unique A - Dused to parallel data records in the Audit File to data records in the source file. Under most circumstances, the field(s) specified in Unique A through D are the same field(s) that are defined as unique keys in the specified Database Dictionary file. These values need to be unique identifiers for the specific file. Unique A is the only required entry. Additional entries for Unique B through D are optional. For example, the unique key for the enduser Inventory/Configuration file is logical.name. In this case, Unique A is defined as logical.name and Unique B through D are left blank (NULL). When an Audit Log record is recorded for device a111, Filename in the Audit Log is recorded as enduser, Unique A as a111. This allows for all enduser Audit Log records to be uniquely associated with each enduser record. A new Audit Log can be generated based on data found in the previous log record for this device. It is possible for Unique A through D to be the same fields as a no nulls or a no dups key. However, this should only be done when a unique key is not available. If no nulls keys are used, it is possible that Audit Records will be related to different source records, making it difficult, if not impossible, to determine to which specific source record a particular Audit Record is related. It is not recommended to use nulls&duplicates keys to define Unique A through D, because if the field(s) in the key are NULL, then Audit records are created which do not relate to any records in the Source File. It is not a requirement that field(s) as Unique A through D be defined as key(s) in the Source File. However, you must take the necessary steps to ensure any non-key field(s) used are defined as unique identifiers, in order to avoid the potential problems outlined above. See the Database Dictionary topic for more information on keys and other aspects of files. Note: When defining Audit Specifications for the Problem and Change Management files, the only field that needs to be paralleled is number. It is not necessary to parallel the last or page fields. See the Database Dictionary topic in this book for information on identifying fields in files. Field Namedefines the name of the field to be checked for modifications. The fields specified for Auditing can be of any data type except arrayed structures or fields within arrayed structures. Any number of fields can be
Database Record Auditing 6-5
specified; however, Auditing overhead increases as the number of fields increase. It is not recommended to specify all fields within a file for Auditing. Rather, analyze the fields within the file to determine which are critical for the management of data records in the file. The following fields in the enduser file are considered critical: Logical.name serial.no. parent vtam.name vtam.parent vendor manufacturer. The following are noncritical in most cases: comments primary.contact alternate.contact feature.no description availability information. The recommended maximum number of fields to audit is 20. Performance degradation occurs when this number is exceeded. Under most circumstances, the recommended maximum will not impair the management of a file. Aliasdefines the alias of a field name that will be used in the audit log. When entries are recorded in the audit log (audit.summ.g form), the default is to record the actual field name. This is overridden by specifying an alias. For example, if the widgets file has a field named fd.ast.no, it may be more meaningful to define the alias field name fixed asset number. Note: A one-to-one correlation exists between the Field Name and Alias input fields. Due to processing considerations, these are independent arrays. Therefore, when one is scrolled, the other must also be scrolled to keep the definitions synchronized.
6-6
Accessing the Audit Log File

The Audit Log File is the repository for comparative data gathered during the audit. It displays the old and new input field data, as well as which user made the revisions and when. The log is a record of the update transaction for the specified source file. One log record is added per source record update, when one or more of the source record input fields defined in the Audit Specifications file are updated. Note: The following procedure will display a list of audit log records only if you have made modifications to enduser records after creating the audit specifications record as displayed in the previous section. Otherwise, you receive an empty log record and no list. To reach the Audit Log form use the following procedure: 1. Select the Utilities tab from the administrators home menu. 2. Click Maintenance. 3. Select the Logs menu tab. 4. Click Audit Log. If log records exist, they are displayed.
Figure 6-3. Audit log form.
6-7
Note: Specific navigation may differ slightly between ServiceCenter versions, but Audit Log can be called from the command line at the main menu in any version by entering audlog, and pressing Enter.
Audit log fields

Note: You can also open the audit.summ form in Database Manager using techniques described earlier in this guide. Filefile name with which this Audit Log record is associated. Unq A through DThe contents of the source record fields defined as Unique A through D in the Audit Specifications file. Datecreation date and time that the Audit Log entry was created. Operuserid of the operator who modified the source record, causing the Audit Log entry to be generated. Fieldfield name, as defined in the Audit Specifications file, or its Alias which has been modified. The old and new version of each Value (i.e., scalar field) or Array (i.e., arrays of simple data types) is recorded. All of these fields are defined in Format Designer as read/display only, and therefore cannot be modified by the user. These fields are scrollable and synchronized so when one is scrolled all related fields move as well.
6-8
Defining an Audit Specifications Entry

The Filename and Field Name values are validated anytime an existing record is updated or a new record added. The Audit utility safeguard system prevents records with misspelled and incorrect file names or field names from being processed. Such errors potentially could cause faulty-communication within the database. Note: The name of the file and one field name of the following example have been entered incorrectly to illustrate the error-correction process built into the Audit utility. Use the following steps when entering data into the Audit Specification file: 1. Select the Utilities tab in the system administrators home menu. 2. Click Tools. The Tools menu is displayed.
Figure 6-4. Tools menu
3. Click Audit Specifications. A blank Audit Specifications Table form is displayed.
6-9
Note: You may access the Audit Specifications Table though the Database Manager utility by entering auditspecs in the Form field of the Database Manager dialog box and clicking Search. 4. Enter information in the Filename and the Unique A through D fields as necessary to parallel the unique key in the source file with the Audit Log (refer to Audit specifications table fields on page 6-4 for more information on input fields). 5. Define those fields you wish to be audited and any aliases. 6. Click Add to retain this record and commit it to the database.
Figure 6-5. Audit specifications table
When the Filename value is invalid, the message The filename filename is not valid. Select one from the list is issued.
6-10
A QBE list is displayed, showing valid ServiceCenter Database Dictionary file names.
Figure 6-6. QBE of valid system filenames
7. Select an entry in the list (enduser for this example). 8. Press Enter. The correct file name is copied to the Filename field.
Important: The enduser file is used in this manual for demonstration purposes only. It does not exist in the shipped system. The functionality used in relation to this file however, works with other forms and files in ServiceCenter in the same way as described in this chapter.
Field name verification

Similar to the Filename values, all field names defined in the record (Unique A through D and all Field Names) are validated against the
Database Record Auditing 6-11
selected Database Dictionary file. When an invalid field name is found, the message The Field field name is invalid. Select one from the list is issued. A pop-up window is displayed showing a list of valid field names for the specified Database Dictionary. 1. Double click on an entry in the list. The selected field name is copied to the appropriate field. The message Record added to the auditspecs file is issued, which means that all fields have been validated and that the record has been saved. 2. Re-query the record before attempting to make any modifications. a. Exit the form. b. Re-open the auditspec form. c. Query for the enduser specifications record.
Maintenance of the Audit Specifications file follows normal ServiceCenter Database Manager procedures. See Chapter 3, Retrieving Records from Within a Database on page 3-1 for more information).
6-12
Invoking Audit Processing

Important: If you are invoking Auditing from Format Control or a RAD call, as a general rule, you should invoke Auditing after Validity Table processing but before the record add or update.
Change Management (CM) is the only application set up to run Auditing in the standard system. To invoke auditing in CM: 1. Open the cm3rcatphase.main form in Database Manager. 2. Enter the name of any phase in the form.
Analysis is used in this example.

3. Press Enter. 4. Set the Audit Records field value to true.
6-13
Figure 6-7. Activating history tracking option
5. Click Save.
Format Control
To invoke Auditing from Format Control: 1. Create an Audit Specifications record for a particular file. Refer to Defining an Audit Specifications Entry on page 6-9 for details. 2. Access the Format Control record associated with the form and the file for which you created the audit specifications record in step 1. a. Select the Utilities tab from the administrators home menu. b. Click Tools
6-14
c.
Click Format Control. A blank Format Control Maintenance form appears.
Figure 6-8. Main format control settings screen
Important: Ensure the Save Copy parameter checkbox on the Main Information maintenance screen is checked (set to true)
d. Enter the name of the form you wish to view (in this example enduser), or leave all fields blank, and click Search. A list of active forms appears. e. If you left all fields blank, select a specific form from the list of records. The selected form appears, displaying the Main Information screen. 3. Click Subroutines to display the Subroutines form, or select Options > Subroutine.
6-15
The subroutine panel is presented, as shown in Figure 6-9.
Figure 6-9. Setting up format control subroutine
Fields
Each field in the Subroutines form needs to be considered in terms of the final outcome you are seeking. Following is a list and description of fields in the Subroutines form: AddThis field needs to be true, since you want audit data to be written whenever a new record is added. Upd (update)This field needs to be true to allow audit data to be written whenever there is a modification to an existing record. Del (delete)This field is empty, as this would write an audit record whenever a record is deleted. Dis (display)This field is empty. BeforeThis setting on the subroutine call can be set to true or false. If it is true, and a key error is detected, then an Audit record exists, but the update never really occurs. If it is false, then you receive the Record Updated message before the Audit Recorded message. ApplicationThis field states the application that compares the fields in the old and new data records, and if necessary, adds a record to the Audit Log file.
MessageThis field provides the error message, which appears if the process cannot be completed as planned. NamesThis field states which files are handled by the subroutine. The Old (or original) version of the data record must be passed to the file parameter. The Save Copy option on the Format Control Maintenance form must be activated before this file variable is available. The New (or updated) version of the data record must be passed to the second.file parameter
ValuesValues in this field correspond to each parameter. These values state to which variables data is passed.
Trigger setup
Event triggers have been integrated into the system auditing function. A trigger can be set up to invoke the auditing application, audit.compare. Set up the audit.compare trigger as follows: 1. Open Database Manager. 2. Enter triggers in the Form field of the Database Manager prompt. 3. Click Search, or press Enter. 4. Enter the name of the new trigger, e.g., example.trigger.audit.update. Note: Each trigger performs one action; therefore, when naming the trigger, you may wish to incorporate the trigger type (when the trigger is to fire) into the name of the trigger. For example, example.trigger.audit.add could be the name of a trigger that fires whenever a record is added. 5. Enter the name of the file which will be audited in the table name field. In this case it is the enduser file. 6. Select the type of trigger, according to the number legend displayed beside the field. Use 4 in this case. 7. Enter trigger.invoke.auditor in the application field. 8. Click Add when ready to add this record to the triggers file.
6-17
Figure 6-10. Trigger record for updates to enduser file
6-18
Lookup Audit Log Entries

Run-time example
Using the definitions provided in the Format Control example in Format Control on page 6-14, Audit Processing is invoked when a record is added or updated in the enduser file. For example, 1. Add the record a111 to the enduser file using the following values:
Table 6-1. Sample field values Field logical name serial no. parent vtam parent vtam name location fixed asset no. manufacturer model type vendor a111 8888 a111-a n87e34 n87d30 carlsbac 12345 crt international 553 crt crt distributors Value
Note: The following message is displayed in the status bar: Record added to the enduser file. Audit Record successfully recorded and added. The audit process is invoked. No audit record will appear until a change is made from the current field values.
6-19
Figure 6-11. Enduser record
All fields specified in the Audit Specifications record have been recorded. All Old values are NULL or contain no data because there is no previous version of the record; therefore, no audit record is created. See Figure 6-11. Audit Log entries are created in response to any changes made to the current values in this record. These audit records are displayed in the audit.summ form, when accessed via the Format Control option created earlier in Format Control on page 6-14. 2. To complete the example, modify the record created in the previous steps by entering new values in the fields of the form that were specified as Unique A-D fields (Figure 6-12.)
Figure 6-12. Endusermodified fields
3. Click Save to commit the changes to the database. Note: The following message is displayed in the status bar: Record updated in the enduser file. Audit Record successfully recorded and added is issued when the record is saved and an Audit Log is created. 4. To view the audit log record generated by this action first deactivate the Record list option by selecting View > Record List. 5. Select Options > audit lkup. A QBE list is displayed.
Figure 6-13. Enduser - audit record QBE
6. Select the desired record from the list. Only two audit records should appear at this time; one for the original record add, and one for the update to that record. The Audit Log (audlog) record generated by the previous record update is shown in Figure 6-14.
6-21
Note: Only those fields which were modified are recorded. Both the Old and the New versions of each modified field are displayed in the audit log record. If none of the fields defined in the Audit Specifications Table are modified, an audit log entry is not generated for the Database Dictionary file.
Figure 6-14. Updated record
7. For further information regarding the modifications to the enduser file, click show detail.
6-22
The same record is re-displayed in an expanded format (audit.g), which shows more detailed information for the arrayed fields, as well as scrollable fields.
Figure 6-15. Expanded audit log record
8. Click End to return to the summary form. 9. From the summary form, click the Prev and Next buttons to review any additional audit records in the log for this enduser record. 10. Click end to return to the enduser record.
6-23
6-24
Chapter 7 File Maintenance

Resetting a Database from Database Manager
In some scenarios you may need to remove all records from a ServiceCenter database file. For example, you may want an empty production file when moving a file from development into production, or you may need to maintain the size of files which continually grow (such as syslog or msglog). Use the Reset option to remove all records from a file.
Warning! Reset removes all records in a file, and therefore caution should be used when choosing this option.
The following example demonstrates resetting the syslog file. 1. Select the Toolkit tab in the system administrators home menu. 2. Click Database Manager. The Database Manager dialog box is displayed. 3. Enter =syslog in the Form field. 4. Click Search or press Enter.
File Maintenance
7-1
A blank syslog form is displayed.
Figure 7-1. Blank system log file
5. Select Options -> Reset from the menu bar. A prompt is displayed, asking you to confirm the action and allowing you to schedule the Reset.
Schedule button
Figure 7-2. Reset prompt
6. From the prompt, you can: Click OK to reset the syslog file. Click Cancel to leave the file intact and return to the blank syslog format.
7-2
Click the Schedule button to schedule a time to run the file reset operation, either once or repeatedly at a set interval.
Note: Scheduling a reset operation is discussed in the following section.
Scheduling a database reset

If you select Schedule from the reset prompt (Figure 7-2), the schedule form is displayed (Figure 7-3).
Figure 7-3. Scheduling form for resetting a file
1. Provide a date in a DD/MM/YYYY format in the Date/Time to run field. 2. Provide a time in an HH:MM:SS format the Date/Time to run field. 3. Select a Repeat Interval option if the database needs to be reset on a regular basis. This setting is optional. The interval period starts from the time and date set in steps 1 and 2 Monthlyreset once a month. Quarterlyreset every three months. Semi-annuallyreset every six months. Annuallyreset once a year.
File Maintenance
7-3
Otherreset in the specified number of days, at the specified time. Use the ddd hh:mm:ss format, where ddd is the number of days from the initial date and time, and hh:mm:ss is the time of day at which the reset is run. For example, 26 10:00:00 schedules the reset to run at 10 a.m., 26 days from the initial reset date and time set in the Date/ Time to run field.
4. Click Schedule to confirm this reset action.
7-4
Regenerating Database Keys from Database Manager

Keys provide efficient, organized access to records in a database. They define a hierarchical tree of indexes associated with the actual data records. Key regeneration means that the existing index tree for a database is discarded and then regenerated from scratch. The regeneration process involves examining every data record in the database and adding indexes to the recreated index tree for each record.
Warning! Key regeneration is a time consuming process taking up to several hours for very large databases.
Under most circumstances, keys are regenerated from within the Database Dictionary Utility whenever keys are added or modified in the Database Dictionary record. The key regeneration function is also available from within Database Manager. If you want to regenerate the keys to the enduser database, be sure that other users are not accessing the database; the regen procedure will interrupt all activity in progress on the enduser file. 1. Select the Toolkit tab in the system administrators home menu. 2. Click Database Manager. The Database Manager dialog box is displayed. 3. Enter enduser in the Form field. 4. Click Search or press Enter. A blank enduser form is displayed. 5. Select Options > Regen to start the regen for the enduser file. A prompt is displayed, asking you to confirm the action and allowing you to schedule the Regen.
Schedule button
Figure 7-4. Regen prompt File Maintenance 7-5
6. From the prompt, either: Click OK to continue with the file/key regen. Click Cancel to leave the file intact and return to the blank enduser format. Click the Schedule button to schedule a time to run the file regen operation, either once or repeatedly at a set interval.
Note: Scheduling a regen operation is discussed in the following section.
Scheduling a database regeneration

If you select Schedule from the regen prompt (Figure 7-4), the schedule form is displayed (Figure 7-5).
Figure 7-5. Scheduling a regen time
1. Provide a date in a DD/MM/YYYY format in the Date/Time to run field. 2. Provide a time in an HH:MM:SS format in the Date/Time to run field.
7-6
3. Select a Repeat Interval option if the database needs to be regenerated on a regular basis. This setting is optional. The interval period starts from the time and date set in steps 1 and 2 Monthlyregenerate once a month. Quarterlyregenerate every three months. Semi-annuallyregenerate every six months. Annuallyregenerate once a year. Otherregenerate in the specified number of days, at the specified time. Use the ddd hh:mm:ss format, where ddd is the number of days from the initial date and time, and hh:mm:ss is the time of day at which the regen is run. For example, 26 10:00:00 sets the regen to run at 10 a.m., 26 days from the initial regeneration set in the Date/Time to run field.
4. Click Schedule, to confirm this file/key regeneration action.
File Maintenance
7-7
7-8
Chapter 8 Unload Script Utility

The unload script utility allows you to create standard ServiceCenter unload files through an enhanced user interface. Unload files created with this utility have the following features: All related records are included in a single unload file. All components of an unload file are identified in a single unload script record. An administrator can modify and repeat the unload process as needed. Unload files are backwardly compatible with earlier releases of ServiceCenter. The unload script utility is particularly useful for system upgrades. Customized features and files, such as forms, link records, or Format Control records, can be unloaded intact into the new system. Entire classes of records can be unloaded from a system and transferred to any other ServiceCenter system as a single file. You may unload the unload script record itself, thereby keeping the query list intact for further upgrades or data swapping. The script you create to tie records together for an unload can also be used to purge those records from your system. You may specify in the unload script record those formats or subformats in your system you want to protect from purging or unloading.
Unload Script Utility
8-1
Creating an Unload Script

To create an unload script: 1. Select the Toolkit tab in the system administrators home menu. 2. Click Unload Script Utility. A QBE list of existing unload script records is displayed.
Figure 8-1. QBE List of Available Unload Script Records
3. Select Options>Add/Edit Unload Scripts.
8-2
A blank unload script record form is displayed.
Figure 8-2. Blank Unload Script record
4. Complete the following fields:

Table 8-1. Unload Script Utility Fields Field Unload Script Unload? Purge? Show Unload Records Show Protected Formats Description Descriptive name of the script. Creates an unload file if checked Purges the records returned by your queries (or the data map) from your system if checked Displays the list of files and the queries you have created to unload records Displays protected forms excluded from any unload. This is a user-defined list designed to protect important forms or subformats from being purged from your system.
8-3
Table 8-1. Unload Script Utility Fields (Continued) Field Filename Query Description Name of the ServiceCenter file from which the records are to be selected Query used to select the records from the file listed in the Filename field. This query selects records for the unload/ purge based on values in a keyed field. Determines whether or not the system uses the datamap to unload related records. If this field evaluates to false, the utility unloads only those records selected by the query. If this field evaluates to true, the utility unloads related records as defined in the datamap file.
Datamap
5. Enter a descriptive name for your script in the Unload Script field. For this example, we have entered Tech Manager. 6. Select the Unload checkbox to unload the records to an external file. 7. Select the Show Unload Records radio button. 8. Select the names of all the ServiceCenter files from which you want to unload records from the drop-down list in the Filename column. a. Click in an empty field to display the drop-down list. b. Type the first letter of the file to advance the list to the proper section of the alphabet. c. Use the scroll bar to find and select the name. format menu operator pmenv smenv unload For this example, we have selected the following files:
9. Write the queries in the Query column needed to select the particular records you want to unload.
8-4
Use the following guidelines when writing a query: Know the name of the field to use in your search. You may query against any field in a file; however, it is preferable to use a keyed field. You may use any operator (# = <> ~, etc.)
For this example, we have entered the following queries:
name#"menu.tech"unloads all forms beginning with menu.tech name="TECHMANAGER"unloads a menu record called TECHMANAGER. name#"tech"unloads all operator records of users from the operator file whose login name begins with tech. name#"tech"unloads all Incident Management profile records from the pmenv file for users whose login name begins with tech. name#"tech"unloads all Service Management profile records from the smenv file for users whose login name begins with tech. name="Tech Manager"unloads the script record we just created. This action (recommended) preserves your script record and the queries you have created for use in another system.
10. Enter either true or false in the Datamap column to direct the system to use or ignore the ServiceCenter datamap. a. Place the cursor in the field. b. Type t for true or f for false. The system fills in the remainder of the word. Note: The data map establishes relationships between files that can be used to retrieve or purge related records such as links and Format Control. Check the predefined relationships for the files you have selected in the datamap file before using this feature.
8-5
Your unload script record may look like the example in Figure 8-3.
Figure 8-3. Unload Script RecordNew
11. Click Add when you are finished to add the record to the database. The following message appears in the status bar: Record added to the unload file.
Commonly scripted files

The following files and corresponding key field names are commonly used when creating unload scripts:
Table 8-2. Commonly Scripted Files and Field Names File format link formatctrl 8-6 name name name System Tailoring, Vol. 1 Field
Table 8-2. Commonly Scripted Files and Field Names File menu operator probsummary problem incidents ocmq ocml ocmo cm3r cm3t name name number number incident.id number number number number number Field
Protecting formats
If you choose to purge any data, you must be sure to protect formats that might be required elsewhere in the system. This is particularly true when enlisting the datamap file to purge forms. Subformats used by forms are deleted automatically when related forms are purged. Inspect the relationships established in the datamap file and enter the names of any such format in the Protected Formats list in your unload script record.
Examples New categories

For this example, assume your system uses three categories for tickets in Incident Management: network.hardware network.software network.performance As a result, your system would contain the following nine forms that would allow you to open, update, and close problem tickets: problem.network.hardware.open problem.network.hardware.update
8-7
problem.network.hardware.close problem.network.software.open problem.network.software.update problem.network.software.close problem.network.performance.open problem.network.performance.update problem.network.performance.close Perhaps you want to consolidate these three categories into a single category called network. For this new category, you need only the following three forms: problem.network.open problem.network.update problem.network.close To purge only the old forms using the unload script utility, query for name#problem.network and specify the three new forms for open, update, and close in the Protected Formats list.
Moving development systems into production

Your production system contains five forms whose names begin with vendor. You have modified all these forms in your development system and are ready to replace the old ones in your production system with the new vendor forms. In the process of developing the vendor forms, you created an experimental form called vendor.new.g, but you are not ready to move this form into the production system. To prevent this form from being unloaded with the others, query for name#vendor in the format file and list vendor.new.g in the Protected Formats list.
Protecting subformats
You are consolidating device types and want to purge a particular device form, such as device.Group.g, from your system. You want to use the data map for the format file to purge link and Format Control records associated with this form. Subformats are mapped to their parent forms in the datamap file and are subject to the same conditions defined in your unload script record. The device.Group.g form and many others in the device file use three important subformats called location.asset, contacts.asset and vendor.asset to link with the location, contacts, and vendor files respectively. A query for name#device.Group in the format file purges both the .w and .g forms of device.Group as well as any subformats used. To keep location.asset, contacts.asset, and vendor.asset from being purged, you must add them to the Protected Formats list in the unload script record.
8-8
Editing an Unload Script

To edit an unload script: 1. Select the Toolkit tab in the system administrators home menu. 2. Click Unload Script Utility. A QBE list of existing scripts is displayed. 3. Double-click on the script record you want to edit. The unload script record is displayed in read-only mode.
Figure 8-4. Unload Script RecordRead-Only Mode
4. Click Edit. The record is displayed in edit mode. 5. Edit the record. 6. Click Save or OK. The following message is displayed in the status bar: Record updated in the unload file.
8-9
Figure 8-5. Unload Script RecordEdit Mode
8-10
Validating an Unload Script

To validate an unload script: 1. Select the Toolkit tab in the system administrators home menu. 2. Click Unload Script Utility. A QBE list of existing scripts is displayed. 3. Double-click on the script record you want to validate. The unload script record is displayed in read-only mode (Figure 8-6). 4. Click Validate.
Figure 8-6. Unload Script RecordRead-Only Mode
If the script is valid, the following message is displayed in the status bar: Unload script is valid.
8-11
If the validity check fails, an error message providing details is displayed in the status bar. Click the message button to display the entire text in a pop-up window.
Warning! A query can be valid and not unload the desired set of records. Make sure your query defines the exact records you want to unload, particularly when using the purge feature.
8-12
Unloading records from an Unload Script

There are two methods for unloading files from an unload script: Peregrine Unload/Export Facilityaccessed from the Options menu of an unload script record in the edit mode (refer to Database Administration). ServiceCenter Unload utilitydescribed in the following section. To unload files from an unload script: 1. Select the Toolkit tab in the system administrators home menu. 2. Click Unload Script Utility. A QBE list of existing scripts is displayed. 3. Double-click on the script record you want to unload. The unload script record is displayed in read-only mode (Figure 8-6). 4. Click Proceed. A blank ServiceCenter Unload utility form is displayed. 5. Enter the name and path for your unload file (Figure 8-7). You may specify the fully qualified path to a particular directory, or none at all. If no path is defined, the system places your unload file in the Run directory of the Server (express client) or in the Run directory of the client (full client connection). It is not necessary to add a file extension.
Figure 8-7. ServiceCenter Unload Utility Form
8-13
6. Select one of the following options:

Table 8-3. Unload Utility Fields Field Append to File Description Allows you to append new data to existing unload files. If this field is checked (true), you may add records to a previously created unload file. If this field is blank (false), a new unload file with the same name will overwrite an existing unload file. Unloaded records are added using the existing Database Dictionary. Any changes to fields or keys are ignored. Database Dictionary of the files being unloaded replaces the Database Dictionary of the corresponding files in the new system. This allows you to unload updated files as well. Adds new records to the files of the new system and updates existing records with new information from records in the unload file. Adds new records to the files of the new system only. Does not replace existing records.
Use existing dbdict Use dbdict of loaded record (replace old dbdict) Add new records and update existing records Add new records only
7. Click Proceed to unload the file. You are returned to the Toolkit tab. If Active Notes is enabled, an unload confirmation message is displayed.
8-14
Purging Records from an Unload Script

You can use the unload script utility to purge (delete) selected records from your system. You have the option to unload the specified records at the same time, or simply to remove the records from your system permanently.
Warning! Purging records can result in the inadvertent loss of records because of an incorrectly worded query. To prevent this, perform an unload at the same time and check the results of the purge. If you have purged the wrong records, you can restore the data from the unload file and edit the query accordingly.
To purge records with the unload script utility: 1. Open the desired unload script record in the edit mode as described in Editing an Unload Script on page 8-9. 2. Select the Purge? checkbox. In this mode you can either display the list of unload records you have defined or view the list of protected forms.
8-15
Figure 8-8. Unload Script Record with Protected Format View
3. Enter the names of any forms you want to protect in the Protected Formats field. 4. Click Save to save your changes. 5. Click OK to return to the read-only screen. 6. Click Proceed. A prompt is displayed asking you to confirm the purge. 7. Click Yes to purge/unload the records. 8. Click No to abort the process and return to the unload script record.
8-16
Chapter 9 Introduction to the Database Dictionary

Chapters 9 through 11 cover the Database Dictionary, and are broken out in the following manner: Chapter 9, Introduction to the Database Dictionary - Provides a brief description of the follow-on chapters, gives an overview of the Database Dictionary, and describes how to access the Database Dictionary. Chapter 10, Adding and Modifying - Describes adding a new field or key to the database dictionary, modifying a field or key in the database dictionary, and deleting a field or key from the database dictionary. Chapter 11, Advanced Operations - Covers making a copy, renaming, and resetting the database dictionary. Also covered are using data pooling and searching for fields.
Introduction to the Database Dictionary
9-1
Understanding the Database Dictionary

The Database Dictionary defines ServiceCenter database files. A file is created by generating its Database Dictionary record. You can generate a Database Dictionary record using the following method: Use the Create File function in the Forms Designer application from a format containing all currently known fields. The Database Dictionary record is automatically generated using this method. All fields defined on the format are defined in the dictionary record. The first field defined on your format is defined as the unique key. The Database Dictionary record contains two arrays: (1) the fields array, which contains field names and types; and (2) the keys array, which defines the files keys and types. Each field is defined by a data type. When automatically generated from the Create File function, ServiceCenter defaults the field data type according to its field name, control settings, or window settings. For example: If the input field name has the word date in it, ServiceCenter automatically defines its type as date/time. If the control setting of a field is 32, ServiceCenter automatically defines its type as number. If the window setting of a field is greater than 0, ServiceCenter automatically defines its type as array. If the field does not have any of the above characteristics, the default type will be character. For more information on the Forms Designer application and the automatic generation of Database Dictionary files from new forms, see the Chapter 23, Introduction to Forms Designer for more information on developing forms and files in coordination.
9-2
Accessing the Database Dictionary

There are three ways you can access the Database Dictionary: Via Forms Designer. Via the Database Dictionary menu option on the Toolkit tab. Via the dbdict command on the command line.
From Forms Designer

The following screens illustrate how to access a Database Dictionary record called enduser from Forms Designer. 1. Access Forms Designer. 2. At the prompt, enter the name of any form associated with the database file you want to edit. For example, you could use enduser. Note: Prefixing the format name with an equal sign (=) displays the enduser format only, rather than a list of all formats starting with enduser. 3. Click Search. The requested form is displayed. 4. Select Options > dbDict.
9-3
The enduser Database Dictionary is displayed, as in Figure 9-1.
Figure 9-1. enduser Database Dictionary record.
5. To see more fields, use the scroll bar on the right of the field names list. 6. To see more keys, use the scroll bar on the right of the keys list. The fields within the database dictionary are defined as follows: Field Namename of the field in the Database Dictionary record. This is the name used to refer to the particular data item in queries, reports and on formats.
9-4
Typedata type of the data item. The number values refer to the data types as follows:
Table 9-1. Data Types Data Type number character date/time logical record array structure expression 1 2 3 4 6 8 9 11 Value
Indexfields location within its parent structure. For example, in the Database Dictionary data displayed in Table 9-1, the field model is the 10th field in the descriptor structure. Levelnumber of structures/arrays that have to be entered to reach this field. In the Database Dictionary data in Table 9-1, the second local.software field has a level of 2 because its parent is an array called local.software and the arrays parent is the descriptor structure. Keyskeys are indexes into the database dictionary. They will be explained in detail later in this chapter. 7. Click OK twice to exit from the Database Dictionary file and return to the Forms Designer prompt. 8. Click Back to return to the Main Menu. Depending on the version of ServiceCenter you are using you may have to click on this key more than once.
Menu and command access

1. Click Database Dictionary on the Toolkit tab of the home menu. You can also enter dbdict on any menu command line and press Enter.
9-5
2. At the File Name prompt, enter the name of any format associated with the database file you want to access.
Figure 9-2. Database Dictionary file name prompt
3. Click Search. Note: Prefixing the file name with an = will display the enduser Database Dictionary record only, rather than a QBE list of all Database Dictionary records starting with enduser. The enduser Database Dictionary record is displayed (Figure 9-1). 4. To see more fields, use the scroll bar to the right of the field names list. 5. To see more keys, use the scroll bar to the right of the keys list.
9-6
Chapter 10 Adding and Modifying
Important: Menu items and messages may appear differently than shown, depending on your version of ServiceCenter.
Adding a New Field

You can add fields to an existing Database Dictionary record with or without records in the file. Existing records in the file will not contain any data in the newly added fields unless each individual record is updated with data or a Mass Update is performed. Refer to the Database Manager section of the System Tailoring Guide for more information. Note: The same field name cannot appear more than once in the Database Dictionary (except for arrays and arrayed structures, which produce different field levels within the file). When you access an existing Database Dictionary, the cursor is automatically positioned on the word descriptor. The descriptor field is referred to as the high level file structure. This field is displayed in all database dictionaries. The cursor must be on a structure when adding fields. If you want to add a field within a structure other than the descriptor structure, place the cursor on the field defined as the structure before executing the add field function. Refer to Fields within structures on page 10-11 for more information.
Forming field names

Follow these rules when forming field names. Valid characters include uppercase and lowercase letters of the alphabet, numeric characters 0 through 9, and the period character.
Adding and Modifying 10-1
Field names must begin with a letter of the alphabet. Spaces and all other special characters are not permitted. Do not use ServiceCenter reserved words (uppercase or lowercase):
AND BEGIN DO ELSE END FALSE FOR
IF IN
ISIN LIKE MONTH NAME
NULL OR STEP THEN TRUE WHILE UNKNOWN
NOT
Scalar fields
A scalar field is a simple data element comprised of a single occurrence of data (as opposed to an array). The following steps demonstrate how to add a scalar field to the Database Dictionary record. In this example, we are adding a logical (true/false) field to the device file that determines whether or not a given user device resides on a local area network (lan). 1. Open the Database Dictionary record for the device file using either: The Database Dictionary utility. or The Forms Designer. See Introduction to Forms Designer on page 23-1 for questions about the Forms Designer.
10-2
Figure 10-1. Example Database Dictionary recorddevice
2. Once the file is open, place the cursor in the descriptor structure 3. Click New. The field editing window appears. 4. Enter lan in the Name field. 5. Enter logical in the Type field or select logical from the drop-down list of valid data types.
Adding and Modifying
10-3
6. Click the Add button to add this field to the device Database Dictionary record. The field lan now appears at the bottom of the list of fields in the device Database Dictionary record. 7. Use the scroll bar to the right of the fields to locate the new field at the bottom of the fields list. Note: All fields added to the Database Dictionary record (if entered in uppercase) will be converted to lowercase to be consistent with fields already defined in dictionaries and on formats. 8. You can now re-edit your Database Dictionary record, update it, or cancel without updating. Note: You must update your Database Dictionary record when adding a new field, or the Database Dictionary record will remain the same. You must also add new field(s) to the appropriate format(s) via Format Manager. See Introduction to Forms Designer on page 23-1 for more information on coordinating files and forms. 9. Click OK when you have finished adding fields to the Database Dictionary record to close and automatically update the file. This returns the message Record updated in the dbdict file.
Valid field types

Numberallows you to input only numeric data in the field. Characterallows you to input any available characters in the field (numbers, letters, special characters). Date/Timerequires field to contain the following formatted data: MM/DD/ YY HH:MM:SS or MM/DD/YYYY HH:MM:SS for years of 2000 or DD HH:MM:SS for time intervals.
10-4
You can enter a 2-digit number for the year field for dates between 1950 and 2049. For dates outside this range, you must enter a 4-digit year. (for example, 69 would be treated by the system as 1969) The SS is assumed to be :00 if left blank. HH:MM:SS is optional if the time is 00:00:00. The system will default HH:MM:SS to 00:00:00 Logicalcontains one of the following logical values: true, false, NULL or unknown. ServiceCenter accepts input of yes or no and converts it to true or false respectively. Labelused only in RAD applications. Recordused only in RAD applications. Arraycompound data element that contains one or more elements of a single data type. Structurecompound data element that contains several sub-fields, each of which may have a different data type. Expressionused only in RAD applications.
Arrays
An array is used to track multiple occurrences of a given field. The values in the field are all the same field type. For example, maybe you want to track all of the components for a personal computer (PC) in the enduser file. To accomplish this, you can create an array field, further defined as a character type, rather than creating multiple scalar fields. The following screens illustrate how to add a field to the enduser file to track
10-5
the various components comprising a PC workstation.
Figure 10-2. Enduser Database Dictionary record
1. Place the cursor on the descriptor structure and click New. 2. Enter pc.components in the Name field of the pop-up window. Note: When specifying field names, no blanks are allowed between words. Always use a period as a delimiter. 3. Enter array in the Type field or select it from the drop-down menu. 4. Click Add. Notice the message Enter data type of arrays element at the bottom of your screen. A new window also appears, which looks similar to the previous. This window is requesting a data type for the array element you have created.
10-6
Notice, pc.components is already displayed in the Name field and the Type field is blank. When adding an array field, you also need to specify the type of array (e.g. character, number, date/time, etc.). 5. Enter character in the Type field, or select character from the drop-down list of valid data types. 6. Click Add to add the new array element.
7. Use the scroll bar to locate the new array and element at the bottom of the fields list. 8. There are two entries in the record for the field pc.components (Figure 10-3). The first entry defines the field as an array. The second entry defines the data type of the array. Both entries are listed as pc.components (using the same field name for both entries is the system default, however, you can override this if you choose). The two entries are added to the bottom of the list of fields in the enduser Database Dictionary record. The second entry is also indented from the first entry (this occurs only if the number of fields specified in the Database Dictionary record is less than 50). 9. You can now re-edit your Database Dictionary record, update it, or cancel without updating. Note: You must update your Database Dictionary record when adding a new field, or the Database Dictionary record will remain the same. You must also add new field(s) to the appropriate format(s) via Format Manager. Refer to Forms Designer section of the System Tailoring Guide for information on coordinating record changes.
10-7
10. Click OK once you are finished adding fields to the Database Dictionary record, to close and automatically update the file. This returns the message Record updated in the dbdict file.
Figure 10-3. New array fields added to enduser record
10-8
Structures
Structures are used in conjunction with subformats. Use structures when you have a common group of fields that you want displayed on multiple formats. For example, Incident Management has three structures defined in the problem Database Dictionary record, the header, middle, and action structures. The fields defined in the header and action structures are set up to be used in every problem format, regardless of the category. Rather than painting each category format with the same input fields, specific formats are created and called in as a subformat on every category screen. The fields defined on a given subformat may be of different type definitions. Note: On the primary format, (in the above example, the category format) the input field defined as a structure is associated with the subformat containing some or all of the fields defined within that structure. Fields defined on the given subformat must be defined within the associated structure, but not all fields defined within the associated structure need to be contained on the given subformat. Refer to the Forms Designer section of the System Tailoring Guide more information. Lets assume you created a file called employee with many formats attached to the file (many different views depending on the user profile). Lets also assume that a common group of fields will be displayed on all the formats. To avoid redundant typing of the same fields on all formats, you can define a structure to your Database Dictionary record and create a separate format to contain this common group of fields. Refer to the Forms Designer section of the System Tailoring Guide for more information on subformats. The following screens illustrate how to add a structure that contains the fields for basic employee information. The fields are name, telephone number, and address. These fields will appear on all formats or views of the employee file. Salary, hire.date, review.date, rehire, termination.date, position, and department will appear only on certain formats.
10-9
Figure 10-4. Sample Database Dictionary record - employee (does not exist on default system)
1. Place the cursor on the descriptor structure. 2. Click New. 3. Enter basic.employee.info in the Name field in the pop-up window. 4. Enter structure in the Type field, or select structure from the drop-down list. 5. Click Add. 6. You can now add fields within the structure you just created (see Fields within structures on page 10-11). 7. Click OK once more to save your edits and end, or click Cancel to quit end without recording edits.
10-10
8. Reopen the record from the prompt now to re-edit your Database Dictionary record or update it.
Figure 10-5. Database Dictionary record with new structure
Note: You must update your Database Dictionary record when adding a new field, or the Database Dictionary record will remain the same. Refer to the Forms Designer section of the System Tailoring Guide for details on adding new fields to ServiceCenter forms. 9. Click OK once you are finished adding fields to the Database Dictionary record, to close and automatically update the file. This returns the message Record updated in the dbdict file.
Fields within structures

As mentioned above, it is important to define fields within structures when these fields exist on a format(s) associated with the input field structure name. To define fields within structures, your cursor (focus) must be on the structure name in the Database Dictionary record. If fields do not need to be defined within a given structure in a Database Dictionary record, the cursor should be positioned on the descriptor structure when adding the fields. The following screens illustrate adding fields to the basic.employee.info structure created in the previous section. 1. Position the cursor on the structure basic.employee.info. 2. Press the New button. Notice basic.employee.info is written in the Structure field. 3. Enter name in the Name field of the pop-up window. 4. Enter character in the Type field, or select character it from the dropdown list of valid data types.
5. Click Add to add the new field in this structure.
Figure 10-6. Adding fields to a new structure
The name field is added to the bottom of the list of fields under the basic.employee.info structure. 6. Place the cursor on the basic.employee.info structure. 7. Click New. 8. Enter telephone in the Name field in the pop-up window. 9. Enter character in the Type field or select character from the drop-down list of valid data types. 10. Click Add to add the new field. The telephone field is added to the bottom of the list of fields under the basic.employee.info structure. 11. Place the cursor on the basic.employee.info structure and click New. 12. Enter address in the Name field of the pop-up window. 13. Enter character in the Type field or select character from the drop-down list of valid data types.
10-12
14. Click Add to confirm the new field. The address field is added to the bottom of the list of fields under the basic.employee.info structure (Figure 10-7). 15. Click OK once more to save your edits and end, or click Cancel to quit end without recording edits.
Figure 10-7. New fields added to new structure
16. Reopen the record from the prompt now to re-edit your Database Dictionary record or update it. Note: You must update your Database Dictionary record when adding a new field, or the Database Dictionary record will remain the same. You must also add new field(s) to the appropriate format(s) via Format Manager. Refer to the Forms Designer section of the System Tailoring Guide for more information. 17. Click OK once you are finished adding fields to the Database Dictionary record, to close and automatically update the file. This returns the message Record updated in the dbdict file.
10-13
Note: When creating categories in Incident Management, define any additional fields in the newly created categories within the middle structure in the problem Database Dictionary record.
Arrayed structures
An arrayed structure is comprised of more than one field whose field type definitions may or may not be the same. You may want to define an arrayed structure to your Database Dictionary record so that on a given form (format) attached to a file, you have the ability to scroll more than one field at a time. In other words, when the cursor is on a field to scroll information, associated information contained in one or more other fields will scroll as well.
Warning! You cannot use the SQL Query method against fields contained within an arrayed structure.
For example, you might want to track contact names and phone numbers in one of your inventory files. When you are scrolling the array of contact names, you also want the array of associated telephone numbers to scroll. Another good example of an arrayed structure is the graph of unavailability. This structure is defined in the standard inventory files distributed with the Inventory/Configuration application. If you wish to create your own inventory files and track availability, you need to add the following availability fields to the inventory file(s):
Table 10-1. Database Dictionary availability fields and types Database Dictionary Field Name number.of.problems explicit.unavailability implicit.unavailability perceived.unavailability start.of.operating.hours end.of.operating.hours graph.of.unavailability graph.of.unavailability date graph number date/time date/time date/time date/time date/time array structure date/time character Field Type
10-14
The field names need to be spelled exactly as they are shown in the above table and defined with the specified field type. Lets assume you have a devicepc file, and would like each record within this file to contain statistical information on availability. The following screens layout the steps for adding the availability fields which pertain to the devicepc file. Note: These graph fields also need to be added to the inventory format(s). Refer to the Forms Designer section of the System Tailoring Guide. 1. Place the cursor on the descriptor field. 2. Click New. 3. Enter graph.of.unavailability in the Name field of the pop-up window. 4. Enter array in the Type field. 5. Click Add.
Figure 10-8. Adding structured array field
The message Enter data type of arrays element appears in the bottom of the screen and the pop-up window refreshes.
10-15
Figure 10-9. New structured array field
The Name field still displays graph.of.unavailability, but the Type field is blank. In order to create an arrayed structure, you must define the type of array as a structure.(e.g. character, number, date/time, structure). 6. Enter structure in the Type field or select structure from the drop-down list. 7. Click Add. There are two entries in the Database Dictionary record for the field graph.of.unavailability. The first entry defines the field as an array. The second entry defines the data type of the array. Both entries are listed as graph.of.unavailability (using the same field name for both entries is the system default; however, you can override this if you choose). The two entries are added to the bottom of the list of fields in the devicepc Database Dictionary record. Note: The second entry is indented in the above example. This occurs only if the number of fields specified in the record is less than 50. 8. Tab to the second occurrence of the graph.of.unavailability field (which is the structure type).
Important: For any field to be part of a structure, the cursor must be positioned on that structure field name before clicking New for the new field to be associated with it.
9. Click New.
10-16
Notice the Structure field contains the value graph.of.unavailability which is the current structure to which you are adding fields. 10. Enter date in the Name field of the pop-up window. 11. Enter date/time in the Type field. 12. Click Add.
Notice the date field is displayed under the structure field graph.of.unavailability. 13. Select the second occurrence of the graph.of.unavailability field (which is the structure type).
Important: For any fields to be part of a structure, the cursor must be positioned on that structure field name before clicking New.
14. Click New. Notice the Structure field contains the value graph.of.unavailability which is the current structure to which you are adding fields. 15. Enter graph in the Name field of the pop-up window. 16. Enter character in the Type field.
10-17
Figure 10-10. Fields added to structure within array
17. Click Add. Note: The graph field is added as the last field under the structure field graph.of.unavailability, and the message graph field added to the pcdevices file is issued. In this case, the graph field is behind the window at the bottom of the screen. You have now added all of the required fields comprising the graph.of.unavailability structure. From here you can re-edit your Database Dictionary record, update it, or cancel without updating. Note: You must update your Database Dictionary record when adding a new field, or the Database Dictionary record will remain the same. You must also add new field(s) to the appropriate format(s) via Format Manager. Refer to the Forms Designer Guide for more information. 18. Click OK once you are finished adding fields to the Database Dictionary record, to close and automatically update the file. This returns the message Record updated in the dbdict file. 19. Press Back to end this session with the Database Dictionary and return to the main menu.
10-18
Alias Fields
An alias field is a field that has a different name but the same index, level and type as an existing field. Alias fields can be used to streamline file maintenance, to force fully keyed queries (as in the Incident Management and Service Management modules), and to facilitate virtual joining. If regular Purge/Archives are performed on files with different field names for the search criteria (e.g., close.time in the problem and probsummary files, msg.time in the msglog file, and evtime in the eventin file), you can build an alias in each file called archive.time and then perform all archive activity based on archive.time without regard to the file name. In Service Management and Incident Management, alias keys are used to ensure that a fully keyed query is performed each time a QBE argument is entered. Refer to the Incident Management Tailoring Guide for more information. In cases where a field must be defined as a normal link as well as a virtual join, but the target file and/or field is different, an alias can be defined for the source field. For example, review the devicepc Database Dictionary record and the device.pc format and link records. In this example, the vj.logical.name field is the alias of the logical.name field.
Alias fields
Shared Level Shared Index Reference Number
Figure 10-11. Alias fields used in inventory Database Dictionary files
10-19
Adding an alias field

The steps detailed below describe using the Arrayed Structure Maintenance Utility (as options) to maintain alias fields in the Database Dictionary. In this example, a new alias for the flag field called network.name.flag is added to the probsummary file.
Warning! Do not attempt to use this feature to maintain non-alias fields; use the standard Database Dictionary utility described in previous pages of this chapter.
1. Select the Toolkit tab in the system administrators home menu. 2. Click Database Manager. 3. Enter =dbdict in the Form field of the Database Manager dialog box. 4. Press Enter. A blank dbdict record form is displayed. Note: You must have SysAdmin capabilities to access Database Dictionary from the Database Manager. 5. Enter probsummary at the Name field prompt.
10-20
Figure 10-12. Search form for dbdict records in Database Manager
6. Click Search.
10-21
The probsummary record is displayed.
Figure 10-13. System file record (probsummary) displayed in Database Manager
7. Scroll through the probsummary record using the scroll bars to the right of each column. These are the fields and keys of the probsummary database dictionary record displayed in an editable format. 8. Pull down the Options menu. 9. Select as options. The as options function manipulates arrays of structures, allowing insert, delete, copy and move.
10-22
The screen is refreshed in write-protected mode disallowing input.
Figure 10-14. flag field of probsummary file record
10. Scroll the fields array until the flag field appears on the screen. 11. Position your cursor on the flag field. 12. Select copy (F9). The screen is refreshed in unprotected mode with new option buttons. 13. Position your cursor on the first alias key - in this example there are none, but we will insert the new alias field immediately following the flag field, so select the downtime.end 14. Select insert.
10-23
This action inserts a copy of flag under the original, with the same type, index and level. The record will be protected against data entry.
Figure 10-15. Duplicate/alias flag field
15. Select End to exit. The screen will be unprotected, allowing data entry. 16. Scroll to the second flag field, and change its value to network.name.flag.
Figure 10-16. Modifying alias flag field
17. Click Save (F2) to confirm the change.
Warning! Do not select Exit. To do so will discard your changes and return to the empty prompt screen
10-24
The Database Dictionary record is re-displayed and the original options are available.
Figure 10-17. probsummary file record with alias fields
18. After the record has been updated, exit using OK. Alias fields should always be defined immediately following their twin, so that the index numbers in the Database Dictionary record are sequential and all duplicate indices are adjacent.
10-25
Adding a Key
A key is an identifying field in a file, used when queries are processed so all fields in a record do not need to be searched for set criteria. A field(s) in a key must be defined as a field(s) in the Database Dictionary record. When a Database Dictionary file is created through Forms Designer, ServiceCenter automatically uses the first field defined on the associated format to create a unique key. You need to manually modify the Database Dictionary record to add the necessary keys to support on-line and reporting queries, as well as sort sequences. Many other default system files, set up in the base system, may need to be changed, based on your individual search and reporting requirements. This section details the manual addition and manipulation of Database Dictionary record/file keys.
Important: If records already exist in the file when you add a key, updating the Database Dictionary record will cause ServiceCenter to automatically perform a regen.
Note: If you add keys to a file that contains records, be careful when defining key types. For example, you should not define a new key as no nulls (no blank values) if records exist in the file that contain no data in the particular field(s) comprising the key. In this case, each record not containing a value in the key field would require an update, populating the field with data. The updates must be performed prior to adding the no nulls key in order to satisfy the new key definition.
Adding a key as the first key

The following operations require that you be in the Database Dictionary application. Enter the application via the Toolkit tab on the main menu. The following example illustrate how to add the customer.no field as a no nulls key to the enduser Database Dictionary record.
Important: customer.no must be defined as a field in the enduser Database Dictionary record.
10-26
Figure 10-18. Adding a key to the enduser Database Dictionary record
1. Place the cursor on the key type of the first key, unique in this example. 2. Click New. 3. In the new key window, select a valid key in the Type field by either typing in the value or selecting it from the drop-down list under the arrow button. Use no nulls for this example.(Peregrine recommends using no nulls or unique as the first key, always.) The following are valid key types: Nulls & Duplicatesallows nulls and duplicates in the field(s) comprising the key. No Nullsallows duplicates but no nulls (i.e., must contain data in at least one of the fields in the key). No Duplicatesallows nulls but no duplicates (i.e., data must be unique, but field may be left blank).
10-27
Uniquemust contain unique data and cannot be left blank. 4. Place the cursor in the blank field names array. 5. Type customer.no in the field names array. 6. Click Add to add this key to the enduser Database Dictionary record. The key customer.no now appears as the first key in the list of keys in the enduser Database Dictionary record. All other keys are moved down the screen. You can scroll the keys array to view the remainder of keys in the list.
Figure 10-19. New key added as first key
7. Press OK once you are finished adding keys to the Database Dictionary record, to close and automatically update the file. This returns the message Record updated in the dbdict file. If records already existed in the file when you added a key, updating the Database Dictionary record will prompt you to confirm a regeneration of the file records. 8. You can either click OK (regen file) to continue with the regen, click Cancel (F3) to abort the regen and restore the Database Dictionary record to the version prior to the latest changes, or schedule a time for the file regeneration, using Schedule (clock button). 9. To remove the key, select it, and click Edit. The edit window appears. You may ignore this. 10. Click Delete on the main record format. A prompt is displayed asking you to confirm the deletion.
11. Click Yes to continue or No to abort the deletion. The next viable key is displayed 12. Click OK if not modifying this key. You are returned to the Database Dictionary record minus the key. 13. Click OK to save the record. 14. The Regen warning screen is displayed, asking you to confirm the action.
Inserting a key between other keys

The following screens illustrate how to insert the key customer.no between the keys logical.name and serial.no. in the enduser file. Note: This is an example only, since we have already added customer.no to the Database Dictionary record in the last exercise. If you would like to perform this exercise, you should delete the customer.no key from the enduser Database Dictionary record before proceeding.
10-29
Figure 10-20. Inserting a key to the enduser Database Dictionary record
1. Click on the key type of the second key, nulls&duplicates in this example, above the serial.no key. 2. Click New. 3. In the new key window, select a valid key in the Type field by either typing in the value or selecting it from the drop down menu under the arrow button. Use no nulls for this example. 4. Enter customer.no in the field names array. 5. Click Add to add this key to the enduser Database Dictionary record.
10-30
The key customer.no now appears after the first key, in the second place in the list, and the serial.no. key has moved down the list of keys in the enduser Database Dictionary record. All other keys are moved down the screen. You can scroll the keys array to view the other keys in the list.
Figure 10-21. New key inserted between existing keys
6. You can now re-edit your Database Dictionary record, update it, or cancel without updating. Note: You must update your Database Dictionary record when adding a new key, or the Database Dictionary record will remain the same. Refer to Chapter 1. 7. Press OK once you are finished adding keys to the Database Dictionary record, to close and automatically update the file. This returns the message Record updated in the dbdict file. 8. You can either click OK (regen file) to continue with the regen, click Cancel (F3) to abort the regen and restore the Database Dictionary record to the version prior to the latest changes, or schedule a time for the file regeneration, using Schedule (clock button). 9. To remove the key, select it, and click Edit. 10. The edit window appears, but ignore the window, and instead click Delete on the main record format. 11. The next viable key is displayed, if not modifying this key click OK.
10-31
You are returned to the Database Dictionary record minus the key. 12. Click OK to save the record.
Adding keys to bottom of the key list

The following screens illustrate how to add a concatenated key comprised of the fields customer.no and location to the bottom of the key list. 1. Scroll down the keys until you reach the bottom of the list. The last key in the enduser Database Dictionary record is type. This is a single key because it is comprised of only one field. In the case of a concatenated key (regardless of how many fields comprise the key) only two fields will display in the key list. To view all of the fields comprising a concatenated key, you must use the scroll arrow buttons to the right of the array or edit the key. Refer to Modifying a Key on page 10-42 for more information. Note: The blank header represents the beginning of the next key. The number of lines displayed per key depends on the number of fields concatenated in that key. Example: A key defined with the fields model and location would be displayed as:
2. Position the cursor on the blank header field located below the key type.
10-32
Figure 10-22. Inserting a key at the end of the enduser Database Dictionary record
3. Click New to display the key definition window. 4. Enter nulls&duplicates in the Type field, or select nulls&duplicates from the drop-down list. 5. Press the Tab key to move to the fields array or place the cursor in the first field of the fields array. 6. Enter customer.no in the first field of the array. 7. Enter location in the second field of the fields array.
10-33
8. Click Add button to commit this new key to the database dictionary file. The message Key added to the enduser file is displayed at the bottom of your screen. The concatenated key comprised of customer.no and location now appears in the bottom of the list of keys in the enduser Database Dictionary record.
Figure 10-23. Concatenated key added to end of the enduser record
By placing the cursor in the appropriate position in the keys section of the Database Dictionary record, you can now press New to add additional keys to the Database Dictionary record without closing the window. 9. You can now re-edit your Database Dictionary record, update it, or cancel without updating. Note: You must update your Database Dictionary record when adding a new key, or the Database Dictionary record will remain the same. 10. Press OK once you are finished adding keys to the Database Dictionary record, to close and automatically update the file. This returns the message Record updated in the dbdict file.
10-34
11. You can either click OK (regen file) to continue with the regen, click Cancel (F3) to abort the regen and restore the Database Dictionary record to the version prior to the latest changes, or schedule a time for the file regeneration, using Schedule (clock button). 12. To remove the key, select it, and click Edit. 13. The edit window appears, but ignore the window, and instead click Delete on the main record format. 14. The next viable key is displayed, if not modifying this key click OK. You are returned to the Database Dictionary record minus the key. 15. Click OK to save the record.
10-35
Modifying a Field
There may be some instances when you want to modify field names or field types in a Database Dictionary record. When you modify a field name, you must change the associated input field on any forms (formats) associated with the file. Modifying a field name does not affect existing records in the file. If you wish to modify a field type, certain considerations must be taken into account prior to any modifications: Under no circumstances should a scalar field be changed to an array or structure, or vice versa, regardless of whether or not data exists in the file. If no data exists in the file and you need to change a scalar field to an array or structure, or vice versa, simply delete the original field and add a new field defining the appropriate data type. Refer to How to Add a New Field and How to Delete a Field in this chapter. If data exists in the file and you need to change a scalar field to an array or structure (or vice versa) you must rename the original field (e.g., old.address) and add a new field (e.g., address) with the appropriate data type defined. You must then perform a Mass Update to move the contents of the original field (old.address) to the newly defined field (address). Refer to the Database Manager section of the System Tailoring Guide for additional information in the update procedure.
Modifying field types: character (scalar) <-> array

The following screens illustrate how to change a field with existing data, called address, from a character type scalar field to an array. Lets assume you created a new file called vendorview from the format vendor. 1. Select the address field name. Only one entry for address should appear, as it is currently a scalar field. 2. Click Edit. 3. Enter old.address in the Name field of the pop-up window. 4. Leave the Type field value as character (Figure 10-24). 5. Click OK to close the window and commit the change to the file.
10-36
Figure 10-24. Modifying an existing field name
Notice the address field name is now old.address in the Field Name array.
Figure 10-25. Renamed field Adding and Modifying 10-37
6. Select the descriptor structure, and click New. 7. Enter address in the Name field of the pop-up window. 8. Enter array in the Type field. 9. Click Add to commit the new array to the file. When adding an array field, you also need to specify the type of array (e.g., character, number, date/time, etc.). The system prompts you for this information now.
A new field.window appears with address displayed in the Name field and the Type field blank. The message Enter data type of arrays element also appears at the bottom of the format window. 10. Select the Type field and enter character. 11. Click Add. Note: Notice two entries for address now exist in the Database Dictionary record since it has been defined as a character array. 12. Click OK to close the window and save the changes. 13. Click OK to end this session with the vendorview file.
Figure 10-26. Added array fields
10-38
Note: This is not the end of the process, but because data exists in the file, you need to move the contents of the field now called old.address to the field called address. To accomplish this, you should perform a Mass Update in Database Manager on all records in the file that have data in the old.address field. Refer to the Database Manager section of the System Tailoring Guide for additional information in the Mass Update procedure. Once the data has been moved, it is recommended that you also remove the old.address field from the Database Dictionary record.
Mass Update
The Mass Update instruction string to move the data from the field called old.address to the first element in the newly created array called address is:
1 in address in $file = old.address in $file
Changing data types: character <-> number

You may want to change the type of a scalar field (e.g., from a character field to a number field). If no data exists in the file, you can edit the field and change the field type quickly without any other modification required. If data exists in the file, you must first change the type of the field in the Database Dictionary record, and then convert the existing data in the modified field to be consistent with the new field type. This must be done for all records in the file that contain data in the modified field. Database Manager section of the System Tailoring Guide for additional information on field and data updates. The following example illustrate how to change the field called zip in the vendorview file from a character type field to a number type field. Lets assume that data exists in the file. 1. Select the zip field name. 2. Click Edit.
10-39
The field editing window is displayed.
Figure 10-27. Modifying an existing field type
3. Enter number in the Type field. This replaces character with number in the Type field.
10-40
4. Click OK to close the window and commit the change to the file.
Figure 10-28. Existing field with modified data type
5. Click OK to update your Database Dictionary record. The message Record updated in the dbdict file is displayed to confirm the update. Note: This may not be the end of the process. If records exist in the file, you need to perform a Mass Update to change the field type of the zip field from character to number (the type of the field, e.g., character, number, date/time, etc., is stored in the data record with each associated value). All records containing a value in the field zip need to be updated to reflect the new field type. Refer to the Database Manager section of the System Tailoring Guide for additional information in the Mass Update procedure.
Mass Update
The syntax used would be:
zip in $file=nullsub{val(zip in $file,1)zip in $file}

Note: If some of the records in the file contain data in the modified field that invalidates the new field type, (in the above example, records that have a character in the zip field that is now defined as a number field), the data will not be converted and a cannot evaluate message is generated for each record failing the conversion. Those records that do not fail the conversion will be updated.
Modifying a Key
As new users are added to ServiceCenter and additional requirements are specified, you may find the need to modify keys in your database dictionary records in order to optimize performance. Refer to the ServiceCenter Performance and Tuning Guide available through Peregrine Systems Professional Services for information on key optimization. Note: As with adding new keys, if records already exist in the file when you modify a key, ServiceCenter automatically performs a regeneration of file data when you update the Database Dictionary record. A modification to a key may be a change in the field(s) comprising the key or a change in the key type definition.
Important: When modify keys in a file that contains records, be careful when defining key types. For example, do not change a key from a nulls & duplicates type to no nulls if the field(s) comprising the key are all null (contain no value). In this case, each record that did not contain a value in the field(s) comprising the key would require an update, putting data in the field before the key could be changed to no nulls.
Modifying keys: nulls & duplicates <-> unique

The following example illustrate how to change the key type of serial.no. in the enduser file from nulls & duplicates to unique. If data exists in the file, you must ensure that a unique value exists in the serial.no. field for every record in the file. If this condition is not met, you will have to update each record individually or perform a Mass Update. 1. Position the cursor on the key type nulls&duplicates above the key field serial.no. 2. Click Edit. 3. Enter unique in the Type field, or select unique from the drop-down list (Figure 10-29).
10-42
Figure 10-29. Modifying an existing key type
4. Click OK to close the window and commit the changes to the file. 5. You can now re-edit your Database Dictionary record, update it, or cancel without updating. 6. Click OK to close and automatically update the file. This returns the message Record updated in the dbdict file.
Figure 10-30. Existing key with modifying type value
10-43
7. If records already existed in the file when you modified a key, updating the Database Dictionary record will prompt you with this screen to confirm a regen on the file. 8. You can either click OK (regen file) to continue with the regen, click Cancel (F3) to abort the regen and restore the Database Dictionary record to the version prior to the latest changes, or schedule a time for the file regeneration, using Schedule (clock button). Refer to the Database Manager section of the System Tailoring Guide for more information on regenerating record data.
Modifying keys: single <-> concatenated

The following screens illustrate how to modify the single key model in the enduser Database Dictionary record to make it a concatenated key comprised of the fields model and location. 1. Position the cursor on the key type nulls&duplicates, above the key model. 2. Click Edit. 3. Add location in the second element of the field names array below model.
10-44
Figure 10-31. Adding concatenated value to existing key
4. Click OK to close the window.
Figure 10-32. Existing key modified to become concatenated
5. You can now re-edit your Database Dictionary record, update it, or cancel without updating. 6. Click OK, to close and automatically update the file.
10-45
This returns the message Record updated in the dbdict file. If records already existed in the file when you modified a key, updating the Database Dictionary record will prompt you to regenerate the file. 7. You can either click OK (regen file) to continue with the regen, click Cancel (F3) to abort the regen and restore the Database Dictionary record to the version prior to the latest changes, or schedule a time for the file regeneration, using Schedule (clock button). Refer to the Regenerating Database Keys from Database Manager on page 7-5 for more information on regenerating record data.
10-46
Deleting a Field
After you have created a Database Dictionary record, you might decide that a field(s) originally defined in the dictionary is no longer needed. If no data exists in the file, you will see a delete option key on the screen when you edit the given field. You can delete the field from the Database Dictionary record. Also remember to delete the field from all associated formats. Note: When you delete a field from a Database Dictionary record, you must check the key list to see if the field is a key or part of a key in the file. If so, you must modify or delete the key to remove the field name. Remember, all keys defined to the file must also exist as fields. The field should also be removed from any associated format(s). If data exists in the file, you cannot delete a field(s) from the Database Dictionary record without first removing the data from that field. The delete key is not present when you edit the given field. If you do not want the field(s) and associated data in the file, you can perform a Mass Update to blank out (NULL) the data in the existing records. You can then rename the field(s) to depict that it is no longer in use (e.g., old.field, old.field1, etc.) The following screens illustrate how to delete the field old.vtam.name from a copy of the enduser file, called enduser1. Lets assume this Database Dictionary record is a copy with no data existing in the enduser1 file, meaning no records have been saved to this file. 1. Select the old.vtam.name field.
10-47
2. Click Edit.
Figure 10-33. Deleting a field
3. Verify the field you selected is displayed in the pop-up window. 4. Click Delete either in the field.window or on the main Database Dictionary form to delete this field from the enduser1 Database Dictionary record. The delete operation requires a confirmation to remove the field. 5. Click Yes in the dialog box to confirm the delete. The screen re-displays with the field old.vtam.name removed from the list of fields. 6. You can now re-edit your Database Dictionary record, update it, or cancel without updating. Note: Remember to delete the field from the appropriate forms. Refer to Forms Designer for details on modifying forms. 7. Press OK, to close and automatically update the file. This returns the message Record updated in the dbdict file.
10-48
Figure 10-34. Field removed from record
10-49
Deleting a Key
Along with the need to modify existing keys, you might also want to delete keys no longer required. Remember, there is a direct correlation between the number of keys defined in a Database Dictionary record and the length of time it takes to add a record to that file. Refer to the ServiceCenter Performance and Tuning Guide available through Peregrine Systems Professional Services for information on key optimization. If you delete a key in a Database Dictionary record, ServiceCenter automatically performs a file regeneration when you update the Database Dictionary record. The following screens illustrate how to delete the nulls & duplicates key for old.vtam.name from the enduser Database Dictionary record. 1. Select the key type, nulls&duplicates, above the vtam.name key. 2. Click Edit. 3. Verify the key you selected is displayed in the window in the bottom of your screen. 4. Click Delete on the main Database Dictionary format to delete this key from the enduser1 Database Dictionary record.
Figure 10-35. Deleting a key from record 10-50 System Tailoring, Vol. 1
A dialog box now appears, requiring a confirmation of the delete action. 5. Click Yes to confirm the delete. The pop-up window reappears with the next key and key type definition displayed (in this example, model). 6. Click OK to close the window without modifying this key. The screen re-displays with the key old.vtam.name removed from the list of keys and the keys below it moved up to take its former place.
Figure 10-36. Record with key deleted
7. You can now re-edit your Database Dictionary record, update it, or cancel without updating. 8. Click OK, to close and automatically update the file. This returns the message Record updated in the dbdict file. 9. You can either click OK (regen file) to continue with the regen, click Cancel (F3) to abort the regen and restore the Database Dictionary record to the version prior to the latest changes, or schedule a time for the file regeneration, using Schedule (clock button). Refer to the Database Manager section of the System Tailoring Guide for more information on regenerating record data.
10-52
Chapter 11 Advanced Operations

Copying a Database Dictionary
You can make copies of your Database Dictionary record for backup purposes or to create another file with very similar dictionary definitions. When you copy a Database Dictionary record, you have the option to copy the record only or the record and all individual data records contained in the file. If you copy the Database Dictionary record and all associated records, data in the original file is inaccessible during the copy process. The amount of time it takes to copy the file and records will vary depending on how many records are in the original file.
Copying Database Dictionary record only

The following screens illustrate how to make a copy of the Database Dictionary record in the enduser file distributed in the Inventory/ Configuration application. In this example, we will copy only the Database Dictionary record, not the data records. 1. Open the enduser record through Database Dictionary. 2. Select Options > Copy/Rename.
Figure 11-1. Copy/Rename Options menu selection Advanced Operations 11-1
3. Enter enduser1 in the New Name field of the rename screen. Note: File names must be one word; no blanks and no special delimiters are allowed. 4. Select the Copy dbdict only radio button.
Figure 11-2. Copying the data structure record only
5. Click OK to begin file copy. You are returned to the copied record. The message Dbdict successfully copied appears at the bottom of the screen. 6. You may now make changes to the enduser1 copy of the enduser Database Dictionary record. 7. When finished with the record, click OK to exit. Note: You are required to update/regenerate your Database Dictionary record only if you have added, deleted, or modified fields and/or keys.
Copying Database Dictionary record and data records

The following screens illustrate how to make an online backup copy of all the records in the enduser file by creating a new file with the same Database Dictionary structure and containing all records contained in the original file.
11-2
Whenever you want to copy records from a file by copying the entire file, you must copy the associated Database Dictionary record as well. 1. Select Options > Copy/Rename.
Figure 11-3. Copy/Rename Options menu selection
2. In the New Name field, enter enduserbackup. (Remember, file names must be one word. No blanks and no special delimiters are allowed.) 3. Select the Copy dbdict and data option to copy all records and the Database Dictionary record from the enduser file to the enduserbackup file. 4. Click OK to copy the record and data stored in the file. Note: The length of time it takes to copy a file with all records will vary depending on how many records exist in the file. It is recommended that copying a file with all associated records be performed during nonpeak operation times.
Advanced Operations
11-3
Figure 11-4. Making backup of current record and data
The Database Dictionary record for the enduserbackup file is displayed and the message *Dbdict successfully copied appears at the bottom of the screen. Note: When an asterisk displays in front of a message, it means there are additional messages to display which may have relevant information regarding this operation. To view all messages associated with this operation, click the M (Messages) button just below the top menu bar. This displays a small message window containing any additional messages.
You can now make changes to the enduserbackup Database Dictionary record. 5. Click OK to exit when you have completed modifications to this file. Note: You will be required to update your Database Dictionary record only if you have added, deleted, or modified fields and/or keys.
Renaming a Database Dictionary Record

After you have created a Database Dictionary record, you may decide that you want to change the name of the file, or you might want to change the name of one or more of the files sent with the base system. For example, you might want to rename the communications file to multiplexors. This would change the file name but retain all of the field and key definitions in the dictionary. If records exist in the file, renaming the Database Dictionary record will associate all of the records with the new dictionary name. This differs from copying a file because it takes only a few seconds to perform this function. The following screens illustrate how to change the name of the communications file to multiplexors. 1. Open the communications Database Dictionary record. 2. Select Options > Copy/Rename. The Copy/Rename dialog box is displayed. 3. In the New Name field, enter multiplexors. (Remember, file names must be one word. No blanks and no special delimiters are allowed.) 4. Select the Rename option to rename the file to multiplexors.
Figure 11-5. Renaming current record and data
5. Click OK.
Advanced Operations
11-5
The renamed Database Dictionary record is displayed with the following message in the status bar: Dbdict successfully renamed.
Figure 11-6. Renamed record
6. Click OK to exit the record and save the file with the new name.
11-6
Deleting a Database Dictionary Record

If you decide that you no longer need a file, you can delete the Database Dictionary record.
Warning! If you delete a Database Dictionary, all records contained in the file are also deleted.
The following screens illustrate how to delete a Database Dictionary record called endusercopy. 1. Open the Database Dictionary record you wish to delete. 2. Click Delete. This operation requires a confirmation, and a delete file confirmation window appears. 3. Click Yes to delete the record and all data associated with the endusercopy file. Note: The amount of time it takes to perform the delete will vary depending on how many records are in the file. It is recommended that deleting a file with a large number of records be performed during non-peak operating times. After the file is deleted, you are returned to the Database Dictionary prompt and the message endusercopy file deleted is displayed on the bottom of your screen. 4. Press Back to exit the Database Dictionary prompt.
Advanced Operations
11-7
Resetting the Database and All Records

If you decide the records in a file are no longer needed, but the file structure is to be retained for later use, you can perform a file reset. The Reset option deletes all data records from a Database Dictionary file. In most instances, once a system has been set up and is in operation, this option will not be used. Most often it is utilized when clearing test data from a preimplemented system or test file.
Warning! This option is only used when the intention is to permanently remove data file records. Once a reset has been performed, the records cannot be retrieved.
The following screens illustrate how to reset a Database Dictionary record called endusercopy2. 1. Open the Database Dictionary record you wish to reset. 2. Select Options > Reset. Note: This option does not appear for files that contain no data records. You are prompted to confirm this reset action.
3. Click OK to confirm this reset and erase all records in this file. 4. Click Cancel to quit and return to the Database Dictionary record. 5. Click Schedule (clock) to schedule the reset to perform at a designated time. If you clicked OK, the reset performs immediately in the foreground. When completed, a message appears at the bottom of the screen confirming the time/ date of the file reset and the removal of all records. The asterisk (*) at the beginning of the message indicates there are additional messages generated and available to read in relation to this operation.
6. Click M in the Tool Tray to view these messages. 7. Read the messages and identify if any problems or errors occurred during the operation.
Scheduling the reset

If you chose to schedule the reset operation at step 6 above, you are prompted with a schedule window.
Figure 11-7. Scheduling file resetting action
1. Set the date and time for the operation to run in the Date/Time field. 2. If you want this operation to run periodically, flushing out data records from this file regularly, provide the appropriate date and time for the interval in the Repeat Interval field. 3. Click Schedule (the clock) to confirm the schedule and activate it.
Advanced Operations 11-9
You are returned to the Database Dictionary file which will be reset.
11-10
Information Pooling
ServiceCenter supports a multiple data-storage pool structure consisting of several 2-gigabyte pools. These pools provide a way of separating data into multiple Windows NT, UNIX (or MVS) files. There are two types of pools; data and index. Every Database Dictionary file has one of each of these information files. The data pool stores the data records for that file. The index pool stores the index and relationships of fields in the Database Dictionary.
Figure 11-8. Data and index pools
The primary pool is pool 3, the SCDB.DB1 file. New pools can be created (4 = scdb.db2, 5 = scdb.db3, etc.). For more information and specific details on P4 pool operations see the P4 Filesystem section of the Data Administration Guide for more information. When a new Database Dictionary file is created, the default data and index pool values are set to 3. Once more data and index pools have been created, file information can be moved to different pools. Index and data information can also be stored in different pools from one another, to allow greater control over the size and use of each data pool. See the P4 Filesystem section of the Data Administration Guide for more information.
Modifying pool settings

1. To display the information pool modification window, select Options > Move To New Pool.
Advanced Operations 11-11
The displayed window provides drop-down menus to specify the location and pool number for data and index information. 2. Select a new value from the list to modify the settings. 3. Click OK to confirm the new settings.
You are prompted to confirm the new settings and move the data accordingly. 4. Click Yes to confirm the action.
See the P4 Filesystem section of the Data Administration Guide for more information on Data Policy and Information Pool settings.
11-12
Searching for a Field

The ability to search the dictionary for a specific field name can be very useful when dealing with a large database dictionary. The following example illustrate how to search for a field. 1. From within the Database Dictionary record you want to search, select Options > Field Search. This brings up the Field Search window prompt.
Figure 11-9. Fieldname search capability
2. Enter the field name to search, for example, one. 3. Click Exact match if you are sure that what you entered is a field in the dictionary record. 4. Click Starts with to find all fields starting with the string entered. 5. Click Contains to search for fields containing the string entered anywhere in the field name. (Used in this example). 6. Click End to cancel the search. If the system finds a match, it responds by giving a message similar to the following: *Field phone found: type=character; level=3; index=2 The message gives the field type, the level (how many structures down the field is located), and the index (location within its parent structure). For example, one appears in: a character type field (phone) in the third level structure (alternate.contact) as the second field in the alternate.contact structure.
Advanced Operations
11-13
7. If multiple fields are found by the search, multiple messages are returned, one message for each field found. The message in the above example displays an asterisk (*), indicating it does have additional messages to display. 8. To reveal all messages from this operation, click M in the tool tray. This displays a small message window containing all messages produced by the last operation performed.
In this example, these messages reveal that one is present in at least two fields in this Database Dictionary file. However, since the Contains button was used, the letters are found in their specific order, regardless of where they appear in the field name. For a more exact match on the word one you can use the Exact match or Starts with button. (Using these options against this example returns no positive hits using Exact match or Starts with.)
11-14
Chapter 12 Notification Engine

The Notification Engine is primarily responsible for sending messages that are generated by ServiceCenter events, such as opening or closing an incident ticket. Administrators can edit these messages, add new messages, change the conditions under which the messages will be sent out, as well as select who will receive the messages. The notification database stores the list of messages that are sent for a given event, the conditions under which each will be sent, and who should receive the message. Messages may vary for each recipient and differ in type. The advantages of a centralized message system are many; consistency across modules, centralized notifications for easy update and customization, and significantly, the ability to customize notifications with RAD expressions without having to purchase a RAD license or having to touch the RAD layer of ServiceCenter. Most message applications create output events and establish the connection via Event Services. Users can add or edit notifications, but must stick with the names of those notifications that are already in the system. There is no such restriction on message types. However, you must be able to call the application that is set in your definition.
Notification Engine
12-1
The Notification File

The notification file works with the message, messagetype, and On Call Schedules files to define notifications for common system events, how those notifications should be delivered, and who they should be delivered to. Administrators can modify the notification arguments that trigger the notification, as well as define who receives the notification. Opening the Notifications File: 1. Start a ServiceCenter Client and log in as an administrator. 2. Click the Utilities tab in the ServiceCenter main window. 3. Click the Administration button. 4. Click the Notifications tab. From here, you can access the areas that control the notification engine: select either Notifications, Messages, Message Types, On Call Schedules, or Daily On Call Record. 5. Click Notifications.The Notification Definition panel appears. 6. Enter the Notification Definition name in the Name text box and click Enter. For a list of all notifications shipped with this version of ServiceCenter, see Table 12-1, Notifications, on page 12-20. Alternately, perform a true search to see a list of all notification records on your particular system.
12-2
Figure 12-1. The Notification Definition Panel
Note: You cannot add new notification names to the system! The notifications shipped with ServiceCenter cover all system events. You can however add a condition to the notification that is unique, and which will be handled only when the condition is met. For example, you can add the condition
company in $L.file="PRGN"
to the CM Change Update notification record, add the new file to the system, resulting in multiple CM Change Update records that behave according to their conditions. The first three fields on this panel, Msg Class, Msg No and Arguments, determine which message to bring up from the message file.
Notification Engine
12-3
Fields on the Notifications Definition Panel

Msg Class - The message class relates to the application area. For example cm3, pm, sm, etc. Msg No - The Msg No or message number corresponds to the scmessage.qbe.g file. See Messages on page 12-9. The Message Class, Message Number, and language fields make up the unique key for this notification. If you add your own message to the message file, the combination of the Msg Class, Msg No and Language fields must not exist in the system already. Arguments - The message arguments can range from none to many. The arguments correspond to the %S in the message text. If there is only one argument, enter the value directly. List multiple arguments in an array. For example ({<arg1>,<arg2>, <and so on>}). Elements of the array can be string literals or expressions. To reference a value in a record, enter: fieldname in $L.file. Strings must be enclosed in double quotes Condition - Enter the condition under which the message should be sent. Values can be True, False, or an expression that evaluates to either True or False. The default value is True. Notify Method - This field specifies the how the message is sent (for example fax, email, etc.). This field can also specify the name of a message class. However, using the Notify Method field is more direct. Recipients - Specify whom to send the message to. Enter an expression or string literal that references an individual user or group name. The following fields are only necessary if the Recipients field contains a group name. Group File - Enter the file that the group name is referencing. If you use this field with either ocmgroups or cm3groups, you can also specify members of those groups by using the Group area and Sub group fields. If you create an On Call Group from the On Call Schedule panel, say PRGN Admin, then the Group Area and Sub Group fields do not apply. Group Area - Acceptable values for use with the ocmgroups file are: All, Quotes, Line Items, and Orders. Acceptable values for use with the cm3groups file are: All, Changes, and Tasks. Subgroup - The subgroup field further specifies the user list. Values are Members/Reviewers, Approvers and All.
Editing a Notification Record

Administrators can add to or change the fields in a Notification Record, including the recipients of a particular message, the conditions under which
12-4
the message will be sent, and the arguments the message will use, by editing the records Notification Definition in the notification file. To edit a Notification Record: 1. Open the notification file. See Opening the Notifications File: on page 12-2. 2. Enter the Notification Records Name and Condition in the search fields, if you know them, and click Search. The related Notification Records will appear. If you didnt enter anything, all Notification Records will appear. 3. Select the desired Notification Record. The Notification Definition will appear at the bottom of the screen. Note: The fields Name and Condition make up the unique key of a Notification Record. 4. Edit the Message Class, if desired. (cm3, pm etc.) 5. Edit the Message Number, if desired. (the message id) The Message Class, Message Number and Language fields form the unique key that the program will use to determine which message in the scmessage file will be sent by this notification. 6. Enter or edit the Arguments the message should use, if desired. Depending on the referenced messages text, as stored in the scmessage file, the number of arguments range from none to many. If there are no arguments in the referenced message, leave this line blank. If there is only one argument, enter that value directly. If there are several arguments, list them in an array, enclosed by braces and separated by commas ({,,}). The format for referencing a value in the record is fieldname in $L.file. The format for string is just the string itself enclosed by double quotes. 7. Edit the Conditions under which this particular message should be sent, if desired. The condition can be true or false, or any expression that evaluates to true or false. 8. Select the Notify Method from the drop down list, if desired. If you do not make a selection, the Notify Method will default to msg. 9. Select the Recipient(s): Enter the recipient of the message. This Recipient can reference more than one person if it is, for example, an email Group Name. Enter only the Recipient(s) if it is one person, or both Recipient(s) and Group File if its a Group Name. Recipient(s), Group File, Group Area, and Subgroup work together to select the appropriate recipients from each group. Recipient(s) can be
Notification Engine
12-5
either a single person or a group name. If a groups name has been entered, the Group File specifies exactly which group it is. Notifications can be sent to the people in a group who are on call, rather than to an entire group. To do this, select oncall as the Group File in the Notification Records Notification definition. The group must be defined as an oncall group. See On Call Scheduling on page 12-12. 10. If the recipient is a Group Name, select the Group File that will receive the message from the drop down list. The Group Files cm3groups and ocmgroups cannot be uniquely keyed by just the group name. For those two groups, select the Group Area from the drop down list and Subgroup from the drop down list. For example, if you have ASSET MANAGEMENT as the Recipient(s), cmgroups as the Group File, changes, Tasks, All as the Group Area and Approvers as the Subgroup, the message will go to the members of the Asset Management Change Management group. 11. Repeat step 4 through step 10 for each entry in the record you are changing. 12. Save the notification file
Adding new fields to a Notification Record

ServiceCenter can generate messages under your specified conditions by adding new rows to a records Notification Definition in the notification file. To add a new row to a record in the notification file: 1. Open the notification file. (See Opening the Notifications File: on page 122.) The Notification Definition window will appear. 2. Enter the Notification Records Name and Condition in the search fields, if you know them, and click Search. The related Notification Records will appear. If you didnt enter anything, a list of all Notification Records will appear. 3. Select the desired Notification Record. The Notification Definition will appear at the bottom of the screen. 4. Make your entries in the next available row. Note: The fields Name and Condition make up the unique key of a Notification Record. Do not change them. 5. Enter the Message Class. 6. Enter the Message Number.
7. Enter the Arguments the message should use, if necessary. Depending on the referenced messages text, as stored in the scmessage file, the number of arguments range from none to many. If there are no arguments in the referenced message, leave this line blank. If there is only one argument, enter that value directly. If there are several arguments, list them in an array, enclosed by braces and separated by commas ({,,}). The format for referencing a value in the record is fieldname in $L.file. The format for string is just the string itself enclosed by double quotes. 8. Enter the Conditions under which this particular message should be sent, if desired. The condition can be true or false, or any expression that evaluates to true or false. 9. Select the Notify Method from the drop down list, if desired. If you do not make a selection, the Notify Method will default to msg. 10. Select the Recipient(s): Enter the recipient of the message. This Recipient can reference more than one person if it is, for example, an assignment Group Name. Enter only the Recipient(s) if it is one person, or both Recipient(s) and Group File if its a Group Name. Recipient(s), Group File, Group Area, and Subgroup work together to select the appropriate recipients from each group. Recipient(s) can be either a single person or a group name. If a group names been entered, the Group File specifies exactly which group it is. 11. If the recipient is a Group Name, select the Group File that will receive the message from the drop down list. Note: The Group Files cm3groups and ocmgroups cannot be uniquely keyed by just the group name. For these two groups only, select the Group Area from the drop down list and Subgroup from the drop down list. For example, if you have:
Asset Management as the Recipient cmgroups as the Group File Approvers as the Subgroup
the message will go to the members of the Asset Management Change Management group, who approve orders. 12. Repeat step 6 through step 11 for each entry in the record you are creating. 13. Save the notification file.
Notification Engine
12-7
Notification FlowChart
Notification Engine
ServiceC enter event fires off a Notification.
Notification Engine loops through each row in the N otification file, exiting when com plete
No
D o the conditions in this record evaluate to true?
Yes
Notification Engine loops through each row in the Record, exiting when com plete.
No
ServiceCenter M essenging sends out the m essage as specified in the N otification R ecord.
Yes
D o the conditions in this row evaluate to true?
12-8
Messages
Administrators can edit the messages that are sent for ServiceCenter events, and add new customized messages by editing records in the scmessage record.
To view, edit or add a record in the message file: 1. Start a ServiceCenter Client and log in as an administrator. 2. Click the Utilities tab in the ServiceCenter main window. 3. Click the Administration button. 4. Click the Notifications tab. 5. Click the Messages button. 6. Open the appropriate message record. a. To search for a record, enter any identifying search information. (For example enter us or cm3, etc. in the Class field) and click search. The related records will appear. b. Click on a record to select it. The records information will appear. The text of the message appears at the bottom of the entry in the box labeled Text. You can view multiple records by selecting Record List from the ServiceCenter View menu. c. Perform a true search to see all scmessage records. The messages Language Code, Class, and Message Number form the unique key that identify the message. Do not edit those unless you are creating a new message. If you create a new message, be sure to Add rather than Save. 7. Edit the messages Severity. 8. Edit the messages Text. 9. Add your Comments, if desired. 10. Click Save to save your changes, or click Add to add the record as a new message.
Notification Engine
12-9
Figure 12-2. The scmessage panel
Fields on the message panel

Language Code - Defaults to the language in which ServiceCenter is currently running. Class - The message class refers to the ServiceCenter application to which the message pertains. Message Number - The message ID. Severity - Reserved for future use. Text - Enter the message text in this field. Arguments are denoted as %S or %S[n] if there is more than one argument. Comments - This field is optional, and is used to further describe the message.
Message Type
The message type defines how a message is sent (i.e. fax, page) and corresponds to the "notify method" in the notification definition. The msgtype file stores the RAD application to call when processing a message of a given type. There are currently eight predefined message types and message applications. Unlike notifications, additional message types can be created and incorporated into the engine by adding a record to the msgtype file and making sure the new type is available on the notification screen. The application can be taken from the canned system or created from scratch (by a system administrator in most cases).
Figure 12-3. The Message Type Panel
Fields on the Message Type Panel

Type - Enter a unique name that can be called by the Notification engine. Description - Enter a description of the Application and its function. Application - Enter the application to call. This application must be defined in RAD code and exist on the system in order to work.
Notification Engine
12-11
On Call Scheduling
Notifications can be sent to the people in a group who happen to be on call, rather than to an entire group. To do this, select oncall as the group file in the notification record. For more information on editing Notification Records, see Editing a Notification Record on page 12-4. In determining recipients, the Notification Engine refers to the Group File. If the Group File selected is oncall, then only the people scheduled as On Call for that day will receive the notification. The members of the oncall group are redefined daily from the oncallsched file. The oncall Group File can be selected for use in a Notification Record. Oncall record is created daily at 12 A.M. by default, using the info in the oncallsched database. Oncall is not modifiable; changes in shifts and contacts must be made in the oncallsched file, which will then be reflected by the associated oncall. The On Call Schedule for a day is created at midnight, and covers the next 25 hours, so that there is a one hour overlap. The On Call Schedule can be modified by an administrator to start at any time during the day, and run for 25 hours. Midnight is the default setting. The daily oncall Group File can be viewed, but not edited directly since it is auto generated. To edit the oncall schedule, open the oncallsched file in Database Manager.
12-12
Fields on the Oncall Schedule Panel
Figure 12-4. The OnCall Schedule Panel
The Daily Schedule tab

Contact - Enter the name of the person receiving the notification. The individual can be either an operator or a contact. Start - Enter the start hour, in 24 hour format. For example 08:00:00. The default is 00:00:00.
Notification Engine
12-13
End - Enter the end hour, in 24 hour format. For example 17:00:00. The default is 23:59:59 Days of the week - Enter True if the contact is scheduled for that day, or false if not. The default is false. Notify Method - Select the notification method from the drop-down list. Condition - Enter either True or False, or an expression that evaluates to True or False, in order to process the record. The default is True.
The Exceptions tab

Contact - Enter the name of the person receiving the notification. Start Date - Enter the start date, in standard ServiceCenter format. End Date- Enter the end date, in standard ServiceCenter format. Notify Method - Select the notification method from the drop-down list. Condition - Enter either True or False, or an expression that evaluates to True or False, in order to process the record. The default is True. Replace Daily - If this field is set to True, then the Exception fields will override the Daily Schedule fields, for the selected contact name. If both Daily Schedule and Exceptions hours have been defined for a person, setting Replace Daily to false causes both sets of rules in the oncall record to be followed. If Replace Daily is set to true, only the exception hours will be listed.
Creating an oncall schedule

To create an oncall schedule: 1. Open the file oncallsched using Database Manager. 2. Enter the Group Name you want to determine the schedule for. 3. Select the Daily Schedule tab. 4. Enter the Contact name. 5. Enter the Start time. 6. Enter the End time. 7. Mark the days of the week as true or false. The default value is false. 8. Select the Notify By method from the drop down list. 9. Enter the condition that applies. A valid entry is either true or false or any expression that evaluates to true or false.
10. Select the Exceptions tab. 11. Enter the Contact name. 12. Enter the Start date. You must enter at least the full date (mm/dd/yy). If no time is entered, the time is defaulted to 00:00:00. 13. Enter the End date. You must enter at least the full date (mm/dd/yy). If no time is entered, the time is defaulted to 00:00:00. 14. Select the Notify By method from the drop down list. 15. Enter the Condition that applies. A valid entry is either true or false or any expressions that evaluate to true of false. 16. Select true or false from the Replace Daily drop down list.
Modifying an oncall schedule

When a contacts availability changes for a short period, the administrator can update the oncall schedule so that the changes will be taken into consideration by the notification engine. To update the oncall schedule, it will be necessary to make the schedule updates in the oncallsched file, and then run the oncall schedule. Update a contacts oncall schedule: 1. Open the file oncallsched using Database Manager. 2. Enter the Group Name you want to determine the schedule for. Run the oncall schedule after updating the schedule, to have updates included in the daily oncall file. Update the schedule: 1. Make the appropriate changes to the oncallsched record. 2. Open the schedule file. 3. Select the Oncall Notification Processor record. 4. Change the Expiration to a time that has already passed. 5. Save the file and exit. The next time incident scheduler runs, it will notice that Oncall Notification Processor expiration time has passed, and will cause the update to be run. The new expiration date will be set to the following midnight.
Notification Engine
12-15
Oncall Flow
On Call Scheduling
An Administrator enters the daily schedules into oncallsched
New Oncall schedule is produced at midnight.
Notification engine goes to the next row in the record, exiting when complete.
No
A ServiceCenter Event sends a notification to the Oncall Notification Group.
Is this person oncall today?
Notification engine loops through the oncall records.
Yes
Message is sent via the method specified in the Notification Record.
12-16
Daily On Call Records

The Daily On Call Records panel displays an overview of the members of a group who are on call for a given day. The information refreshes based on incident scheduler. Note: You cannot create an On Call Record from this panel. To display an On Call Record for a given group: 1. Click Utilities on the system administrators home menu. 2. Click the Administration button. 3. Click the Notifications tab 4. Click Daily On Call Records. A blank On Call Record displays. 5. Enter a group name and press enter, or just click search to bring up a list of all group names on your system. The system ships with one group defined, PRGN Admin. Selecting a group displays the schedule for the members of that group.
Figure 12-5. On Call Schedule
Notification Engine
12-17
Example: On Call Schedule

The following panels ship with ServiceCenter. For example purposes, a group named PRGN Admin has been created. You can access this example and modify it for your own use by clicking search from a blank On Call Schedule.
Figure 12-6. Example On Call Schedule
The members of the group have had their regular, daily schedules defined, as per the field definitions for this panel. Note FALCONs schedule is irregular and that she has two definitions, one for Monday/Wednesday/ Friday, the other for Tuesday and Thursday. Note also the different notification methods for each of the two lines: one email, one page, based on the assumption that when FALCON is off site, she will not be able to access email.
12-18
Figure 12-7. Example On Call Exceptions
Should members of your group be travelling, on vacation, or deviating from their defined On Call Schedule for whatever reason, then you must use the Exceptions tab to define the exceptions. Note the exception for Thompson and Peters that overrides their On Call schedule for the period specified.
Notification Engine
12-19
Figure 12-8. Example Daily On Call Schedule
The Daily On Call Record panel takes the information entered in the On Call Schedule panels and displays the members of group, daily. You cannot modify the information being displayed from the Daily On Call Record panel; this panel displays the current definitions only. You can, however, take the information and definitions from the PRGN Admin group and modify them to make them your own. Just be sure to save it out to a different group name. The information on this panel refreshes daily, or whenever the incident scheduler is run.
Default Notification Definitions

The following table lists the Notification Records that ship with ServiceCenter 4 and their basic function:
Notification Record Clone Relation CM Approve Action sent when a user copies associations of a cloned incident or call sent when a user approves a change phase Table 12-1. Notifications
12-20
Notification Record CM Change Close CM Change Open CM Change Update CM Disapprove CM Task Close CM Task Open CM Task Update CM Unapprove CM Unapprove All CM Unapprove One due date notice ICM Attribute Add ICM Attribute Update ICM Children Update ICM Delete ICM Device Add ICM Device Update late notice IM Action Alert IM Action Close IM Action Open IM Action Reopen IM Action Update IM Alert Reassign IM Edit Close
Action sent when a user closes a change phase sent when a user opens a change phase sent when a user updates a change phase or opens one thats been deferred sent when a user disapproves a change sent when a user closes a task phase sent when a user opens a task phase sent when a user updates a task phase or opens one thats been deferred sent when a user unapproves a change phase sent when a user unapproves all levels of a change phase sent when a user unapproves one level of a change phase sends the message that corresponds to the due date notice alert sent when a user adds an attribute sent when a user updates an attribute sent when a user updates a device's children sent when a user deletes a device type sent when a user adds a device sent when a user updates a device sent when an item reaches due date sent when a user updates an incidents alert status sent when a user closes an incident sent when a user opens an incident sent when a user reopens an incident sent when a user updates an incident sent when an incident exceeds the reassignment limit sent when a user closes an incident Table 12-1. Notifications
Notification Engine
12-21
Notification Record IM Edit Close Cascade IM Edit Close Linked IM Edit Open IM Edit Reopen IM Edit Resolve IM Edit Update IM First Open IM First Close IM First Resolve IM Save Relation RM Approval RM Denial RM Final Approval RM Final Denial RM Line Item Change Category RM Line Item Close RM Line Item Drop Avail RM Line Item Mark Avail RM Line Item Open RM Line Item Reopen RM Line Item Update RM Order Change Category
Action sent when a user closes an incident and its related calls sent when a user closes an incident but not its related calls sent when a user opens an incident sent when a user reopens an incident sent when a user resolves an incident sent when a user updates an incident sent when a user opens an incident sent when a user closes an incident sent when a user resolves an incident sent when a user opens a related incident for a call and ends up linking the call to an existing incident instead sent when any approval action is taken against the request or order sent when any denial action is taken against the request or order sent when the request is completely approved sent when the request is completely denied sent when a user manually changes the category of a line item sent when a user manually closes a line item sent when a user marks a line item as unavailable sent when a user marks a line item as available to order sent when a user opens a new line item sent when a line item is reopened sent when a line item is updated sent when a user manually changes the category of the order Table 12-1. Notifications
12-22
Notification Record RM Order Close RM Order Open RM Order Update RM Request Change Category RM Request Close RM Request Deferred Request Late Notice Request Not Approved Request Not Ordered RM Request Open RM Request Open Next Phase RM Request Phase Change RM Request Reopen RM Request Update SM Add SM Close SM Save SM Update Save Association Save Relation
Action sent when an order is closed sent when an order is opened sent when an order is updated sent when a user manually changes the request category sent when an order is closed sent when a request is deferred sent after a specified due date sent when a request is denied or not approved sent if the request is not in the ordering phase within one day of the date that the first line item is ordered. sent when a request is opened sent when the quote moves from one phase to the next sent when a user manually changes the phase of the request sent when a request is reopened sent when a request is updated sent when a call is opened in an active state sent when a call is closed sent when a call is opened in an inactive state sent when a call is updated sent when linking two associated records sent when opening a related record Table 12-1. Notifications
Notification Engine
12-23
12-24
Chapter 13 Introduction to Format Control

Overview
Chapters 13 through 1 cover the Format Control utility, and are broken out in the following manner: Chapter 13, Introduction to Format Control Provides a brief description of the follow-on chapters and describes the knowledge requirements for users. Chapter 14, What is Format Control? Covers the features and flow of Format Control, introduces the eight processes, and defines the system language used. Chapter 15, Getting Started Describes how to access Format Control from within ServiceCenter and how to add records. Chapter 16, Format Control Processes Describes each Format Control process and gives examples. Chapter 17, Array Maintenance Describes array maintenance (sorting, inserting, deleting, moving lines) applications for simple arrays and arrayed structures. Chapter 18, Sequential Numbering for Format Control Describes how records can be numbered automatically with a userdefined sequence through the use of Format Control. Chapter 19, Posting Describes the process of Posting data from a source file to a target file with Format Control. Chapter 20, Error Messages Describes the possible error messages a user could receive. Chapter 21, Special Processing Considerations Explains the requirements for applying Format Control to the Incident and Change Management applications. Chapter 22, Common Applications Called from Format Control Lists applications commonly called from Format Control and defines their parameters.
Introduction to Format Control
13-1
System Administrators using Format Control needs a basic knowledge of ServiceCenter utilities, applications, and system language. Other topics referenced from this guide are: Forms Designer, Link Maintenance, and the System Language Guide.
13-2
Chapter 14 What is Format Control?

Format Control allows the System Administrator to apply the following special processes to ServiceCenter files through individual forms: Validate fields. Establish user privileges. Display alternate QBE forms. Do Calculations and Validations based on other fields in this file or other files. Call RAD routines. Define additional options and menu items. Automatically update or insert data in other parts of the database. Format Control records can be attached to any form or file within ServiceCenter and do not require special programming skills to implement. Routines defined in Format Control can be user interactive or transparent and are performed when a record is displayed or when a user adds or updates a record or deletes a record from the database. Format Control is easily applied and changed. Format Control is intended as a convenient utility and should not be overused. Excessive reliance on Format Control to modify your system can result in reduced system performance. If you intend to heavily customize your system, we recommend you find other, more efficient ways to implement your changes such as macros, Data Policy, or, if needed, RAD, and limit the use of Format Control.
What is Format Control?
14-1
Format Control Process Flow

Format Control Record Selected Initialization Process of Format Control Record(s) Selected from Database
File Opened by User
Format Control Applied Before Display
Data Displayed on Screen
User Action
Add a New Record
Update the Current Record
Delete the Current Record
Format Control Applied Before Add
A
Validations Fail
Format Control Applied Before Update
A
Validations Fail
Format Control Applied Before Delete
Validations Succeed
Validations Succeed
Validations Succeed
Record Added to Database
Record Updated in Database
Record Deleted From Database
Format Control Applied After Add
Format Control Applied After Update
Format Control Applied After Delete
14-2
Format Control Processes

There are eight major functional processes in Format Control that define the actions to be taken on a record. Each of these processes is represented by a separate form within the Format Control Utility.
Initializations
This form is the entry point in Format Control and has several functions: Initializes fields or variables that will later be used in the Format Control record. Initially displays a value in a field when the record itself is displayed. Names special QBE and initial query forms to use, sets up default sort sequences, and runs scripts.
Validations
The Validation process allows you to set up a logical expression for checking data in fields or variables on the form. The validation expression you set up must evaluate to true upon the desired edit function for it to be successful. If the expression does not evaluate to true, a validation message will be displayed, and the specified operation will not be allowed.
Calculations
The Calculations process can be used whenever you want to perform a calculation on currently available fields or variables. The fields needed for calculations may be variables, fields in the primary file, or fields in any other secondary files which may have been queried.
Additional File Queries

Additional File Queries are generally used to extract information from a file other than the primary file in order to perform calculations and validations and to report on information from more than one file.
14-3
Security
Security is used to control database options available to the user. If the contents of a field evaluate to true at processing time, the corresponding button will be available to the user.
Subroutines
This process allows you to call RAD subroutines.
Views
This process allows the user to display multiple QBE views of ServiceCenter forms based on conditions evaluated at run time.
Additional Options
Additional Options is used to define menu options you want available to users on any form associated with a particular Format Control record. This feature is available in Database Manager only.
Selecting a Process View

For most of the processes in Format Control, there is a short and a long view of the form. The short view is used when the Format Control information is relatively simple. The long view contains the same fields and is used when the information is more extended or complex. These views are simply two different ways of displaying the same Format Control record. When you first select one of the Format Control processes, such as File Queries, the Short View of the format is displayed. To display the Long View, select Show Expanded Form from the Options menu. If you select another process of the Format Control record (i.e. Calculations), the last view selected (long or short) is displayed as the default in the new category. A label appears on the right side of the form above the data fields indicating which view is being displayed.
14-4
Long View
Short View
14-5
Creating Expressions
Definitions
Primary File The file attached to a form. This is referred to as $file in a Format Control record. Additional files are defined as $file1, $file2, etc. in the order of their entry in the secondary files section of the Additional File Queries screen of the Format Control record. Semicolon Semicolons(;) separate statements to allow them to be entered on one line. Variable A value that resides in memory only, rather than in a database record. Variable names always start with $. To ensure that a variable contains the proper value, initialize it in the Initializations Section of the Format Control record. Statements ServiceCenter supports some BASIC-like statements. Their use will be demonstrated in various example in this chapter: if then else while do for do Note: For detailed instructions about ServiceCenters System Language, refer to the System Language topic in System Tailoring -vol. 2.
System Functions
Many of the ServiceCenter system functions are used to create expressions in Format Control. The following is a list of the most commonly used functions: denull Compresses an array by deleting all trailing NULL entries and returns the compressed array. index
Returns the index or position number for a specific element value in an array or character in a string. If the target value is not in the array or string, it returns 0 (zero). lng Returns the number of elements in an array or structure and the number of characters in a string. nullsub Replaces a null value with a known value, eliminating the possibility that expressions will return null or unknown results. operator() Sets and returns the logon id of the current operator. str Converts a nonstring data type into a string. substr Extracts a substring from a string. tod() Returns the current date and time. val Converts a field into a numeric, logical, or date/time value.
Boolean (Logical) Fields

In the forms for Additional File Queries, Calculations, Validations, and Subroutines, you will find some or all of the following fields: add update delete display before A value of true (or any variable or expression that evaluates to true) in any of these fields will cause the Format Control functions to be executed. These functions will be executed before the edit is performed. If the fields are blank,
What is Format Control? 14-7
the calculation, validation, etc. will not be performed for this file. For example, a value of true in the add field will cause Format Control functions to be performed before a record is added. If the other fields (update, delete, display) are blank, the functions will not be performed when the record is updated, deleted, or displayed. Note: The display field is used for the initial display of records or when the Format Control record is used with reports.
Important: The before field must evaluate to true or false only. A variable WILL NOT work in this field.
Normally, these fields would contain true, false, or blank, or they could contain a variable that could be calculated in the Calculations process before being used in another process. When using either of these methods, use either version (short or long) of Format Control to enter an expression that will be evaluated to true or false at execution time. This is an example of an expression that is frequently used:
index ("SysAdmin", $lo.ucapex)>0

This expression searches the users capability array in the Operator Record to see if he/she has SysAdmin capabilities. The function will be executed if this evaluates to true, indicating that the operator has SysAdmin listed as a capability and therefore is authorized for the function.
File Variable
The current database record (the record being modified or displayed by the user) in Format Control is always identified by the variable $file. Elements of the current record being acted upon by Format Control are associated with $file by expressions. For example, <field.name> in $file might identify a particular field in the current record to which a Format Control process has been attached. The $file variable does NOT reference a file, which may use several forms to input data.
14-8
Chapter 15 Getting Started

Accessing Format Control
You can access the Format Control Utility from three locations in ServiceCenter: From Forms Designer. From the Database Manager (file=formatctrl). Directly from a menu.
Access from Forms Designer

The best method for accessing Format Control is through Forms Designer. This method reduces the chances of accessing the incorrect record because you are accessing the record directly from the form with the same name as the Format Control record. To access Format Control from Forms Designer: 1. Click the Forms Designer button in the Toolkit tab in the administrators home menu. 2. Enter the name of the form you wish to see in the Form field of the Forms Designer dialogue box. 3. Use the Search function to find the form. 4. Select Format Control from the Options menu. The Format Control record is displayed for the selected form. See Figure 15-1.
Getting Started
15-1
Figure 15-1. Main Format Control Form
Direct Access
You can access Format Control directly without going through Forms Designer. This method allows you to search for an existing record or create a new record. To access Format Control directly: 1. Click the Tools button in the Utilities tab in the administrators home menu. The Tools menu is displayed. 2. Click on Format Control in the Tools tab. A blank Format Control Maintenance - Main Information form is displayed. You can either search for an existing Format Control record or create a new record from this form.
15-2
Adding a Record
To add a record to Format Control: 1. Access the form to which the Format Control record will be associated. 2. Access Format Control from Forms Designer. A new Format Control record is created for the form. ServiceCenter automatically places the forms name in the Name field. By default, a value is automatically entered in the System field (a required field) and the Use Default Sort checkbox is selected. Note: When accessing Format Control in this manner, the name of the new record is defaulted to the same name as the form used to access it. In the rare cases where a different name is needed, you can override the default name. 3. Add the desired data. These fields are discussed in the next chapter. 4. Click on the Add button to add the record to the database. 5. Use the Options menu to select the appropriate Format Control process. These processes are discussed in the next chapter.
Getting Started
15-3
15-4
Chapter 16 Format Control Processes

When Format Control is called, it evaluates user input from seven processes to modify the way data is delivered to the database. These processes are evaluated in the following order. Views Additional File Queries Calculations Validations Subroutines Additional Options Security (Privileges) Note: The order in which the processes are presented in this chapter reflects the frequency with which each process is used and not the processing order. Format Control processes are accessed through the Options menu from anywhere within a Format Control record or through the corresponding buttons. See Menu 1 below. As you move between processes, the Options menu changes to reflect the available choices. For processes containing arrays,
16-1
editing tools (Insert Line, Delete Line) are included in the menu. See Menu 2 below.
Menu 1 Menu 2
16-2
Initializations
The first form of a Format Control record is the Main Information form or Initializations process. The Initializations process of the Format Control record is used to store general information and to initialize variables to be used in other processes of the Format Control record. Initialization expressions are the first operation performed for each evaluation of a Format Control record.
Figure 16-1. Format Control Main Information Form
16-3
Fields
Name Name of the Format Control record. Format Control uses the base name of the displayed form to locate the Format Control record. The base name has the GUI (.g) or Web (.w) suffix removed; therefore, the same Format Control record is used for Text, GUI, and Web users.
Form Name
problem.initial
Format Control Record
problem.initial.g problem.initial
problem.initial.w Figure 16-2. Naming Process for Format Control Records
16-4
File Name Do not use this field. Values in this field differ in meaning between applications, and unexpected results could occur. System Free form text field that allows you to group your Format Control records by functionality. You may query by System name to display a QBE list of records in that group. Select your own unique name or use the system default, miscellaneous. Query Form This optional field is used to name an abbreviated form named designed to limit the scope of queries against large database files by reducing the number of fields available for user queries. Query forms typically contain only keyed fields for the file, and appear only in preparation for querying. Note: Limiting users query fields only to keyed fields reduces system load and speeds the querying process. For example, if you have a large database file with only three keys defined in its database dictionary, you should limit your users ability to query non keyed fields. You could create a form like figure 16-3 to limit keyed queries.
16-5
Figure 16-3. Contacts Query Form
16-6
When a record is selected using this query, the normal form (the form to which the Format Control record was attached) is displayed with all its fields.
Figure 16-4. Complete Contact Record
Default QBE Form Enter the name of the QBE form to usewhen displaying record lists, i.e., lists of records selected as a result of a query. You can create different QBE forms for different users and establish a default for each group. Note: To create a standard, default QBE form to be used for all forms and users that access a particular file, create a form called (filename).qbe. For example, contacts.qbe. This feature allows you to name different QBE forms for querying the same file. Create different forms based on user capabilities and attach them by name to the appropriate Format Control Record. Refer to Forms Designer for specific information on creating forms.
Format Control Processes 16-7
For example, you could use the Forms Designer to create a custom QBE form for the contacts file using the following values: Form name: contacts.view. Column Captions Contact Name First Name Company Phone Email Input values contact.name first.name company phone email
Figure 16-5. Custom QBE Form
Note: The Format Control Views process allows you to define many different QBE forms for use with a single data form. For specific information on this process, refer to the View section later in this chapter.
16-8
Save Copy If this option is selected, a copy or image of the primary files record will be saved before the record is displayed. The before copy is referenced as $file0, e.g., name in $file0 to reference the original value of the name field, before any changes resulting from user input. For example, if you want to be able to check whether a user changed a field, select this feature. Then, you can create calculations to set a flag, based on whether or not the value changed, for example:
if (originator in $file=originator in $file0) then $nochange=true else $nochange=false

Based on the results of this calculation, other Format Control activities can occur or not occur. Stored Form Name If this option is selected, the Database Manager application will store the name of the form used to add each record to a file in a field called format. This format field must exist in the files Database Dictionary record. For example, Incident Management and Change Management store the form name in each record so the system knows which form to use when displaying records. Use Format Control to do the same thing in other database files. Run Script If this option is selected, the system will execute the script identified in the Initialization Expressions as $script.name. For example, to collect information in a form before it is displayed for querying the database, you can build and execute a script called datacollection to prompt for information. The name of the script would be entered in the Initializations Expressions as:
$script.name="datacollection"
Refer to the Scripting chapter in the ServiceCenter Base Utilities Guide, for information about building scripts. Use Default Sort If this option is selected, the specified Default Sort Sequence for queries will always be used.
16-9
Default Sort Sequence for Queries The value in this field determines which key will be used to select data from all records. This sort sequence overrides the systems decision about the most efficient key to use for queries. If the sort sequence is not a key in the dbdict for the file, you receive the messages: Records cannot be selected from the (filename)file and Sort order must be a key.
Warning! Improper key selection can result in an inefficient query, which can adversely affect system performance.
Initialization Expressions Set initial values for variables and fields in this array. These expressions are used in subsequent calculations or to display values in forms upon initial display. They are evaluated before any other Format Control processes are evaluated against the current record. Initialization expressions are evaluated each time the form is used, either to view a record in Database Manager or to write a record to a report. The following table demonstrates how to initialize variables to different data types: Data Type character number date/time boolean (true/false) arrays Syntax $x=" " $number=0 $dt= '00:00:00' $end=false or $end=f $array={}
Note: You can set the value of variables to NULL after establishing their types.
16-10
Examples: If you want to total a variable dependent upon a value in a field in the Calculations process of a Format Control record, use Initialization Expressions to set the variables as follows:
$open=0;$update=0;$close=0
In the Calculations process of Format Control, add the following calculations:
if (open.time in $file>=tod() - 7 00:00) then ($open+=1); if (update.time in $file>=tod() - 7 00:00) then ($update+=1); if (close.time in $file>=tod() - 7 00:00) then ($close+=1)
This could be used in a report to calculate the number of problem tickets opened, updated, and closed within the last week. If you do not set these variables to 0 in the Initialization Expressions field, the system will not know these variables are numeric. In our example, the system will reset the variables to zero for each record selected before executing the other Format Control operations. If the manufacturer field in an inventory file is usually ibm, use Format Control to initialize a default value of ibm. Either leave the default value or replace it with a different manufacturer as appropriate. The syntax would be as follows:
if manufacturer in $file=NULL then manufacturer in $file="ibm" or manufacturer in $file=nullsub(manufacturer in $file, "ibm")

If a variable is to be initialized only once during evaluation of a ServiceCenter Report Writer report, the operation should be performed in a Format Control record connected to the header form. If the variable is set in the detail form, it will be reset each time a record is selected. To initialize a field or variable only once for a Report Writer report, put Initialization Expressions in a Format Control record attached to the header form:
$total=nullsub($total,0) $total now contains a value of 0 if it was previously NULL

To initialize a field or variable for a Report Writer report each time a record is read, put statements in a Format Control record attached to the detail form. Use the following statement:
$finished=false;$severity1=0;$name="ibm";$date=00:00:00
Modifying a Format Control Record

Move through a Format Control record by selecting the various processes (Views, Calculations, Additional Queries, etc.) from the Options menu or by clicking the buttons. Add or delete data in any form of the record. You may exit the record at any time: Click Back. A prompt box is displayed asking you if you want to save any changes you have made. Click on OK to save your changes and return to a blank Initializations form. Click No to return to the Initializations form without saving the changes to the record. Click Cancel to return to the current form without taking any action.
16-12
Validations
The Validations process of the Format Control Record is used for forcing a field to be required (not NULL), to be a specific value, or to be within a range of values during data entry. This is a commonly used section of Format Control because it is a simple way of field editing. Note: Validations should not be confused with Validity Tables, a different ServiceCenter utility with more flexibility and better suited to complex validations. The Format Control Validations process uses expressions in a Format Control record to establish field validity and is well suited to single field validations. Select Validations from the Options menu to display the Validations form.
Figure 16-6. ValidationsShort Form
16-13
Fields
Add, Update, Delete, Display These are Boolean fields that control Format Control processing. Processes evaluating to true apply Format Control before completing the specified operation. For example, when a user clicks Save, and before the record updates, Format Control executes every section or expression where the Update field evaluates to true. Validation An expression that evaluates to True or False. If this expression evaluates to True, then the validation is successful and processing continues. If this expression evaluates to False, then the validation fails and the validation message appears on the screen. On Failed Validation Set Focus To The field where the cursor should be positioned. When a Validation fails, ServiceCenter displays the input form again, with the error message displayed at the bottom and the cursor positioned in the field specified here (typically the field that just failed its Validation). Message Error message displayed when a field value, defined in the Validation expression, fails to evaluate to true. Message ID Error message number to display instead of the Message when the validation fails. If a Message Number is specified, a corresponding message from the scmessage file displays when the Validation fails, rather than displaying the text in the Message field discussed above. Since the scmessage file can hold messages in many languages, this is the preferred method for multi-lingual implementations.
16-14
Comments Brief comment about the field being validated.
Figure 16-7. ValidationsLong Form
Examples
Required Fields
Use the following values to make a field (location) required when adding a record or updating a database file: Add true Update true
16-15
Validations not null (location in $file) or location in $file~=NULL or location in $file<>NULL On Failed Validation Set Focus To location Message The location field is required.
Specific Values
To make a field begin with a specific value when adding or updating a record: Add true Update true
Validations type in $file #US On Failed Validation Set Focus To type Message The type field must begin with US.
Range of Values
To validate a value within a range: Add Update true true Validations amount in $file<=100000 On Failed Validation Set Focus To amount Message The amount cannot be greater than 100000.00 Add true Update true
Validations no.of.cables in $file>2 and no.of.cables in $file<25 On Failed Validation Set Focus To no.of.cables Message
The number of cables must be within 3 and 24. Add Update true true Validations dept in $file#101 or dept in $file#102 On Failed Validation Set Focus To dept Message Invalid dept name.
Conditional Values
Some validations are conditional, i.e., you only want to perform the validation if other specific conditions occur. In the example below, the Sales dept in Atlanta has only two valid cost centers: 2284 and 3401. The example shows a cost.center validation for the contacts file that occurs only if the location and dept fields contain Atlanta and Sales, respectively. This type of conditional validation works well if you have only one or two exceptional situations. However, if you have many combinations to check and verify, setting up separate conditional validations for each is very inefficient. Instead, use a more appropriate method such as: Setup a new file listing the various acceptable combinations. Use a Format Control File Query to read the appropriate record from the new secondary file. Setup a single Format Control validation to verify that the current value matches the secondary file value. In the Calculations tab, add a new line Add True Update True
Calculation: if (location in $file=Atlanta and dept in $file=Sales) then $atlsales=true else $atlsales=false Note: These conditions can also go directly into the Add, Update, Delete, and Display fields on the Validations tab, but they are harder to read and require slightly more processing since they must be evaluated twice, for both the Add and Update conditions. In the Validations tab, add a new entry: Add
$atlsales
Update $atlsales
16-17
Validation: cost.center in $file isin{2284, 3401} Message: The cost center for Atlanta Sales personnel must be 2284 or 3401 On Failed Validation Set Focus To: cost.center
To validate a value based on a condition: 1. Enter the following expression in the Calculations section of the Format Control record:
if (manufacturer in $file=ibm) then ($charge=false) else ($charge=true)

2. Enter the following in the Validations section of the Format Control record. Update Add $charge $charge Validations repair.charge in $file>0 On Failed Validation Set Focus To repair.charge Message When the manufacturer is IBM, there cannot be a repair charge.
Fields in an Arrayed Structure

The Validations process, in conjunction with the Calculations process, can be used to validate fields in an arrayed structure. In this example, we are validating the Serial Number field in the devices.covered array of the service form. If a user enters data in the Model, Install Date or Warranty fields, there must also be a valid Serial Number. Use the following values to set up the Format Control record: Calculations Process Add true Update true
Calculation expression $errorlist={};if (not null(devices.covered in $file)) then for $i = 1 to lng(denull(devices.covered in $file)) do (if (not null($i in devices.covered in $file)) then if null(1 in $i in devices.covered in $file) then ($i in $errorlist=str($i))) Note: This entire Calculation expression must be in a single line. Validations Process: Use either version A or version B - either one
16-18
will work. A. Add true Update true
Validation lng(denull($errorlist))=0 Message For each DEVICE COVERED you must supply a serial number
16-19
B. Add lng(denull($errorlist))>0 Validation false
Update lng(denull($errorlist))>0
Message For each DEVICE COVERED you must supply a serial number.
16-20
Calculations
Select Calculations from the Options menu to open the Calculations process of the Format Control record, or click the Calculations button. The Calculations process in Format Control is similar to a process Command panel and can perform the same functions without involving RAD programming.
Figure 16-8. CalculationsShort Form
16-21
Fields
Add, Update, Delete, Display These are Boolean fields that control Format Control processing. Processes evaluating to true apply Format Control before completing the specified operation. For example, when a user clicks Save, and before the record updates, Format Control executes every section or expression where the Update field evaluates to true. Calculation The Calculation expressions are only performed on variables or fields that are currently available, either from the primary file or any additional file that has already been accessed from Additional File Queries. Note: If the Format Control record is to be used with reports, it is important to remember that the processes you set up will be performed every time the form is accessed. If the Format Control record is on a detail form, the calculations will be performed on every record. If the Format Control record is on the header form, calculations will be performed on every page.
16-22
Figure 16-9. CalculationsLong Form
Examples
Simple calculations
Calculate the total amount from price and tax given below: price in $file=120.00;$tax=0.05; Calculation: $amount=price in $file*$tax Result: $amount=6.00
16-23
Perform expressions (math) on variables given below: $a=8, $b=4, $c=5, $d=2 calculations $x=$c*$b+1 $x=$c*($b+1) $x=$a*$c/$b - $d results $x=21 $x=25 $x=8
Note: Multiplication (*) and division(/) are calculated firstaddition (+) and subtraction (-) next. Subtraction must be separated by spaces (9 - 5).
Moving Characters in a Field

Strip the first three characters from a field and insert them into another field. If the first three bytes of a serial number were the same as the manufacturers name: serial.no.=ibm173605 Calculation Expression: manufacturer in $file=substr(serial.no. in $file, 1 ,3) Result: manufacturer=ibm
Calculations on Fields in Arrayed Structures

Perform calculations on fields in arrayed structures. The format: (1)manufacturer (2)model (3)quantity (4)price (5)amount (1) ibm________ 123__ _______2 100.00 200.00_ (2) dec________ 222__ _______4 200.00 800.00_ (3) ___________ _____ ________ _____ _______ The dbdict: arrayed.structure.example arrayed.structure.example manufacturer model quantity price amount
16-24
The operator enters manufacturer, model, quantity and price in a database file. Calculate the total amount of all items in the array: (amount=quantity*price) Calculation Expression: 5 in 1 in arrayed.structured.example in $file=3 in 1 in arrayed.structure.example in $file*4 in 1 in arrayed structure.example in $file In this example, the expression would evaluate to: amount=2*100.00 amount=200.00 This would have to be repeated for each possible element in the arrayed structure. To do so, you must use a for loop: for $i=1 to lng(denull(arrayed.structure.example.in$file)) do 5 in $i in arrayed.structure.example in $file=3 in $i in arrayed.structure.example in $file* 4 in $i in arrayed.structure.example in $file
Important: This statement must be entered as one continuous line.
Calculation Expression: 5 in 2 in arrayed.structured.example in $file=3 in 2 in arrayed.structure.example in $file*4 in 2 in arrayed.structured.example in $file. In this example, the expression would evaluate to: amount=4*200.00 amount=800.00 Note: The reference of a field (in an element) located in a structured array is based on how it is defined in the database dictionary, not how it is displayed in the form. Therefore, if quantity was the fifth entry in the arrayed structure in the dbdict, it would be referenced as 5 in 1 in arrayed.structure.example in $file, rather than 3 in 1 in arrayed.structure.example in $file as shown in this example.
Counting Tickets of Differing Severity Levels in a Report Writer Report

Count the number of problem tickets opened over a period of time based on severity level in a ServiceCenter Report Writer report: if(severity in $file=1) then ($sev1+=1) if(severity in $file=2) then ($sev2+=1) if(severity in $file=3) then ($sev3+=1)
At the end of the processing $sev1, $sev2, and $sev3 will contain the total number of problems for each severity level. Note: $sev1, $sev2, and $sev3 would have to be initialized once to zeros using an assignment expression ($sev1=0) in the Initializations form of the Format Control record.
Counting Open Problem Tickets in a Report Writer Report

Create a report that counts the number of problem tickets that are still open over a period of time. Expressions defining tickets still open for periods of one week, two weeks, three weeks, and over four weeks: if (open.time in $file>tod() - 7 00:00) then ($week1+=1) if (open.time in $file>tod() - 14 00:00 and open.time in $file<tod() - 7 00:00) then ($week2+=1) if (open.time in $file>tod() - 21 00:00 and open.time in $file<tod() - 14 00:00) then ($week3+=1) if (open.time in $file>tod() - 21 00:00) then ($greater.than3+=1) In the totals format of the report: Number Of Problems Still Open Within The Last Week: ($week1) Number Of Problems Still Open Between 1 & 2 weeks: ($week2) Number Of Problems Still Open Between 2 & 3 Weeks: ($week3) Number Of Problems Still Open Over 3 Weeks: ($greater.than4) Note: The Format Control record would be attached to the detail form of the report in order for the calculation to be performed for each record selected by the report. The variables would have to be initialized to zeros one time only using the nullsub function in the Initializations form of the Format Control record.
Denulling an Array
Denull an array before printing in a report, so the underscores in blank lines are not printed. comments in $file=denull(comments in $file)
Using Calculations in Reports

Create a report to calculate the percentage of problem tickets that were opened and closed within the same day: Attach the Format Control record to the detail form of the report. display: true if (date(open.time in $file)=date(close.time in $file)) then ($resolved+=1);$all.recs+=1
16-26
Note: :$resolved and $all.recs must to be set to zeros using the nullsub function in a Format Control record attached to the report header form. This would be a one-time initialization. Attach a Format Control record to the totals form: $perc=(round(($resolved/$all.recs)*100, 1) Note: The 1 at the end of the expression is the number of positions after the decimal point (43.7). Create a report to calculate the down time for specific device types over a period of time: Attach the Format Control record to the detail form of the report. $down=up.time in $file - down.time in $file $dt=(1*$down)/60 This calculates downtime in hours. Note: In this case, the result of the calculation (1*$down) converts the type of $down (which is now date/time) to numeric. The system stores this numeric value as the number of minutes since year 01/01/0001 00:01. Combine all the information from the Description and Update Description arrays of an incident ticket, regardless of array size, and attach the following Format Control calculation to the detail form of the report:
$action={"DESCRIPTION"}+denull(action in $file)+{"UPDATE ACTIVITY"}+denull(update.action in $file)+denull(resolution in $file)
Note: These calculations denull the action and update.action arrays and store their lengths. The lengths are then used to check and concatenate the information into one readable block. Put the following label and input field on the detail form where the descriptions are to begin: DESCRIPTION: _____________________________________________________________ ($action) window of (-1) An example of what the output would look like is: DESCRIPTION: description line 1 description line 2 UPDATE ACTIVITY
update line 1 update line 2 update line 3
16-28
Additional File Queries

Select Queries from the Options menu to open the Additional File Queries process of the Format Control record, or click the Queries button. This process validates data in the current file against data in other ServiceCenter files or counts records in an associated file and returns the results. The Additional File Queries process has four boolean fields that, if evaluated to true, will be evaluated BEFORE any task is performed on a record.
Figure 16-10. Additional File QueriesShort Form
Fields
Filename Enter the name of the database file to be used for the secondary file query in this field. You may use either a variable or a literal for the file name.
The primary file (named in the Name field) is referred to in the Format Control record as $file. Each additional file that is called in this section will be referred to as $file1, $file2,....$filen depending upon their position on the additional file query line. For example, the contacts file (the additional file to be queried from this form) will now be referred to as $file1.
Figure 16-11. Additional File QueriesLong Form
Query This is the expression used to select records from the database file specified in the Filename field. Once a match has been made, the data in the additional file is available for reference. For example: contact.name=contact.name in $file
16-30
contact.name is the input field name from the contacts dbdict. contact.name does not have to reference a $filename here, but refers instead to the name in the Filename field. You could interpret this expression as: contact.name in contacts file=contact.name in problem.initial file. Comments A brief comment about the use of this query or an indication that the file query should return a count of the number of records found by the query. To indicate that a count should be returned, begin your comment with "count." For example, "count location records". The count is returned as a number in a global array variable called $file.count. The position in the list is the same as the file numberthat is, the count for $file2 would be 2 in $file.count. Add, Update, Delete, Display These are Boolean fields that control Format Control processing. Processes evaluating to true apply Format Control before completing the specified operation. For example, when a user clicks Save, and before the record updates, Format Control executes every section or expression where the Update field evaluates to true. Note: Refer to Boolean (Logical) Fields on page 14-7 for detailed information on valid entries in boolean fields. Required Query? (short form: Reqd) This field is used for validations in additional files. If the field evaluates to true, the indicated function (Add, etc.) will not be performed unless the system finds an appropriate record to match the specified query. A suitable message is displayed to the user. If this field evaluates to true in our example, the additional file, contacts, would be queried to ensure that a valid entry was made in the problem ticket for the contacts name. For example, if JACKSON is entered in the problem ticket, but no record for JACKSON is found in the contacts file, the problem ticket is not added to the database and the user receives an error message. Required Field Name (short form: Field Name to Check) This is an optional field allowing you to check for a NULL state in a primary record field when no records are found as a result of executing the query against the specified file. At run time, Format Control first performs
16-31
the requested query against the specified file. If one or more records are found, processing continues normally to the next Format Control definition. If no records are found, Format Control checks for a value in the Required Field Name field. If a value is defined, it then checks the contents of that field in the primary record. The sequence of events is as follows: If the Required Field Name field is NULL and the Required Query condition evaluates to true, Format Control issues the specified error message. If an error message is not defined, it issues a default message. If the Required Field Name field is not NULL, Format Control checks for a NULL state in the contents of that field in the primary file. For example, if the Required Field Name field contains the value location, Format Control examines location in $file for a NULL condition. If Format Control does not detect a NULL condition, and the Required Query condition evaluates to true, Format Control issues the specified error message.
Note: If you need to check for multiple complex conditions in order to control the evaluation of the secondary file query, we recommend that you use the add, update, and delete conditions to specify the complex condition. Error Message This is the message to be displayed to the user if no records are found with the query. The value must be valid in the secondary file. For example: Vendor is not a valid name in the vendor fileplease re enter.
Examples
Report Information
Create a report to list hardware problems associated with different vendors. A vendors address and phone number is not on the problem record, but is desired on the report. The address and phone number values are available from the vendor file. Make the following entries in the Format Control record attached to the reports detail form: Field Values: filename
vendor query name=vendor.name in $file display true Note: The problem file is the primary file ($file), because it is defined as such in the report record. The vendor file is the secondary file($file1) from which we are extracting the values from two fields (Post Address and Phone). Field Values from the Calculations process (See following section). display true true Explanation display: trueTo be performed on display of report (always true for reports). filename: vendorThe vendor is the secondary file ($file1). query: name=vendor.name in $fileThe query needs to match the value of the name field in the vendor file with the vendor.name field in the problem file. calculation expressionMoves the fields called Post Address and Phone from the secondary file ($file1) into variable called $address and $phone, which are fields defined on the detail form of the report. calculation expression $address=address in $file1 $phone=phone in $file1
Validation
To validate that a field entry in a record is a valid value that exists in another file: Additional File Queries Field Values:
filename query
model
add true
model.name=model in $file
update true
Required Query? true (all records)
Required Field Name model
Error Message Model is not a valid model in the model file - please re-enter.
16-33
Explanation Add To be performed before adding record. Update To be performed before updating record. Filename The secondary file query will access the model file. Required Field Name The validation only occurs if the model field is not NULL. Query The model.name in the model file must match the model field in the primary file. Required Query? If the model field is not NULL, it must match a model.name value in the model file. If not, the primary file record will not add or update. Error Message This is the message the user will receive if attempted match is not found. Note: The same rules that apply to queries and ServiceCenter performance should be applied here. Selections performed on secondary files should use fully-keyed queries.
16-34
Security
To access the Security process of the Format Control record, select Privileges from the Options menu or click Privileges. There is only one form associated with Security. The Security process of the Format Control record is used to control which options (System Tray buttons) will be available to the user. All the options in this process of the Format Control record are boolean. If they evaluate to true, the options will be available to all users. If they evaluate to false, the option will not be offered to any user. Expressions can also be used in all Security fields to make the options available to users based on their capabilities as defined in their Operator Records or based on values in the data at runtime. Refer to the Expressions in Boolean (Logical) Fields earlier in this chapter. Note: Format Control Security options are not available for Incident Management, Change Management, Financial Management, and the Device Inventory portion of Inventory and Configuration Management. These applications have their own security written into the applications. Note: In ServiceCenter versions before 4.0, users with the SysAdmin capability word in their Operator Record had access to all database options without regard to values in these fields. Starting with ServiceCenter 4.0, SysAdmin users are controlled by Format Control privileges just as other operators are. To revert to the pre-4.0 blanket
16-35
SysAdmin privileges, SysAdmin users can click Administration Mode from the initial Database Manager screen..
Figure 16-12. Security Process: Standard Tab
Fields
Fields on the Standard Tab
Add Controls a users ability to add a record to the database. This applies to Add and Add/Retain. The default value is true.
Update Controls a users ability to update a record. The default value is true. Delete Controls a users ability to Delete a record. The default value is true. Find Determines if the Find button will be displayed, allowing the user to link to another file and view the data within a desired record. The default value is true. Fill Determines if the Fill button will be displayed, allowing the user to link to another file and extract data from within a desired record to be placed in the current record. The default value is true. A Link record must be set up for the Find and Fill options to work correctly. If a link record is not set up, the Find and Fill buttons will not be displayed. Print Determines whether or not the Print option (mass and record level) appears in the Options menu of a file opened in Database Manger. The default value is false. Access From Db Mgr Determines whether or not the user can access the Database Manager using the form to which the Format Control record is attached. If this field evaluates to false, users will be denied access to the database using this form. The default value is true. Users who are denied access will see the error message: This file CANNOT be accessed by the DB Mgr. due to formatctrl restrictions. Query Window Determines whether or not the user is allowed to open the Advanced Search Window. (Refer to the Database Manager documentation for information on this option.) The default value is false. Count Records Determines whether or not the Count Records button appears in the System Tray of the QBE list. The default value is true.
16-37
Validity Lookup Determines whether or not the Validity Lookup option appears in the Options menu of a blank form in Database Manager. The default value is true. Note: If no Views are defined for a particular form, the Views button will not be enabled, regardless of privilege. Views Determines whether or not the Views button appears in the System Tray providing access to alternate QBE forms. These are the forms defined in the Views process of Format Control. The default is true. Edit Array Determines the users ability to edit array structures. The default value is true. Note: Refer to the Database Manager documentation for a detailed explanation of these database operations
16-38
Figure 16-13. Security Process: Advanced Tab
Fields on the Advanced Tab

Load Determines the users ability to load data from an external file into the current file. The default value is false. Unload
16-39
Controls a users ability to Unload records to an external file. The default value is true. Mass Add Determines whether or not users have access to the Mass Add feature. The Add option appears in the Options menu of a QBE list. The default value is false. Mass Update Determines whether or not users have access to the Mass Update feature. The Update option appears in the Options menu of a QBE list. The default value is false. Complex Update Determines whether or not the Complex Update button appears in the System Tray during a Mass Update procedure. The default value is false. Mass Delete Determines whether or not the Delete option appears in the Options menu of a QBE list. The default value is false. Reset Determines if the Reset option appears in the Options menu.
Warning! A reset deletes ALL records from the current database file. Make this option unavailable to most users. The best practice is to set the value of the field to false and change it to true only when you need to delete all records from a file. The default value is false.
Regen Determines if the Regen option appears in the Options menu.
Warning! A regen will rebuild all indexes for every record in the current database file. All users will be locked out of this file while the regen is executing. If the regen is stopped before completion, records remaining to be processed will not be available to the users. The best practice is to set the value of the field to false and change it to true only when you need to regen a file. The default value is false.
16-40
Subroutines
Select Subroutines from the Options menu to display the Subroutines form. The Subroutines process allows you to call subroutines that can do anything available through RAD. The subroutine can be run at add, update, delete, and display/print time, either before or after the process is performed.
Figure 16-14. SubroutinesShort Form
16-41
Fields
Add, Update, Delete, Display These are Boolean fields that control Format Control processing. Processes evaluating to true apply Format Control before completing the specified operation. For example, when a user clicks Save, and before the record updates, Format Control executes every section or expression where the Update field evaluates to true. Before Determines whether the subroutine will be performed before or after the specific add, update, delete, or display operation. The default is false (blank), meaning the subroutine will be performed after the specified operation. In most cases, you should change this to true. Application Name The name of the RAD application to be executed when the specified operation is performed. This must be an existing application. Execution Error Message This message will be displayed if there is an error executing the application.
16-42
Figure 16-15. SubroutinesLong Form
Parameters
Name List The names of the parameters used to pass data to the subroutine application if necessary. The name must be a valid Peregrine defined parameter input field name. Refer to Chapter 6: RAD Functions Reference in the RAD User Guide for a list of these parameter names and their uses. For example: record (type of record)
16-43
Value List The names of the fields or values to be passed to the subroutine application. The type of the field must match the type of the parameter defined in the Name field. For example: $file (to pass the whole record to the subroutine)
Examples
Fingerprinting
Fingerprinting in Format Control allows a System Administrator to monitor the activity of a specific file. An application (fingerprint) called through Subroutines automatically records the names of users adding or updating records of fingerprinted files and the time each action is performed. A separate form, made available in the Views process, displays this information on demand. (Refer to the discussion of Views below.) Fingerprinting is set up in four steps: Edit the dbdict. Create a form. Set up an Alternate View of the form created. Set up a Subroutine call of the fingerprint application. Note: This example demonstrates how two Format Control processes can work together Edit the dbdict In order for the fingerprint field of the secondary file to be populated with data from the contacts file, fingerprint must appear as an array field of data type character in the dbdict record for the contacts file. 1. Select the Toolkit tab in the Home menu. 2. Click on the Database Dictionary button. 3. Enter contacts in the File Name field of the Database Dictionary dialogue box. 4. Press Enter or click on the Search button.
16-44
5. The dbdict record for the contacts file is displayed.
Figure 16-16. Contacts Database Record
6. Place the cursor in the descriptor field of the dbdict. 7. Click on the New button.
16-45
8. Enter fingerprint in the Name field of the edit box and select array from the dropdown list.
9. Click on the OK button. 10. Enter fingerprint in the Name field of the edit box and select character from the dropdown list
11. Click on the OK button. 12. Exit the Database Dictionary. Create a Form Create a secondary form called show.fingerprint that will display the update data from the contacts file. This form will be referenced in the Views process of the Format Control record for the contacts file. 1. Select the Toolkit tab in the Home menu. 2. Click on the Forms Designer button. 3. Enter show.fingerprint in the Form field of the Forms Designer dialogue box. 4. Click on the New button. 5. Create a form consisting of a single Text field with the following values:
16-46
Note: Refer to the Forms Designer documentation for details on creating forms. Property Input X Y Height Width Array Length Value fingerprint 2 2 2 56 10
6. Select the Label tool and name the field Last Updated. 7. Your new form will look like this:
Figure 16-17. The show.fingerprint Form
8. Click on the OK button to save your form. 9. Select Create File from the Options menu. 10. Enter fingerprint as the filename for your form in the prompt box.
11. Click on the OK button to create the file. 12. Exit Forms Designer. Set up an Alternate View in the Views Process 1. Click the Tools button in the Utilities tab. 2. Click on the Format Control button in the Tools menu. 3. Enter contacts in the Name field of the Format Control Initializations form. 4. Press Enter or click on the Search button. 5. The Initializations form is displayed.
Figure 16-18. Initializations Form of Format Control
6. Select Views from the Options menu or by clicking the Views button. Note: For a complete discussion of the Views process, refer to Views on page 16-62.
7. Enter the following data in the Alternate Views structure of the Views form: Display Format Name show.fingerprint contacts Condition index("SysAdmin",$lo.ucapex)>0 true
The Condition expression for the show.fingerprint form restricts viewing privileges to users with System Administrator capabilities only.
Figure 16-19. Using the Views Process for Fingerprinting
8. Click on the OK button. Set Up a Subroutines Call Set up a Subroutines call to the fingerprint application in which Format Control is applied to the contacts file before the record is added to or updated in the database.
1. Select Subroutines from the Options menu or by clicking the Subroutines button. 2. Select Show Expanded Form from the Options menu. 3. Enter the following data in the Subroutines form: Application Name fingerprint Parameters: Name record index string1 Value $file val("10", 1) Updated Add true Update true Before true
4. Your Subroutines form will look like this:
Figure 16-20. Fingerprint Call from Subroutines
16-50
5. Click on the OK button. Update the contacts File and Check Fingerprinting The parameters you have defined will display the names and dates of the last ten updates to the current contacts record, as made and viewed through the contacts form. Appended to the update information is a one word description of the action recorded, in this case Updated. Every time the Save button is clicked while viewing a contacts record via the contacts form, an additional entry to the show.fingerprint record array is added.
Important: You must be logged in as System Administrator in order to display the show.fingerprint form, and you must be viewing contacts records using the contacts form.
1. Select the Toolkit tab in the Home menu. 2. Click on the Database Manager button. 3. Enter contacts in the Form field of the Database Manager dialogue box. 4. Press Enter or click on the Search button. 5. Select contacts from the QBE list. 6. A blank contacts record is displayed. 7. Click on the Search button. 8. A QBE list of contacts in your database is displayed. 9. Click on any contact name to display the contacts record. 10. Update any field. 11. Click on the Save button.
16-51
12. Click on the Views button to display a QBE list of the forms you have made available in the Alternate Views structure of the Views process.
Figure 16-21. Views QBE List
13. Select show.fingerprint to display the fingerprinting form you created.
Figure 16-22. Fingerprint Record
14. Scroll down the list to view earlier updates to the current Contact record. 15. Click on the Views button to display the Views QBE list. 16. Select contacts to return to the Contact record.
16-52
Additional Options
Select Additional Options from the Options menu, or click the Addl Options button, to display the Additional Options form. Additional Options designates unique Options menu options (and corresponding Fkeys) to perform additional RAD functions without actual RAD modifications. The Additional Options process layout is similar to that of the Menu file (where options on a menu are defined) and performs in the same fashion. Buttons are defined to run RAD applications (like database) from within another application. Once the application is finished running, the user is returned to the original application and form. Settings within the Additional Options process can restrict access to a browse only mode or allow data input, depending upon a users system rights. Note: Additional Options are designed for use with the Database Manager only. Also, the ServiceCenter Document Engine and Display application are newer tools that provide similar functionality to Format Control Additional Options. They are generally preferable to Format Control Additional Options. However, Additional Options are still available, primarily because of carryover usage from previous ServiceCenter versions. See The Document Engine on page 1-1 and Display Application on page 13-1 of System Tailoring, Volume 2 for more information.
16-53
Figure 16-23. Additional OptionsShort Form
Database files with attached Format Control records in which Additional Options have been designated, display extra Options menu selections corresponding to each defined Additional Option. When defining Additional Options, you can: name another form to appear when the option is selected continue to view the form with the attached Format Control record In either case, the System Tray buttons are replaced with buttons appropriate to the application launched via the Additional Option and the corresponding Fkeys are activated. Users move between applications or files with a single click. After activating an Additional Option, the related application or file appears with its normal Service Tray buttons, e.g., allowing users to query for records and save updates.
16-54
Figure 16-24. Additional OptionsLong Form
Fields
Name The name of the current Format Control record appears here. Form To Display Name an additional form you want displayed when User Options is selected. This form must exist in the form file. If this field is left blank, the original form continues to display.
16-55
Allow Input Select this feature to allow the user to edit the records called by the Additional Options process. Deselect this checkbox if you want the user to have browseonly capabilities when User Options is selected from the Options menu. The fields of a record open only for browsing appear gray, and cannot be modified. Use As Master Select this feature to set the Additional Options buttons as the default buttons for this file. Whenever a user opens a record from this form, the control buttons and Fkeys defined in the Format Control Additional Options appear in the System Tray. Allow Edit This field determines whether the user will be given the edit record function (F2), which allows an edit of the record. Records are not initially displayed in the edit mode. To modify the record, the user must click on the Edit button (or press F2). This is similar to the Edit Report option in the Report Writer Utility. Option # Assign ID numbers to the option buttons in this field. Valid numbers are from 112, excluding 3 and 6. (Three is reserved for Logout and 6 identifies the more function in Text mode.) Condition For Option The value in this field determines whether or not this button/Fkey will be available to the user. This field can evaluate to true, false, or a qualifying expression. If the value is true, the button will be displayed to all users. Sample expression: index(OCMO, $lo.ucapex)>0 In this example, the capability word of OCMO (OCM Order Applications) would have to appear in the Execute Capabilities array of the users Operator Record and be a valid entry in the Capability File. Users with this capability would have access to the attached option button. Command Enter the description of the buttons function in the Command field. This label will appear on the button in the Service Tray.
16-56
For example: Option# 1 Command Location
This button/Fkey accesses the location file. Description Enter a plain text description of the options function in this field. The user will not see this description; it is for administrative reference only. Application Name the application to be executed if the operator selects this option. Comments Brief comment about the option being defined. This field is for reference only. Error Message Enter the message to be displayed in the Status Tray if an error occurs when executing this application. Reset On Return If the $file variable is modified in the called application, do you wish to keep the changes or reset it back to its original state before calling the other application? Since the passed variables are on the parameter panels (and thus are local variables), the variable will contain the value it had in the called application if this function evaluates to true. For example: If the value of a field in $file (the current record) was true before being passed to the application, and upon return to the Format Control record it has a value of false, the field will retain the value of false if the reset on return function were set to false. Options set to true will exit to the Home menu rather than returning the user to the form specified in the Format to Display field. Name Enter the name of the parameter used to pass data to the application. For example: name name
16-57
Value Enter the name of the field, value or form to be passed to the application. For example: value location The database application would be called using location (value) for the name (parameter) of the form to be used to display.
Example
A user adding or updating a Contacts file might want the option of viewing the Location or Clients file without leaving the current record. The normal procedure is to access each file separately through the Database Manager QBE list. To save time, the System Administrator can attach a Format Control record to the contacts file establishing Additional Options functions. The user can now go directly to secondary files in any sequence and return immediately to the contacts file or to any other form designated in the Form to Display field. We will create an Additional Options Format Control record for the user.contacts form that will provide button access to the Location file and the Clients file.
Opening Prompt Form

If the user has no need to return to the contacts file record after initiating the Additional Options process, a custom prompt form containing instructions and information can be used. This form is not interactive and serves as a center point for moving through the files defined in Additional Options. Create the form using Forms Designer, and enter the name of the form in the Form to Display field in the Additional Options form. Remember: If you leave this field blank, all option files will exit to the original file. (Refer to the Forms Designer documentation for details on creating forms.)
16-58
Figure 16-25. Sample Additional Options Prompt Box
Note: Any ServiceCenter form can be designated in the Form to Display field of Additional Options. Updating display objects such as charts or marquee can be included on your form.
Designate Files to Be Called

Use the following values in the Additional Options form to designate the files to be called (See Figure 16-24):
Option # 1 2 Condition true true Command Location Clients Application database database Reset on Return false false Names name name Values location company.g
Error Message Cannot display requested form. Form must already exist. Form to Display Leave this field blank. Note: The name of the parameter is name because the type of parameter to be passed is character. The value to be passed in this case is the name of the form used to view the file.
User Interaction
1. Start the Database Manager and click the Administration Mode checkbox. Note: You must be in Adminstration mode to use the user.contacts form, as required for this example.
2. Open the contacts file in Database Manager by entering user.contacts in the Form field. 3. A blank user.contacts form is displayed. 4. Click on the Search button 5. Select a Contact Name from the QBE list. 6. Press Enter. 7. A complete data record is displayed. 8. Select User Options from the Options menu. Note: This option only appears in the Options menu of forms if there is an associated Format Control record in which Additional Options have been specified. 9. If you have named a form in the Format to Display field of the Additional Options process, that form will appear. (See Figure 16-25) If you have left the field blank, the Contacts record is displayed. 10. A new set of System Tray buttons appear.
11. Click on the Location button to display a blank Location record. 12. Click on the Back button to return to the primary (contacts) file. 13. Click on the Clients button to display a blank Clients record.
16-60
Figure 16-26. Blank Clients Record
14. Click on the Back button to return to the primary (contacts) file. 15. Click on the directional buttons to move forward and backward through the primary file records.
This will take you out of the Additional Options mode. To return, select User Options from the Options menu again. 16. Click on the more button (or press F6) to restore the normal tray buttons. 17. Click on the menu button (or press F12) to return to the Home menu. 18. Click on the Exit button from the primary file to exit the Additional Options settings and return to the QBE list
16-61
Views
The Views process allows a System Administrator to create and present alternate views of the database to different users based on their system capabilities. You can create several QBE and display forms that present different information from the same file. These forms can be selected whenever you view a QBE list or record by selecting the Views button. To enable the Views process, the appropriate array in the Format Control record must contain one or more form names, and the corresponding condition must evaluate to true. When a QBE list is displayed in Database Manager, the Format Control record for the file is used. Multiple QBE forms can be used to create quick data listings, without the requirement of generating a report. Refer to Database Manager in this volume for more information about QBE lists. To access the Views process, select Views from the Options menu of the Format Control Main Information form.
Figure 16-27. Views
16-62
Note: The short and long versions of this form are the same.
Fields
QBE Format Name The name of a QBE form. Note: It is advisable to enter the name of the default QBE form, <filename>.qbe, with a Condition of true to allow the user to return to the default list. Comment A brief comment about the use of this form. This field is for reference only. Condition A boolean statement which, if evaluated as true at run time, makes the named form available for viewing. Note: If a form defined in the QBE Format Name field does not exist when it is requested for display, the default <filename>.qbe format will be used. Display Format Name The name of an alternate form. Condition (Display) A boolean statement which, if evaluated as true at run time, makes the named form available for viewing.
Example
We will create an alternate QBE form for the operator file that displays the operators name, system capabilities, password, and last login time. The new form will be available to System Administrators only and will be attached to the operator file through the Views process of Format Control. Note: QBE Views are only active when the Record List option is turned off. Therefore, before starting this exercise, go to the ServiceCenter Views menu at the top of the overall session window and uncheck the Record List option. For an example of setting up alternate form Views (rather than alternate QBE list form views), refer to the Examples on page 16-44.
16-63
Create a New QBE Form An easy way to create a new QBE form is to copy and rename the default form, then change the input values, labels and any necessary dimensions. 1. Select the Toolkit tab in the Home menu. 2. Click on the Forms Designer button. 3. Enter operator.capability in the Name field of the Forms Designer dialogue box 4. Click on the New button. Form name: operator.capability. Column Captions Login Name Capabilities Password Last Login Input values name cap.exec password last.login
16-64
Figure 16-28. Custom QBE Form
Important: To create Label Boxes with the Label tool, you must define an input value and leave the Caption property blank. Refer to the Forms Designer documentation for details on creating forms.
5. Click on the OK button to save your new form. 6. Select Format Control from the Options menu. 7. A prompt will ask if you want to save your changes.
16-65
8. Click on the Yes button. You will see a Format Control record with operator.capability in the name field.
Figure 16-29. Format Control Record for operator.capability Form
9. Click on the New button to add the new record to the database. 10. Select Privileges from the Options menu or by clicking the Privileges button. 11. Enter index("SysAdmin", $lo.ucapex)>0 in the Access from DB Mgr and Views fields.
16-66
This Condition expression restricts viewing privileges to users with System Administrator capabilities only.
Figure 16-30. Establishing Security for the operator.capability Form
12. Click on the OK button. Name Your Form in the Views Process You must attach your new form to the Format Control record for the operator file in order for it to be available to your users. 1. Click the Tools button in the Utilities tab. 2. Click on the Format Control button in the Tools menu. 3. Enter operator in the Name field of the blank Format Control Initializations form. 4. Click on the Search button
16-67
5. Select operator from the QBE list displayed. 6. The Format Control record for the operator file is displayed. 7. Select Views from the Options menu. 8. Enter the following values in the QBE Formats structure: QBE Format Name operator.capability operator.qbe Condition index("SysAdmin", $lo.ucapex)>0 true
Figure 16-31. Views Process for operator File
9. Select Privileges from the Options menu. 10. Make certain that index("SysAdmin", $lo.ucapex)>0 is entered in the Access from DB Mgr and Views fields.
16-68
The Condition expression for the operator form restricts viewing privileges to users with System Administrator capabilities only.
Figure 16-32. Restricting Access in Security Process
11. Click on the OK button.
16-69
Open an Operator Record Note: QBE Views are only active when the Record List option is turned off. Therefore, after logging on as a System Administrator, but before accessing the operator file, go to the ServiceCenter Views menu at the top of the overall session window and uncheck the Record List option. Login as a System Administrator and open the operator file. When you query the database for a list of operators, a Views button will give you access to the new QBE form, operator.capability. Use the Views button again to switch back to the default QBE form (operator.qbe). 1. Select the Utilities tab in the Home menu. 2. Click on the Administration button. 3. Click on the Operators button. 4. A blank Operator record is displayed. 5. Click on the Search button to display the default QBE list (operator.qbe)
Figure 16-33. Default QBE List
16-70
6. Click on the Views button to display the available QBE list choices.
Figure 16-34. Views QBE List
7. Select operator.capability from the list
Figure 16-35. Custom QBE List Displayed
16-71
8. Click on the Views button again to switch back to the default view. Note: You may create several QBE forms for a single file, each with different display conditions, depending upon the views your users need to see.
16-72
Chapter 17 Array Maintenance

Two types of arrays exist within ServiceCenter: simple arrays, consisting of fields of similar data types; and arrayed structures, composed of related fields of similar or dissimilar data types. A series of applications exists in ServiceCenter that can be called from the Additional Options process of Format Control to perform various maintenance functions on arrayed structures. A single application, called from the Subroutines process, allows the user to sort simple arrays automatically when adding or updating records.
Arrayed Structures
The arrayed structure maintenance functions (copy, move, delete, insert) are similar to those used in the array editor found in the Expand Array option in the Options menu. However, in Format Control, these functions act against the entire arrayed structure element, not against a single field within the structure. Figure 17-1 shows an arrayed structure. The most significant difference between the array editor and the arrayed structure editor is that the array editor redisplays the field in question in an expanded, dynamic array field. This does not occur with arrayed structures. The current form displayed when starting the function is the same one displayed during execution. The routines that perform these functions are available collectively and individually to any RAD routine or Format Control Additional Options definition. The following general rules apply to arrayed structure maintenance: None of the routines perform update functions to the database. In order to save the changes, you must select the appropriate update function within the application that called the maintenance functions. The applications are cursor dependent. For example, the insert function inserts a blank element at the cursor position within the arrayed structure. If the cursor is placed in any field within an element of the arrayed structure, the function is performed against that entire element. If the functions are executed against a non-arrayed structure field, the procedure normally fails and either issues an invalid data-type message or produces unpredictable results.
Array Maintenance 17-1
Structure
Figure 17-1. Custom Form Illustrating Arrayed Structures
The Arrayed Structure maintenance applications perform tasks such as moving, copying, deleting or sorting lines in arrayed structures. They are used with the Additional Options process to define special button features for files opened in Database Manager. Users working with forms containing arrayed structures will find these options useful in editing files. The name of each application, its basic function, and its available parameters are defined. To call these applications from Format Control, refer to Additional Options on page 16-53 for a detailed explanation of how to define Additional Options and how to pass data to these subroutines. Users should have a thorough knowledge of Forms Designer and the use of subformats in the creation of arrayed structures. For more information, refer to the Forms Designer documentation. Note: Under normal circumstances, the application as.options is called. However, you can call each of the other applications as needed. RAD users should follow normal subroutine call procedures to execute these applications. (Please refer to the RAD User Guide).
17-2
as.options
The as.options application displays all available arrayed structure options on one rio (Record Display/Input) Command panel. Note: Use of this application in arrayed structure maintenance provides all the controls needed to copy, insert, delete and move fields. It is not necessary to run as.copy, as.move, as.insert, and as.delete in conjunction with this application.
Parameters
file The file variable currently being edited. This is always $file when called from Format Control. name The name of the current form when the arrayed structure maintenance applications are displayed. If left blank, the default is the result of executing the function current.format(). Under normal circumstances, you do not pass data to this parameter. However, you could pass the name of a special form that contains an expanded version of the arrayed structure. cond.input A boolean field that allows the user to edit the data record when the arrayed structure maintenance options are displayed. The default is true. Note: When calling the application from Format Control, the value must be passed as a data type of 4 (logical) by using the syntax: val("false", 4) index The number of lines in the subformat that displays the arrayed structure. For instance, if the arrayed structure subformat has data on lines 1 and 2, then 2 should be passed to this parameter. The default is 1. Note: This is NOT the window size that displays the arrayed structure. Also note that when calling the application from Format Control, the value must be passed as a number by using the syntax: val("n", 1) where n = the number of lines in the subformat, and 1 indicates a data type of number.
Array Maintenance
17-3
The results of the maintenance routines are unpredictable if this number does not correctly reflect the number of data lines in the subformat.
Example
Create the Format Control record that attaches the as.options application to the service form. 1. Click the Tools button in the Utilities tab in the administrators home menu. 2. Click on the Format Control button in the Tools menu. 3. Type service in the Name field of the blank Format Control record. 4. Press Enter. 5. If a Format Control record does not already exist for service, click on the New button to create one. (See Adding a Record on page 15-3 for information about adding records.) 6. Select Additional Options from the Options menu. Note: Refer to Format Control Processes on page 16-1, for details on Additional Options. 7. Enter the following values in the fields of the Additional Options process form:..
Option # 2 Condition true Desc Options Application as.options Reset on Return true Names file name Values $file service
17-4
8. In addition, enter Could not execute into the Message field. The record appears as follows:
Figure 17-2. Format Control Record for service Form
9. Click on the OK button. 10. Exit Format Control. Test the option you have defined for the service form. 1. Select the Toolkit tab in the Home menu. 2. Click on the Database Manager button. 3. Enter service in the Form field of the Database Manager dialogue box. 4. Press Enter or click on the Search button. 5. Select service from the QBE list. 6. A blank Service Agreement form is displayed. 7. Click on the Search button
Array Maintenance
17-5
8. Select a record from the QBE list. For this example, we have chosen ibm santa fe Service Agreement # 123456.
17-6
9. The IBM Santa Fe Service Agreement record is displayed.
Figure 17-3. Service Agreement with Normal Button Options
10. Enter data in blank fields so that the records for all three devices are complete. 11. Select Options from the Options menu. 12. The System Tray in the service form displays the buttons associated with the as.options subroutine.
The Insert button inserts a blank line in an arrayed structure above the cursor position. The Delete button deletes the line in which the cursor is placed. The Copy button copies the entry from the line selected by the cursor. The original element is left in place when the copy is inserted into the arrayed structure. The Move button copies the entry from the line selected by the cursor. The original element is deleted when the copy is inserted into the arrayed structure.
17-7
Array Maintenance
The following System Tray buttons are displayed for completing the copy and move functions:
The Insert button inserts the copied element into the arrayed structure above the line selected by the cursor. The Replace button replaces the element selected by the cursor with the copied element.
13. Click on the End button to restore the normal tray buttons. 14. Click on OK or Save to save any changes you have made to the Service Agreement record.
Important: You must use the OK or Save button to update your record. Clicking on the Enter button will NOT save any changes you have made.
as.copy
The as.copy application copies an element from one position to another, leaving the original in place.This application is used in conjunction with as.delete, as.insert, and as.move.
Parameters
file The file variable currently being edited. This is always $file when called from Format Control. name Under normal circumstances, data is not passed to this parameter. The default is the result of executing the function cursor.field.name(1). The application as.get.name is then executed against this result. Note: You can pass the name of a specific arrayed structure. If the data passed to this parameter does not contain any commas, it is considered to be an arrayed structure name. If a comma is found, the application as.get.name is executed against the data.
17-8
index The number of lines (height property) in the subformat that displays the arrayed structure. For instance, if the arrayed structure subformat has data on lines 1 and 2, then 2 should be passed to this parameter. The default is 1. Note: This is NOT the window size that displays the arrayed structure. When calling the as.copy application from Format Control, the value must be passed as a number by using the syntax: val("n", 1) where n = the number of lines in the subformat, and 1 indicates a data type of number. The results of the maintenance routines are unpredictable if this number does not correctly reflect the number of data lines in the subformat. For more information, refer to the System Language Guide.
as.delete
The as.delete application deletes an element from an array. This application is used in conjunction with as.copy, as.insert, and as.move.
Parameters
file The file variable currently being edited. This is always $file when called from Format Control. name Under normal circumstances, data is not passed to this parameter. The default is the result of executing the function cursor.field.name(1). The application as.get.name is then executed against this result. Note: You can pass the name of a specific arrayed structure. If the data passed to this parameter does not contain any commas, it is considered to be an arrayed structure name. If a comma is found, the application as.get.name is executed against the data. index The number of lines (height property) in the subformat that displays the arrayed structure. For instance, if the arrayed structure subformat has data on lines 1 and 2, then 2 should be passed to this parameter. The default is 1.
Note: This is NOT the window size that displays the arrayed structure. When calling the as.copy application from Format Control, the value must be passed as a number by using the syntax: val("n", 1) where n = the number of lines in the subformat, and 1 indicates a data type of number. The results of the maintenance routines are unpredictable if this number does not correctly reflect the number of data lines in the subformat.
as.insert
The as.insert application inserts a NULL element. This application is used in conjunction with as.copy, as.delete, and as.move.
Parameters
file The file variable currently being edited. This is always $file when called from Format Control. name Under normal circumstances, data is not passed to this parameter. The default is the result of executing the function cursor.field.name(1). The application as.get.name is then executed against this result. Note: You can pass the name of a specific arrayed structure. If the data passed to this parameter does not contain any commas, it is considered to be an arrayed structure name. If a comma is found, the application as.get.name is executed against the data. index The number of lines (height property) in the subformat that displays the arrayed structure. For instance, if the arrayed structure subformat has data on lines 1 and 2, then 2 should be passed to this parameter. The default is 1. Note: This is NOT the window size that displays the arrayed structure. When calling the as.copy application from Format Control, the value must be passed as a number by using the syntax: val("n", 1) where n = the number of lines in the subformat, and 1 indicates a data type of number.
17-10
The results of the maintenance routines are unpredictable if this number does not correctly reflect the number of data lines in the subformat.
as.move
The as.move application moves an element from one position in an array to another by creating a copy and then deleting the original. This application is used in conjunction with as.copy, as.insert, and as.delete.
Parameters
file The file variable currently being edited. This is always $file when called from Format Control. name Under normal circumstances, data is not passed to this parameter. The default is the result of executing the function cursor.field.name(1). The application as.get.name is then executed against this result. Note: You can pass the name of a specific arrayed structure. If the data passed to this parameter does not contain any commas, it is considered to be an arrayed structure name. If a comma is found, the application as.get.name is executed against the data. index The number of lines (height property) in the subformat that displays the arrayed structure. For instance, if the arrayed structure subformat has data on lines 1 and 2, then 2 should be passed to this parameter. The default is 1. Note: This is NOT the window size that displays the arrayed structure. When calling the as.copy application from Format Control, the value must be passed as a number by using the syntax: val("n", 1) where n = the number of lines in the subformat, and 1 indicates a data type of number. The results of the maintenance routines are unpredictable if this number does not correctly reflect the number of data lines in the subformat.
Array Maintenance
17-11
Example
Create a Format Control Record
1. Click the Tools button in the Utilities tab. 2. Click on the Format Control button in the Tools menu. 3. Type service in the Name field of the blank Format Control record. 4. Press Enter. 5. If a Format Control record does not already exist for service, click on the New button to create one. (See Adding a Record on page 15-3 for information about adding records.) 6. Select Additional Options from the Options menu. Note: Refer to Format Control Processes on page 16-1, for details on Additional Options. 7. Enter the following values in the fields of the Additional Options process form:.
Option # 1 2 4 5 Condition true true true true Desc Copy Delete Insert Move Application as.copy as.delete as.insert as.move Reset on Return true true true true Names file index file index file index file index Values $file val("18", 1) $file val("18", 1) $file val("18", 1) $file val("18", 1)
Error Message for each subroutine call above: Could not execute.
17-12
8. The record appears as follows:
Figure 17-4. Format Control Record for service Form
9. Click on the OK button. 10. Exit Format Control.
Test the Form

Test the effects of the Format Control options you have defined: 1. Select the Toolkit tab in the Home menu. 2. Click on the Database Manager button. 3. Enter service in the Form field of the Database Manager dialogue box. 4. Press Enter or click on the Search button. 5. Select service from the QBE list.
Array Maintenance
17-13
6. A blank Service Agreement form is displayed. 7. Click on the Search button 8. Select ibm santa fe(Service Agreement # 123456) from the QBE list. 9. The IBM Santa Fe Service Agreement record is displayed.
10. Enter data in blank fields so that the records for all devices are complete. 11. Position the cursor within the arrayed structure to identify an insertion, deletion, move or copy point. 12. From the Options menu, select any of the standard options or any of the four new options defined in the Format Control record. The Insert option inserts a blank line in an arrayed structure above the cursor position. The Delete option deletes the line in which the cursor is placed. The Copy option copies the entry from the line selected by the cursor. The original element is left in place.
17-14
The Move option copies the entry from the line selected by the cursor. The original element is deleted after the copy is inserted into the arrayed structure. The following System Tray buttons are displayed for completing the copy and move functions:
The Insert button inserts the copied element into the arrayed structure above the line selected by the cursor. The Replace button replaces the element selected by the cursor with the copied element.
13. Click on OK or Save to save any changes you have made to the Service Agreement record. Note: You must use the Save button to update your record. Clicking on the Enter button will NOT save any changes you have made.
as.get.name
The as.get.name application returns the structure name of the arrayed structure in which the cursor is located.
Parameters
name The structure name of the arrayed structure. The default is the result of executing the function cursor.field.name(1). prompt The returned structure name of the arrayed structure. This is a data return parameter. Data should not be passed to it.
as.sort
The as.sort application sorts an arrayed structures based on the contents of a particular field within the arrayed structure. This application supports major, intermediate, and minor sorting by allowing you to sort multiple arrayed structure fields with one pass of the application.
You can also specify an ascending or descending sort order. You must call this application from Format Control or RAD on an asneeded basis.
Parameters
file The file variable currently being edited. This is always $file when called from Format Control. name The name of the arrayed structure you wish to sort. This name corresponds to the input field of the subformat object in the form to which the Format Control record is attached. (For information on creating subformats, refer to the Forms Designer documentation.) Note: If the data passed to this parameter does not contain any commas, it is considered to be an arrayed structure name. If a comma is found, the application as.get.name is executed against the data. numbers An array that specifies the field numbers on which to sort within the arrayed structure. This is a required field. If left NULL, the sort routine ends. The data must be passed as an array of numbers. In Format Control, you must first define a $variable in the Initializations form for the array of numbers, then pass that variable to the numbers input field in the Additional Options definition. There are three levels of sorting: major, intermediate, and minor. For example, if you pass the array {6, 1, 3}, field 6 is the major sort, field 1 is the intermediate sort, and field 3 is the minor sort.
Important: Field numbers correspond to the index numbers listed in the Database Dictionary and NOT to the sequence in which they appear on the form itself.
condition A boolean array that specifies either ascending or descending order for each field being sorted in the arrayed structure (as specified in the numbers parameter). To specify an ascending order, pass a value of true (the default). To specify a descending order, pass a value of false. Each element in this array has a direct correlation with the elements of the numbers parameter. For example, to sort the fields, 3, 1, and 6 of an arrayed structure in ascending, descending, and ascending order, the
17-16
condition parameter is {true, false, true}. In Format Control, you must first define a $variable in the Initializations screen that defines the boolean array, then pass the variable to this input field in the Additional Options definition.
Example
1. Click the Tools button in the Utilities tab. 2. Click on the Format Control button in the Tools menu. 3. Type service in the Name field of the blank Format Control record. 4. Press Enter. 5. If a Format Control record does not already exist for service, click on the New button to create one.(See Adding a Record on page 15-3 for information about adding records.) 6. Enter the following expressions in the Initialization Expressions field of the Initializations form: $numbers={4, 2, 3} $array={false, true, false} Note: You must leave a space after each comma in the expressions above.
Array Maintenance
17-17
The Warranty field (4) sorts first in descending order, the Model field (2) sorts in ascending order, and the Install field (3) sorts in descending order.
Figure 17-6. Initialization Expression for as.sort Application
7. Select Additional Options from the Options menu. Note: Refer toFormat Control Processes on page 16-1, for details on the Additional Options function. 8. A prompt box will appear asking if you want to save the changes to the Format Control record. Click on the Yes button to save your changes. 9. Select Show Expanded Form from the Options menu.
17-18
10. Enter the following values in the fields of the Additional Options process form. To enter the third and fourth parameter values, position the cursor on the first values field (where you entered the value $file) and press PgDn..
Option # 1 Condition true Command Sort Application as.sort Reset on Return true Names file numbers name condition Values $file $numbers devices.covered $array
Error Message Could not execute. Format to Display: Leave this field blank. (If left blank, the value of this field will default to the current formthe form you want to sort.) Note: The value, devices.covered, is the name of the arrayed structure to be sorted. This value must match the input value of the subformat object in the form to which the Format Control record is attached. (For more information about creating subformats, refer to the Forms Designer documentation.) 11. The record appears as follows:
Array Maintenance
17-19
Figure 17-7. Format Control Record for as.sort Application
12. Click on the OK button. 13. Exit Format Control. Test the sorting order you have defined for the service form. 1. Select the Toolkit tab in the Home menu. 2. Click on the Database Manager button. 3. Enter service in the Form field of the Database Manager dialogue box. 4. Press Enter or click on the Search button. 5. Select service from the QBE list. 6. A blank Service Agreement form is displayed. 7. Click on the Search button. 8. Select ibm santa fe (Service Agreement # 123456) from the QBE list. 9. The IBM Santa Fe Service Agreement record is displayed.
17-20
Array Maintenance
17-21
10. Enter data in blank fields so that the records for all devices are complete. 11. Place the cursor in the arrayed structure. 12. Select Sort from the Options menu to execute the sort. 13. Click on the Save button to save any changes you have made to the Service Agreement record.
Important: You must use the Save button to update your record. Clicking on the Enter button will NOT save any changes you have made.
17-22
Sorting Simple Arrays

The sort.array application is a utility called from Format Control to sort simple arrays in either ascending or descending order. Supported array data types are: number character data/time The sort.array utility is called from the Subroutines process of Format Control. (Refer to Format Control Processes on page 16-1 for information about Subroutines.) Use this utility to sort simple arrays in ascending or descending order
Example
This example has three parts: Create the form. Create a Format Control record. Create a data record.
Create a Form
Create a form called demo.sort with three simple arrays of different data types: numbers, characters, and dates. Provide a Name field for the record and create a file in the Database Dictionary called demosort. (For information about creating forms, refer to the Forms Designer documentation.) Use the following values to construct your form: Field Name Name Numbers Characters Dates Input Value name number character date
Array Maintenance
17-23
Your form should resemble the following:
Figure 17-10. Demonstration Form for sort.array Utility

Call the sort.array application from the Subroutines process of Format Control. 1. Access the Format Control Initialization form. 2. Type demo.sort in the Name field. 3. Click on the New button to create a new Format Control record for your demo form. 4. Select Subroutines from the Options menu or click the Subroutines button. 5. Select Show Expanded Form from the Options menu in the Subroutines process. 6. Enter the following values in the long form view of Subroutines:
Application Name sort.array Add true Update true Before true Error Message Could not sort the array.
17-24
Parameter values:
Names file name boolean1 Definition When calling sort.array from Format Control, always pass $file to this parameter. The name of the input field (array) in $file you wish to sort. The parameter that controls the sort order. A value of true sorts in ascending order. If you pass false, the sort order is descending. The default is true. Values $file number val ("false", 4) *
* For a detailed discussion of the val function, refer to the System Language guide. 7. The completed Subroutines record (long view) looks like Figure 17-11:
Array Maintenance
17-25
Figure 17-11. Long Version of the Subroutine Form
8. Click on the OK button to save your record.
Add Data to Your Test Form

1. Select the Toolkit tab in the Home menu. 2. Click on the Database Manager button. 3. Type demo.sort in the Form field of the Database Manager dialogue box. 4. Press Enter or click on the Search button. 5. Type sort1 in the Name field of your test form. 6. Enter data in the arrays in random order (numbers in the Numbers array, characters in the Characters array, etc.)
17-26
Figure 17-12. Test Data Record
7. Click on the Add button to add the record to the database and sort the array. Note: Since Update evaluates to true in the Format Control record for this form, you may also sort an array by clicking on the Save button.
Array Maintenance
17-27
The Numbers array is sorted in descending order.
Figure 17-13. Sorted Numbers Array
8. Repeat the process for the other arrays by changing the name parameter in the Format Control record to reflect the array being sorted. 9. Remove the boolean1 parameter, and the sort order defaults to true. The array is sorted in ascending order.
17-28
Chapter 18 Sequential Numbering for Format Control

Sequential numbering is a Subroutine process of Format Control that automatically adds identifying numbers to database records as they are created. Sequential numbering can be used for inventory control, problem tickets, or employee records, for example. Sequential numbers can be defined for appropriate fields in any data record. You may create alphanumeric strings (prefixes and suffixes) that identify records by task or item. Sequential numbering allows you to: Increment/decrement numbers in sequence. Reset values at definable intervals. Define values for increment/decrement sequence. Define the length of the number. Append prefixes and suffixes (characters) to sequential numbers. The getnumb.fc application is called from the Subroutines process of Format Control to establish the sequential numbering sequence.
Sequential Numbering for Format Control
18-1
Data Types
There are two data types of sequential numbers: Simple numbers (1, 2, 3, etc.). Complex character strings (DEV00001/WS). Note: If you wish to use the prefix and suffix capabilities of sequential numbering, the field being incremented or decremented must be defined in the Database Dictionary as type character. In all other cases, the field must be of type number.
18-2
Parameters
The following parameters are used for passing sequential numbering values to the getnumb.fc application in the Subroutines process: record The data record in which the number will be placed. The value of this parameter must be $file. name The sequential number Class (category) of the record to which the Format Control record is attached. This value appears in the Class field of the Sequential Numbering File. prompt The field in the data record in which the sequential number will appear. string1 (Optional). Defines the prefix to use. This is the identifying character string that appears before the sequential number. query (Optional). Defines the suffix to use. This is the identifying character string that appears after the sequential number. text (Optional). Defines the data type of the sequential number (number or string). The default is number. number1 (Optional). Defines the length of the sequential number. The subroutine will add as many zeroes to the number as necessary to match the required number of digits. Pass the RAD function val() to the number1 parameter. For example, a four digit number would have the value val("4", 1) where 4 is the length of the number and 1 is the data type (number). numbers,1 (Optional). Determines the reset point for the sequential number. When the value passed to the application is reached, the sequential number is reset to its starting value.
18-3
numbers,2 (Optional). Establishes a new starting value for the sequential number when the reset point has been reached. numbers,3 (Optional). Sets the increment/decrement value. For example, you may want to increment by 2, displaying only odd or even numbers. numbers,4 (Optional). Allows the user to increment or decrement the sequential number independent of the number file. Use this parameter to attach a special number to your records without updating the number file.
18-4
Simple Sequential Numbers

This example illustrates the process of setting up sequential numbering using Format Control. In the process, we will: Create a form. Create a database file. Create a Format Control record for the form. Open the number file. Add a numbered record to the database file.
Create the Form

Create a form in Forms Designer called employees that records simple employee data such as name, address, and telephone number. Be sure to include a field labeled Employee ID with an input value of employee.id.
Figure 18-1. Blank Employee Record
18-5
Create a Database File

1. After you have finished creating your form, select Create File from the Options menu in Forms Designer. 2. Enter employees as a file name in the dialogue box. 3. Click on the OK button to create the new datafile. 4. Change the Employee ID field of the employee file to a number data type. a. Select the employee.id field with the cursor. b. Click on the Edit button. c. Select number from the dropdown menu in the Type field.
Important: A data type of number is required for all simple sequential numbering.
Figure 18-2. Editing Data Types
18-6
5. The edited file appears as follows:
Figure 18-3. Create a File

1. Click the Tools button in the Utilities tab in the administrators home menu. 2. Click on the Format Control button in the Tools menu. 3. Type employees in the Name field and click on the New button. 4. Select Subroutines from the Options menu or click the Subroutines button. 5. Select Show Expanded Form from the Options menu in Subroutines.
18-7
6. Use the following values to complete the Subroutines process: (Refer to Subroutines on page 16-41, for information on Subroutines.)
Application Name getnumb.fc Add true Before true Error Message Sequential number did not process correctly!
Names record name prompt
Definition The record in which the number will be placed. In this example, the employees datafile. The name to appear in the Class field of the Number file generated by the Format Control record. The field within the record receiving the sequential number.
Values $file employees employee.id
18-8
Figure 18-4. The Long Version of the Subroutine Form
Add a Record to the Database

1. Select the Toolkit tab in the Home menu. 2. Click on the Database Manager button in the Home menu. 3. Enter employees in the Form field of the Database Manager dialogue box. 4. Press Enter or click on the Search button. 5. Add data to the blank Employee Database record.
18-9
6. Click on the Add button. The sequential number is added to the Employee ID field before the record is added to the database.
Figure 18-5. Sequentially Numbered Data Record
Number File
A Sequential Number File record is created by the Subroutines process of Format Control when the application getnumb.fc is called. Values in the number file fields are defined by the parameters passed to the application from within Subroutines. These values determine how the sequential number is displayed and what other information is contained within it. You can define number file values either directly in the number file or via parameters passed from Format Control. However, if you use the number file to change values also defined in the Format Control Subroutines process, they will be overridden by the Format Control values. To view the number file: 1. Select the Toolkit tab in the Home menu. 2. Click on the Database Manager button in the Home menu. 3. Enter number in the Form field of the Database Manager dialogue box. 4. Press Enter or click on the Search button.
5. When the blank Sequential Number File form appears, press Enter or click on the Search button to display a QBE list. 6. Select employees from the list of records. 7. The Sequential Number File for the employees file is displayed.
Figure 18-6. Number File for employees Datafile
Fields
Class The class or category of data records to which the Format Control record is attached. Last Number Displays the number of the last record in the defined sequence. Decrement? Boolean field determining whether or not the numbering sequence is decremented. If this field evaluates to true, the sequence will be decremented.
Sequential Numbering for Format Control 18-11
Description Plain text description of the file to which the Format Control record is attached. This field is for reference only. Reset Point Defines the point (number) at which the sequential number will return to its starting value. Increment/Decrement By Determines the numbering sequence. For example, you may want to increment a sequence by two, producing odd numbers only. The default is 1. Length Determines the length (number of digits) of the number. For example, a sequential number with a starting value of 1 and a length value of 5 would be displayed as 00001. Prefix Prefix to appear before the sequential number. For example, you may want to identify a device record with the prefix DEV. Suffix Suffix appended to the end of the sequential number. For example, the sequential number identifying a workstation record might be followed by / WS.
18-12
Prefixes and Suffixes

Prefixes and suffixes are used to embed information in the sequential number and provide additional levels of identification. For example, each device in the database might be described by a logical name in the form of DEV(number)/ (device type). For workstations the device type might be WS. In this case, DEV is the prefix for the sequential number and /WS is the suffix. In this example, we will add a subroutine call to the device.workstation form to assign a unique device number to all records added to the file from this form. In the process, we will: Create a Format Control record for the device.workstation form. Add a record to the device.workstation file.

1. Click the Tools button in the Utilities tab. 2. Click on the Format Control button. 3. Enter device.workstation in the Name field of the blank Format Control Initializations form. 4. Press Enter or click on the Search button. 5. Select Subroutines from the Options menu or click the Subroutines button. 6. Select Show Expanded Form from the Options menu. 7. Use the following values to complete the Subroutines process: (Refer to Subroutines on page 16-41, for information on Subroutines.)
Application Name getnumb.fc Add true Before true Error Message Sequential number did not process correctly!
Names record name
Definition The record in which the number will be placed. In this example, the device.workstation record. The sequential number class to be used.
Values $file devices
18-13
Names prompt string1 query text
Definition The field within the record receiving the sequential number. The string (prefix) to be added to the front of the sequential number when creating a new number. The string (suffix) to be added to the end of the sequential number when creating a new record. Defines the sequential number type (number or string). Since characters occur in the number, this must be string. Determines the length of the sequential number.
Values logical.name DEV /WS string
number1
val(4, 1)
The Format Control record appears as follows: .
Figure 18-7. Completed Subroutine Form
18-14
Add a Data Record

1. Select the Toolkit tab in the Home menu. 2. Click on the Database Manager button in the Home menu. 3. Enter device.workstation in the Form field of the Database Manager dialogue box. 4. Press Enter or click on the Search button. 5. Add data to the blank Workstation record.
Figure 18-8. Workstation Record
18-15
6. Click on the Add button. A complex sequential number is added to the Asset field before the record is added to the database.
Notice that the complex sequential number DEV0002/WS appears in the Asset field (logical.name). Add another record, and the sequential number will advance to DEV0003/WS.
18-16
Chapter 19 Posting
Posting is the process of copying data from a source record to a target record. The purpose of Posting is to update similar fields in other records without having to open those records to modify each field. The relationship between the two records is normally based on a value defined in one (or more) of the source record input fields. Posting is the opposite of the Fill function, which copies data from the target record to the source record. Fill 1. Starts on a source record. 2. Accesses a record in a secondary (target) file based on data in the source record (usually the contents of the input field selected by the cursor. 3. Copies (fills) data from that target record back to the source record. Posting 1. Starts on a source record 2. Accesses a record in a secondary (target) file, based on data in that record. 3. Copies (posts) data from the source to the target and then performs some action (add, update, open, etc.) on the target record. The posting process allows you to control the process in several ways: Define the target file. Select the fields to copy. Determine whether or not to prompt the user for add/update confirmation. Decide which application to invoke for the posting process. Define manual or automatic posting.
Posting
19-1
Link Records
The Posting process requires you to create a standard ServiceCenter Link record. The Link record establishes the connection between similar fields in the source and target files. When Posting, it is best to create a new Link record dedicated to the Posting process so as to avoid conflicts with Link records defining common fill relationships. For specific information on Links, refer to the Link Maintenance documentation.
Figure 19-1. Link Record
Fields
When referring to fields in the source record, use the $File file variable. To refer to fields in the target record, use the $Filet file variable.
19-2
Important: The case must match that of the sample (upper case F the rest lower case).
Name This is the name of the form from which the Posting process will be initiated. The default process is for Posting to find a Link record that matches the name of the currently displayed form. Note: When calling the Posting routine, you can override the default and define a specific Link record. Description Brief description of the function of the source form. Add Query This field defines the query that is executed against the target file in order to locate the target record. This query should be built to retrieve a unique record in the target file. If, however, more than one record is retrieved, the Posting process is completed against all records in the list. This same value is displayed on the Link line format. Field Name (SOURCE) This is the name of the input field on the form that allows the user to begin the Posting process. Note: You can define the same input field multiple times on the Link record. If more than one field in the list matches the source input field, the Posting process is completed for all fields in the list. Use existing input fields or define special input fields to invoke Posting to a particular file. For example, add the input fields called post.to.problem and post.to.change. Each of these input fields would then be defined to the Posting link record. This allows the user to place the cursor on either field and invoke the Posting process defined for that input field. Consider using special input fields for the Posting process if you define a Posting link on the same format used for find/fill and if the same source input field defines the unique target record used for find, fill and Posting. This is because the fields that are filled from a target file will probably not be the same fields that are Posted to a target file.
Posting
19-3
Format/File Name (TARGET) This is the name of the target form or target file. If this is the name of a form, data is posted to the file associated with that form. If it is not a form name, Posting attempts to post to a file with that name. Field Name (TARGET) This is the name of the input field in the target record that will be used to query for a unique record in the target file based on the contents of the Source Field input field. The Add Query field overrides this value. Comments This field is normally used for entering general comments about a particular Link line. This same value is displayed on the Link line form.
Link Line Definition File

The Link line definition file defines a single field as the reference field for the Posting routine and lists the names of other fields linked for the Posting process. When Posting is invoked, the system will compare the value for the reference field in the source file with the value for the linked field in the target file. If the values are the same, the system compares the listed fields for changes and posts the new data to the target file. The fields used for the Link line definition have the same definition/use for Posting as they do for find and fill with the following exceptions: The Source Field array lists fields in the source record and the Target Field array lists fields in the target record. You can define parameters in the Expressions field to control the Posting process flow. Refer to Posting Variables for a complete list of the variables used in this field to control Posting process. Note: Reference or manipulate input fields with the $File file variable. Any modifications made to this record variable are passed back to the calling application.
Warning! Processing statements may modify the contents of the original record.
19-4
Figure 19-2. Linking Individual Fields for Posting
Fields
Comment When Posting, this field must contain the word POST (all upper case). Query (Optional). This field contains a specific Link query that overrides the standard link query. The general rule is: target field=source field in $File
Posting
19-5
For example: target1=source1 in $File The file variable $File is used for all references to the source file in fill and find operations. QBE Format (Optional) This field contains the name of the QBE form to be used if more than one record is selected in find or fill. Expressions This field contains logical or arithmetic expressions used within Link queries. Example: $post.confirm=true This expression instructs the system to prompt the user to confirm the Posting process. Source Field (Fill To/Post From) List the fields from the source record you wish to Post to the target record. Although field names do not have to match, the position of the source fields in the array must correspond to the position of the target fields receiving the data. Target Field (Fill from/Post To) List the fields from the target record to which the data from the corresponding source fields is to be Posted. Although field names do not have to match, the position of the target fields in the array must correspond to the position of the source fields from which data is Posted.
System Tray
Edits an array selected by the cursor. Click on the Expand button to display the array window and activate the System Tray editing features.
19-6
Posting Variables
The following variables are available during the posting process and can be used to control the Posting process flow: $File The source record file variable $Filet The target record file variable $post.msg The message issued to the operator when the posting routine successfully completes. The default message is: The posting routine is complete. $post.confirm A logical field that controls whether on not the user is prompted to confirm the Posting action. The default is false. $post.confirm.fmt The name of the form used to display the target record for Posting confirmation. $post.appl The name of the RAD routine used for posting. If an application is not defined to this variable, and the $post.confirm option is true, the confirmation is a simple add or update of the target record. No other processing is performed against the record. $post.names An array that defines the names of the parameter panel input fields to which data will be passed. This field is needed only when an application is defined to the $post.appl parameter. $post.values An array that defines the values passed to the called application. There is a one-to-one relationship between this array and the $post.names array.
Posting
19-7
Posting Process Flow Automatic
Source File
Subroutines
Link Record
User Action
Add a New Record
Update an Existing Record
No
Confirm?
Yes
Yes
Confirm?
No
Data Posted to Target File
Target File Displayed
Data Posted to Target File
Post Add
Post Update
19-8
Setting up Posting via Format Control Subroutines or Additional Options

This section defines the field values required to invoke Posting through either Format Control Subroutines or Format Control Additional Option.
Figure 19-3. Setting up Manual Posting in Format Control
Fields
Application This is always post.fc. Allow Input (Additional Options only) Check the box to allow the user to modify fields and update records while Format Control is in effect.
Posting
19-9
Parameters
The following are the definitions for the parameters passed to post.fc through the name and value fields. file The file variable containing the source record for link processing. This will always be $file when calling post.fc through the Additional Options process. In most cases, the variable will be $file when calling post.fc through the Subroutine process; however, it could be $file1 (or some other file variable established by Format Control or your own RAD processing). name (Optional) The name of the link record that defines the posting rules. This defaults to the name of the currently displayed form. prompt (Optional) The source field within the posting link record. This defaults to the input field name where the cursor was located when the option was selected.
19-10
Examples
There are two types of Posting available in Format Control: Automatic posting, setup via Format Control Subroutines User-controlled posting, setup via Format Control Additional Options for use with Database Manager only. The following examples will demonstrate both types of Posting by demonstrating how to setup posting from the Change Management application and file to the contacts file.
Automatic Updates via Format Control Subroutines

Posting can be used to update any ServiceCenter file from another part of ServiceCenter. For example, new contact information from a change request can post directly to related fields in the contacts file without any user interaction. If you are opening a change request for a new contact, Posting can create a new Contact record and populate the common fields defined in the Link record. Posting from Change Management can occur when new requests are opened and when active requests are updated. In this example, cm3r.hardware is our Source Format (accessing the cm3r file) and contacts is our Target form (accessing the contacts file). Both files contain such contact information as name, phone, and department. The relationship between the two files is based on a single common fieldthe name field in this example. When Posting is initiated from a change request, the system attempts to find a Contact record in which the value of the contact.name field matches the value of the requested.by field in the change request. If a match is found, the system updates the Contact record. If no match is found (as in the case of a request from a new person), the system creates a new Contact record based on the values in the change request.
Identify Field Input Values

In order to create a Link record for Posting, you must identify the common fields in the Source and Target files. This can be accomplished from within Forms Designer by two methods: The Validate Format Option. Select individual fields in the Design mode.
Validate Format
1. Open form contacts.g in Forms Designer. 2. Select Validate Format from the Options menu. The input values of all the fields are displayed in the form.
Posting 19-11
3. Note the input values of the fields you wish to name in the Posting routine. Field Contact Name Corp Structure Company Work Phone Value contact.name corp.structure company contact.phone
Figure 19-4. Displaying Field Input Values in the Target File
Note: The input value for a Fill box is not displayed by the Validate Format option. To see values not displayed, use the method described below.
Individual Fields
1. Open cm3r.hardware in Forms Designer. 2. Click on the Design button.
19-12
3. Select a field and check the Input value in the Properties window.
Note: This method is slower than using the Validate Format option, but will display all input values, including those not shown in Fill boxes.
Important: Be certain not to alter the form when checking field input values. Click on the Cancel button to exit the Design mode without changing the form.
Create the Link Record Create a new Link record for cm3r.hardware. for the Posting process. This will avoid any conflicts involving links established in a current record for the Fill function.
1. Click the Tools button in the Utilities tab in the administrators home menu. The Tools menu is displayed. 2. Click on the Links button.
Posting 19-13
3. Enter the name of the Link record you wish to create in the Form field of the Link Manager dialogue boxin this example, cm3r.hardware.post 4. Click on the New button. 5. Enter the following values in the first line of the new Link record: Field Field Name (SOURCE) Format Name (TARGET) Field Name (TARGET) Comment Value requested.by contacts contact.name POST
Important: You must enter POST in upper case letters in the Comment field for the Posting process to work.
6. The new Link record will appear as follows:
19-14
Figure 19-5. Source File Link Record
7. Place the cursor in the requested.by line and select Select Line from the Options menu. 8. The Link line definition form is displayed. Enter the following values for the Source and Target fields: Source Field requested.by request.phone Target Field contact.name contact.phone
Posting
19-15
request.dept
corp.structure
Figure 19-6. Link Line Definition Form
9. Click on the Back button. 10. A prompt will ask if you want to save the Link record you have created. 11. Click on the Yes button to save the record.
Create the Format Control Record

Automatic Posting is defined in the Subroutines process of Format Control. The application called is post.fc. Posting takes place before the change request is added or updated in the database. 1. Click the Tools button in the Utilities tab. 2. Click on the Format Control button. 3. Type cm3r.hardware in the Name field of the Format Control Initializations form. 4. Click on the Search button. 5. If no record exists, click on the New button.
6. The Format Control record for cm3r.hardware is displayed.
Figure 19-7. Format Control Initializations Form
7. Select Subroutines from the Options menu or click the Subroutines button. 8. Select Show Expanded Form from the Options menu to display the long version of the Subroutines form. 9. Enter the following values in the first available slot: Field Application Name Comments Add Update Before
Posting
Value post.fc POST true true true

19-17
Names file name prompt Error Message
Values $file cm3r.hardware.post requested.by
Could not post to contacts file.
Figure 19-8. Format Control Subroutines Setup to Call Posting
Note: The name parameter passes the name of the Link record you created, and the prompt parameter passes the source field for the Link relationship. 10. Click on the Back button.
19-18
11. A prompt will ask if you want to save the changes to the Format Control record 12. Click on the OK button to save the record.
Open a Change Request

In order to test the Posting routine you have set up, you must open an existing hardware change request or create a new one. We will first test updating the contacts file by changing the values in the Department and Phone fields in the General tab of the change request. Then we will test creating a new Contact record by changing the Name field in the change request. 1. Click on the Change Management button in the Services tab in Home menu. 1. Click Open New Change in the Main tab of the Change Management menu. 2. Select the Hardware category for your request. 3. An initial hardware change request form is displayed. 4. Place the cursor in the Name field and click on the Fill button.
Posting
19-19
Figure 19-9. Hardware Change Request Form
19-20
5. Select a name from the QBE list of contacts. (The contact information displayed in the QBE list comes from the contacts file.)
Figure 19-10. Contact Name QBE List
6. The system populates the Change Initiator structure with information from the contacts file.
Figure 19-11. Contact Information from a Change Request
Posting
19-21
7. Change the department designation and phone number in the change request form.
8. Click on the Save button to save the request and post the data to the contacts file. 9. Place the cursor in the Name field and click on the Find button. 10. The Contact record displays, showing your changes. The departmental information is at the bottom of the Business Information tab and the phone number is in the Contact Numbers tab of the Contact record..
Figure 19-12. Updated Contact Phone Information
11. If there are problems, click on the Message button to view posting messages.
19-22
12. Open a new change request and change all the contact information including the contact name. See Figure 19-13 for an example.
Figure 19-13. Establishing a New Contact
13. Click on the Save button to save the new request and evoke the Posting process.
Posting
19-23
14. Check the contacts file by placing the cursor in the Name field and clicking on the Find button.The new contact name, phone number, and department appear in a new Contact record.
Figure 19-14. Contact Record Created from Posting Routine
15. Complete the Contact record and click on the Save button to save record to the database. 16. Click on the Back button to return to the change request record.
Manual Posting via Format Control Additional Options

In some cases, you may want to give your users the option to manually control posting. User Options for Posting data are defined in the Additional Options process of Format Control and require user interaction to complete the routine. Manual Posting is desirable whenever you do not want changes to post automatically. This is true whenever the changes may only be temporary;
19-24
typically you do not want temporary changes to update permanent records. For example, if the contact is calling from a different phone, her temporary number can be added to the change request without being posted to her contacts record. Additional Options are only available for Database Manager. To setup manual posting within other ServiceCenter modules, such as Incident Management or Change Management, setup a new Display option definition to call the post.fc application. In this example, we will re-use our posting link record from Database Manager and will define Additional Options for a hardware change request form. The user will be able to click on a button to Post updates to contact information. As in the previous example, the Source File is cm3r.hardware, and the Target File is contacts. Note: Peregrine does not recommend accessing Change Management forms and records via Database Manager. We do so in this example ONLY to demonstrate Additional Options capabilities for manual posting.
Create the Link Record As for automated posting via the Format Control Subroutines process, manual posting requires a link record to control the posting rules. For our example, we can use the same link record we created for automated posting from cm3r.hardware to contacts. Create the Format Control Record
Manual posting is defined in the Additional Options process of Format Control. User Options for Posting appear as Service Tray buttons after the post.fc (Posting) application is launched. 1. Click the Tools button in the Utilities tab. 2. Click on the Format Control button in the Tools menu. 3. Enter the name of the form in the Name field of the blank Format Control record. In this example, enter cm3r.hardware.
Posting
19-25
Source File
Additional Options
Link Record
User Action Add a New Record Update an Existing Record
No
Confirm?
Yes
Yes
Confirm?
No
User Options
User Options
User Options
User Options
Post Data to Target File
Post Add
Post Update
Figure 19-15. Manual Posting Process Flow
19-26
Source File
Additional Options
Link Record
User Action Add a New Record Update an Existing Record
No
Confirm?
Yes
Yes
Confirm?
No
User Options
User Options
User Options
User Options
Post Add
Post Update
Figure 19-16. Manual Posting Process Flow
Posting
19-27
4. if the Format Control record does not already exist, click on the New button to create a new Format Control record.
Figure 19-17. New Format Control Record
5. Select Additional Options from the Options menu or click the Additional Options button. 6. Select Show Expanded Form from the Options menu to display the long version of the Additional Options form. 7. Enter the following field values in the first available slot: Field Option Condition for Option Command Description Comments
19-28
Value 1 true Post to Contacts Post to Contacts POST

Application Error Message Reset on Return Names file name prompt
post.fc Could not post to contacts file. true Values $file cm3r.hardware.post requested.by
Note: After entering the second parameter name and value (name/ cm3r.hardware.post), click Save to save the updated Format Control record. A scroll bar appears next to the Names array so you can scroll down and enter the third Names value (prompt). To enter the third Values value (requested.by), position the cursor on the first Value entry($file) and press the PgDn key.
Figure 19-18. Defining Additional Options for the Source File
8. Click on the OK button to save your changes.

Posting 19-29
Modify a Hardware Change Request

In order to test the manual Posting routine you have set up, you must access a hardware change request and modify one or more fields in the Change Initiator section that were defined in the Link record. Then, you will invoke the Additional Options to verify that the contacts file data changes to reflect the changes in your change request. We will do this via the Database Manager Administrator mode because Format Control Additional Options are not available in Change Management. 1. Access the Database Manager. 2. Select the cm3r.hardware form. 3. Click Administration Mode. Note: You must click Administration Mode or you will be using Change Management instead of Database Manager. Format Control Additional Options are not available in Change Management.
19-30
4. Retrieve any existing Hardware change request, for example the change request you created with a new contact in the last section, as shown below.
Figure 19-19. Retrieving an Existing Change Request
5. Verify that the existing Change Initiator matches an existing contacts file record. To do so, position the cursor on the Change Initiator Name field and click Find. You should see the related Contact Information record displayed on form contacts.g. 6. If no contacts record match exists, clear the existing Change Initiator Name field, then use the Fill button to fill a valid contact value into the change request record.
Posting
19-31
7. Update the Department and Phone fields.
8. Select Post to Contacts from the Options menu to initiate posting to the contacts file. Note: The option name depends on the value entered in the Command field of the Additional Options definition. Therefore, you may see something other than Post to Contacts in your Options menu..
9. Place the cursor in the Change Initiator Name field and click on the Find button. 10. The updated Contact record is displayed.
19-32
Note: The updated departmental data from the change request displays in the Corp. Structure field at the bottom of the Business Information tab, and the updated phone data displays in the Work phone field in the Contact Numbers tab.
Figure 19-20. Updated Contact Record
Confirming the Posting Routine

A confirmation function is available in Posting that posts the new contact information to the target file, but waits for user approval before updating the record. The target file is displayed to the user, who can edit any of the information before confirming the update. For example, when a new Contact record is created by the Posting routine from Change Management, only the fields specified in the Link record are populated. At some point, the record must be completed. When the confirmation feature is active, the new Contact record is displayed to the user when Posting occurs. The user can complete the contact information form, save the record, and return to the request without leaving Change Management.
Posting 19-33
Note: This feature is available in both the automatic and the manual Posting modes. Confirmation is activated by setting a flag called $post.confirm to true in the Expressions field of the source file Link line definition record. 1. Click the Tools button in the Utilities tab. 2. Click on the Links button. 3. Enter the name of the source file Link record in the Form field of the Link Manager dialogue box. In this example, use the name of the Link record you created for these exercises, cm3r.hardware.post. 4. Click on the Search button. The source file Link record is displayed.
Figure 19-21. Posting Link Record
5. Place the cursor in the requested.by field of the Link record and select Select Line from the Options menu. 6. The Link line definition form displays. 7. Enter $post.confirm=true in the Expressions field. 8. Click on the Back button.
19-34
Figure 19-22. Posting Link Line with posting confirmation
9. A prompt box appears, asking if you want to save the changes to the Link record. 10. Click on the Yes button.
Manual Posting with Confirmation

Use the same procedures for evoking the confirmation process as for establishing User Options in manual posting. When you activate the Posting routine, the confirmation process displays the target form and file (contacts) and provides a new set of System Tray buttons. 1. Access the Database Manager. 2. Select the cm3r.hardware form. 3. Click Administration Mode. Note: You must click Administration Mode or you will be using Change Management instead of Database Manager. Format Control Additional Options are not available in Change Management. 4. Retrieve any existing Hardware change request.
Posting 19-35
5. Verify that the existing Change Initiator matches an existing contacts file record. To do so, position the cursor on the Change Initiator Name field and click Find. You should see the related Contact Information record displayed on form contacts.g. 6. If no contacts record match exists, clear the existing Change Initiator Name field, then use the Fill button to fill a valid contact value into the change request record. 7. Update the Department and Phone fields. 8. Select Post to Contacts from the Options menu to initiate posting to the contacts file. Note: The option name depends on the value entered in the Command field of the Additional Options definition. Therefore, you may see something other than Post to Contacts in your Options menu..
19-36
9. The Contact record (target file) for the contact specified in the change request form is displayed, with a confirmation request.
Figure 19-23. Target File with Confirmation Request
10. You may edit other fields than those selected for the Posting routine. 11. Click the Save button to save ALL changes, from both the change request and also changes entered directly in the contact record, to the database. 12. Click the Cancel button to ignore any changes you have made in the record. The Posting process is NOT completed and you are returned to the change request form.
Posting
19-37
19-38
Chapter 20 Error Messages

There are several error messages you will receive if you enter an incorrect expression into a Format Control record. These errors can take several forms: If any syntax errors are present when the system attempts to parse (evaluate) an expression field (e.g., Calculation, Initialization) in a Format Control record, the following message will appear in the Status Bar at the bottom of your screen when you click on the Back button or attempt to select another function from the Options menu: Field contains an invalid expression. In the case of incorrect syntax in a Calculation expression, the system will not let you exit the Format Control record until the problem is resolved. If you cannot resolve it, delete the line and re-enter the desired input when the correct syntax is determined. In the case of incorrect syntax in an Initialization Expression, the system will not let you access additional Format Control functions (Subroutines, Additional Options, etc.) from the Options menu. The system will accept a properly constructed Initialization Expression in a Format Control record that may not be accepted by the called application at run time. When an application cannot recognize an Initialization Expression, the Format Control function fails, and the following message is displayed in the Status Bar at the bottom of your screen Cannot evaluate initialization expression #:1 Format Control will accept properly constructed but conflicting expressions within a record. For example: Initialization expression: $x=ibm Calculation expression: $x+=1 When Format Control attempts to perform this calculation on a non-numeric field at run time, the system displays the following error message: Wrong or mismatched type in increment or decrement
Error Messages 20-1
20-2
Chapter 21 Special Processing Considerations

Incident Management
In Incident Management, each action taken on an incident ticket will add an additional page; therefore, update and delete operations are not truly performed. Even though there is a Save button, the application is really adding a new record to the problem database. Furthermore, when you close an incident, a page gets added to the file with a status of closed. Consequently, when using Format Control on Incident Management, the add field must evaluate to true. Format Control records are only executed on the initial, browse, open, update, and close forms for Incident Management. Format Control could be placed on the following forms: problem.abends.open problem.abends.update problem.abends.close Format Control will NOT be executed on the following forms: problem.hdr problem.hdr1 problem.open problem.update problem.close
Special Processing Considerations
21-1
Change Management
Change Management allows you to define three types of Format Control records: Detail Master Approval. The detail and master records are executed during standard add, update and close processing. The approval record is executed during Change Management approval processing. Change Management uses the four processing functions as follows: Add Processed at open time. Update Processed at update time (update, reopen). Delete Processed at close time. Display Processed when an item is displayed. The Format Control components are executed after the process is invoked but before the record is permanently updated. For instance, the add function is executed after the user clicks on the Open button in either the Request or Task structure, but before the Request/Task is added to the database. The display function is executed after a record has been selected from the QBE list but before the record is actually displayed. You can execute both a master Format Control record and a detail Format Control record for each Request/Task process. If any of the Format Control components fail, for any reason, the user is always returned to the previously displayed screen with the appropriate error messages.
Master Format Control Record

Change Management supports a master Format Control record which allows you to define in one record the Format Control statements that apply to all Change Management Request Phases. The name of the master Format
21-2
Control record is cm3r (cm3t for Tasks). The options on this Format Control record are executed during all Request/Task processing except approval and background processing. The master format control record is processed before the detail Format Control record.
Detail Format Control Record

To enforce processing rules that are unique to a Phase, define a format control record that is the same name as the default View of that Phase. The add, update, delete, and display features are processed just as they are with detail Format Control definitions.
Approval Format Control Record

The Change Management approval process checks for a Format Control record that is associated with the approvals view of the Phase. The add features are processed when a Request is approved. The update features are processed when a Request is disapproved. The delete features are processed when a Request is unapproved. The master Format Control record is not executed during approval processing.
21-3
Eventout Records
When problems are opened, updated or closed by Event Services, a record may be written to the eventout file. This record contains information from the problem (described in the output eventmap record for the event) that will be passed to an external process via the SCAuto/IPAS external interface. You can elect to write to the eventout file when Help Desk operators open and close tickets so that the information is passed to the external interface. The axces.write application creates a character string of fields from a structure and writes them to eventout. An Event Registration record identifies the event type and the name of the Event Map records used to define which fields will be selected from the record. The application should be called as a Format Control Subroutine passing two parameters: The record from which data will be mapped. The Event Type, as defined in the Event Register. To write to eventout on problem close, the Format Control record would be attached to the problem.equipment.close form using the following values: FieldValue Applicationaxces.write Addtrue NameValue record$file namepmc Note: This procedure is not specific to Incident Management. You can write eventout records for other applications, such as Inventory Control or Change Management.
21-4
The Subroutine form for the problem.equipment.open form looks like this:
Figure 21-1. Subroutine for Incident Management
21-5
Page Messages
SCAuto supports a generic page function. Page events can be written to the eventout file via a Subroutine call to scauto.page from Format Control. The parameters to pass are: Name name prompt text string1 query values names, 1 names, 2 names, 3 Value contact.name in contacts file or name in operator file (SP4 or >) numeric message alphanumeric message separation character user sequence number list of contact.name or name values (SP4 or >) a pager phone number (ignored if value is passed in name or values (SP4 or >) pager PIN number (SP4 or >) the name of a record in the distgroup file that contains a list of names or contact.names (optionalSP4 or >)
21-6
Incident Management Alert Records

How can you determine what Format Control record is running within Incident Management at any given time? The normal rules of Format Control apply during Text and GUI mode operations. For example, when you update a form named problem.abends.update.g, Incident Management looks for a Format Control record called problem.abends.update. However, when background alerts are processed, Incident Management uses a different set of Format Control records named problem.<category>.alerts, where <category> is a defined Incident Management category. For example, for an incident ticket of an abends category, Incident Management will look for a Format Control record called problem.abends.alerts. A ticket in the TCP category would access a Format Control record called problem.TCP.alerts.
Important: Alerts are processed in the background and cannot ask the user for information. Any Subroutines which require screen input/ output should be avoided in alert Format Control operations, as should Validations requiring user input.
21-7
21-8
Chapter 22 Common Applications Called from Format Control

Users typically want to know which ServiceCenter applications they can call from Format Control. Since there are so many applications that can be called, listing each one is not practical; however, certain applications are called frequently or have a specific function within Format Control that should be documented. These applications and their parameters are listed below. Also included in this chapter are the steps for determining the parameters for any application you may decide to use.
Common Applications Called from Format Control
22-1
Applications
fill.fc
This application is called to copy data from a target file to the current file, using predefined links under user control.
Parameters
record This will always be $file when calling fill.fc through the Additional Options process. This is a required parameter. text The name of the field in the target file to be filled. The default is the current field (the field in which the cursor is located). If the field is an array, the fill operation will attempt to copy data back to that item in the selected array. string1 The form name that determines which Link record to use. The default is the Link record for the current form.
Variables Supported
$fill.replace $project.first $fill.exact
post.fc
This application is called to execute the Posting routine from the Subroutines process (automatic Posting) and from the Additional Options process (manual Posting). For further information, refer to Chapter 19, Posting.
22-2
Parameters
file This will always be $file when calling post.fc through the Additional Options process. In most cases, the variable will be $file when calling post.fc through the Subroutine process; however, it could be $file1 (or some other file variable established by Format Control or your own RAD processing). name This is an optional field that is defaulted to the name of the currently displayed form. You can override this default by passing a string of the specific Link record you want to use. prompt This is an optional field that is defaulted to the name of the input field in which the cursor was located when the option was selected. You can override this default by passing a string of a specific field name you want to use.
getnumb.fc
Call this application to establish the numbering sequence in Sequential Numbering. You may create simple identification numbers for database records or complex numbers composed of prefixes and suffixes. For further information, refer to Chapter 18, Sequential Numbering for Format Control.
Parameters
record The data record in which the number will be placed. The value of this parameter must be $file. name The sequential number Class (category) of the record to which the Format Control record is attached. This value appears in the Class field of the Sequential Numbering File. prompt Names the field in the data record in which the sequential number will appear.
22-3
text Defines the data type of the sequential number (number or string). number1 Defines the length of the sequential number. The subroutine will append as many zeroes to the number as necessary to match the required number of digits. Pass the RAD function val() to the number1 parameter. For example, a four digit number would have the value val("4", 1) where 4 is the length of the number and 1 is the data type (number). string1 Defines the prefix to use. This is the identifying character string that appears before the sequential number. query Defines the suffix to use. This is the identifying character string that appears after the sequential number. numbers,1 Determines the reset point for the sequential number. When the value passed to the application is reached, the sequential number is reset to its starting value. numbers,2 Establishes a new starting value for the sequential number when the reset point has been reached. numbers,3 Sets the increment/decrement value. For example, you may want to increment by 2, displaying odd or even numbers only. numbers,4 Allows the user to increment or decrement the sequential number independent of the number file. Use this parameter to attach a special number to your records without updating the number file.
message.fc
This application sends messages under user control.
22-4
Parameters
index Select one of three message levels: 1 for information (default) 2 for action 3 for error
In Text mode, message levels may appear in different colors. prompt Enter a message class that matches one of the records in the msgclass table (e.g., problemclose). To send email, there must be a msgclass record with a type of email for the message class name specified. The default is msg. text The text of the message can be either a string or an array. You can generate an array of the screen contents using the genout() function, for example, and insert lines of text at the top of the array. name This value can contain either a list of operator names of a single name. For internal ServiceCenter messages, the names must be operator IDs defined in the operator table. For email, the names can either be operator IDs or contact names (contact.name) defined in the contacts table; an email address must be specified in the relevant table. The default is operator(). string1 The message name parameter is used to identify the message. Use the name of the ServiceCenter application or application area that generates the message. number1 The message number parameter is used to identify a message within the area specified by the string1 parameter. query The mail class parameter is used within Incident Management applications to identify the ticket number so that mail already sent can be selected and updated. It must contain the string pm.main and a Mail Target must be defined.
Common Applications Called from Format Control 22-5
names,1 The mail target parameter must contain the problem ticket number.
validate.fields
Call this application in the Subroutines process to validate fields in a form.
Parameters
name Names the field in the current form to validate. For example, logical.name. To name the field in which the cursor was last located when an add or update were performed, use the RAD function cursor.field.name(). names Name of the array in the current form to validate. The line of the array to be validated must be defined in the Initializations process. second.file The data record in which the field is being validated. The value of this parameter must be $file. cond.input The required value of the field defined by the parameter val(). For example, to validate a boolean field to true, use the value val("true", 4). Example Validate all fields a specific field a range of fields Name second.file second.file name second.file names Value $file $file <field name> $file $array (defined in Initializations
22-6
database
Call this application to access other tables from a particular record. For example, you might want an option button to appear on your users screens allowing them to call the location file from the contacts file.
Important: This application is called only from Additional Options in Format Control.
Parameters
name The name of the form you want to display to a user.
query.stored
This application is called to access all queries for a specific file or to execute a specific stored query.
Important: This application is called only from Additional Options in Format Control.
Parameters
name Name of the file you want the user to be able to query. For example, device.workstation. text Name of the stored query you want to execute. For example, name=operator().
22-7
axces.page
This application builds the eventout record used by the Telemon axces interface. The pager group, type, phone number, and PIN are retrieved from the contacts file.
Parameters
name Required field containing the Contact Name from the contacts file. prompt The numeric message. This is a required field if the text parameter is not used. text The alphanumeric message. This is a required field if the prompt parameter is not used. string1 This parameter defines the separation character. If you define your own character, be sure it does not occur naturally in fields in the event. The default is ^. query This parameter defines the page response code, used by the pageresp input event to identify the type of event processing that should occur. For example, to update a particular problem with the response from a page, pass pm and the problem ticket number (e.g., pm9700123). The registration record determines the application to call by examining the data in the first position of the evfields field. values This parameter identifies a list of addressees from the contacts file or operator file. names,1 This parameter lists the pager phone number from the contacts file. names,2 This parameter lists the pager PIN number from the contacts file.
22-8
names,3 Use this parameter to pass the name of a group defined in the distgroup file.
axces.write
This application is called to build an eventout record used by the SCAutomate interface
Parameters
record The parameter names the record to be written. In Format Control this will be $file. This is a required parameter. name This parameter names the registration type as it appears in the eventregister file. For example, to write an eventout record when an incident is opened, use the value pmo for this parameter. string1 This parameter defines the separation character. If you define your own character, be sure it does not occur naturally in fields in the event. The default is ^. text This parameter defines a system sequence ID with a maximum length of 16 characters. ServiceCenter will generate the system sequence ID unless you supply one. prompt This parameter defines a user sequence ID with a maximum length of 16 characters. query This parameter defines the user name. The default is operator().
22-9
axces.fax
This application is called from Format Control to build an eventout record used by the Replix FAX axces interface.
Parameters
names,1 This parameter passes the name of the sender. Use your login ID. name This parameter passes the name of the recipient. Use the recipients login ID. prompt This parameter defines the recipients FAX phone number. For example, fax.phone from the contacts file. string1 This parameter defines the separation character. If you define your own character, be sure it does not occur naturally in fields in the event. The default is ^. text This parameter names the form or text string. If a record variable is passed in the record parameter, pass the form name in the text parameter. If you pass a string in the text parameter, use the pipe symbol (|) to separate line of text. names,2 This parameter defines the FAX title. names,3 The destination FAX phone number. record This parameter passes the record variable. Use $file in Format Control.
22-10
fingerprint
This application automatically records the names of users adding or updating records of fingerprinted files and the time each action is performed.
Parameter
record Refers to the current file to which the Format Control record is attached. In Format Control this parameter will always be $file. name The name of the array. index Defines the maximum length of the array used to display the fingerprinting data expressed by the function val(). For example, a value of val(10, 1) returns an array listing the last ten updates. string1 Attaches a one word description of the action taken to the end of the fingerprint data string. For example, a string1 value of Updated, adds the word Updated to the user name and date appearing in the fingerprinting array.
sort.array
This application is called from Subroutines to sort simple arrays (number, character, date/time) in either ascending or descending order.
Parameters
file When calling sort.array from Format Control, always pass $file to this parameter. name The name of the input field (array) in $file you wish to sort.
22-11
boolean1 Controls the sort order. A value of true sorts in ascending order, and a value of false sorts in descending order. The value is expressed as val(). For example val(false, 4).
22-12
Determining Parameters
The parameters for any application in ServiceCenter can be determined without using the RAD Editor. Use Database Manager to display the input value of each field in a particular application parameter panel. This value is the parameter name used in the Subroutines process of Format Control. 1. Select the Toolkit tab in the Home menu. 2. Click on the Database Manager button. 3. Type format in the Form field of the Database Manager dialogue box. 4. Press Enter or click on the Search button. 5. Select Format from the QBE list displayed. 6. Enter the name of the application whose parameter values you want to view (getnumb.fc in this example) in the Format Name field of the blank Format form. 7. Press Enter or click on the Search button.
22-13
The parameter Name appears in the Input field of the form and the function appears in the Label field.
Parameter Description
Parameter Name
8. Scroll down to view all the parameters listed. 9. Click on the Back button and exit this record without saving it.
Warning! Be sure to exit the record without altering any information.
22-14
Chapter 23 Introduction to Forms Designer

Chapters 1 through 1 cover the Format Control utility, and are broken out in the following manner: Chapter 23, Introduction to Forms DesignerProvides a brief description of the follow-on chapters and describes the knowledge requirements for users. Chapter 24, Dynamic View DependenciesIntroduces the Forms Designer feature that allows you to create forms with attributes that are evaluated as the user interacts with the forms. Chapter 25, Forms Designer ElementsIntroduces you to the basic elements of Forms Designer. Chapter 26, The Forms Design ProcessOutlines the steps required to access Forms Designer and provides a preview of the forms design process. Chapter 27, The Properties WindowDescribes the types of properties that appear in the Properties Window and how to set property values. Chapter 28, The Tools PaletteProvides detailed descriptions of the 18 tools available in the Tools Palette and the design objects you can create with them. Chapter 29, The Form WizardDescribes how to use the Form Wizard to create a new form. Chapter 30, Tutorial: Creating a New FormLeads you through the process of creating a new form, saving the form and creating a file for the form. The process of modifying an existing form is also described. Chapter 31, Designer TipsProvides tips for designing forms that meet your specific needs.
Introduction to Forms Designer
23-1
The instructions in this manual assume a working knowledge of ServiceCenter. Additional reference information can be found in the ServiceCenter Users Guide and the ServiceCenter System Administrators Guide. To access Forms Designer, you must be logged in as an administrator (for example, FALCON).
23-2
Chapter 24 Dynamic View Dependencies

Dynamic View Dependencies involves a dynamic evaluation of view properties according to special dependencies set up at forms design time. Using Forms Designer, you can create objects with attributes that are evaluated when the form is displayed and as the user interacts with the form. For instance, you can do things like: Specify that a field should be visible only when another field contains a certain value Specify that the choices in a drop-down list be dynamically calculated based on the choice in another combo box Specify that a field be drawn in a special font or color when it displays a certain value
Dynamic View Dependencies
24-1
A number of properties can be set up for dynamic evaluation. Field properties are normally set using the Properties window of Forms Designer. For instance, the Caption property for a Label specifies the text to display on the screen. The figure below shows a Property Window for a Label object.
Associated properties
Figure 24-1. Properties Window
Notice that under the Caption property there is a property named Caption Condition. This associated property allows you to specify a condition evaluated dynamically to compute a caption for the label. Similarly, notice the other property pairing in the Property Window: Visible and Visible Condition ForeColor and ForeColor Condition BackColor and BackColor Condition Bold and Bold Condition Italic and Italic Condition FontIncrease and FontIncrease Condition Other components may have these and other property and property condition pairs. In each case, you are able to specify a special conditional statement that specifies the run-time value for the property.
Specifying property conditions

There are three types of conditional statements that can be specified for a property: Field Comparisons Field Value Matching Dynamic Functions
Field comparisons
The first type of conditional statement is a field comparison. Field comparison statements have the following syntax:
FIELD (=|<>) VALUE

where:
FIELD is any variable or file field surrounded by brackets, for example, [$x], [name], and so forth. VALUE is any quoted string or number.
For example, suppose you want to make a certain field visible only when the category of a ticket equals network. Assume that the category can be selected via a drop-down list whose Input is defined as $category. You can specify the visibility dependency by assigning the following to the Visible Condition property of the field:
[$category] = "network"
Note that it is also conceivable that instead of a variable, a drop-down list might use a record field as input. If the field is named category, you would then set up the Visible Condition as follows:
[category] = "network"
Important: In order for a property to depend on a variable (or record field), the variable must be assigned as an input to an object on the same screen.
Finally, note that in addition to a comparison of equality, you can specify an inequality comparison, as in:
[$category] <> "network" (i.e., category is not network)
24-3
Field value matching

The second type of statement allowed in a property condition allows you to specify matching output values to various input values. The syntax is as follows:
FIELD ? ValueList : DisplayList

where:
FIELD is any variable or file field surrounded by brackets, for example, [$x], [name], and so forth. ValueList and DisplayList are lists of comma-separated values
As an example, suppose you want the color of a label to change based on the value of a severity field. The severity is specified in an edit field whose input is $severity. You set the Color Condition of the label as follows:
[$severity]? "sev1","sev2","sev3" : 1,7,2

This statement tells the label to do the following: Use a color value of 1 (red) when $severity=sev1 Use a color value of 7 (yellow) when $severity=sev2 Use a color value of 2 (green) when $severity=sev3 You can also specify a value to use if no match is found. For instance:
[$severity]? "sev1","sev2","sev3" : 1,7,2, 0

This tells the system to use color 0 (black) if $severity is none of the listed sev values. Note again that it is assumed that the $severity field has been assigned as input to at least one field on the screen.
Dynamic functions
The third type of property condition statement allows you to call a function that evaluates a result dynamically. The syntax is as follows:
FunctionName( PARM_0, ..., PARM_n )

The parameters to the function can be any string or number. One parameter may also be a variable or record field. A number of functions may be defined in the future. Currently, only the following functions are available: select( return_field, file_name, select_field, select_field_value ) Runs a dynamic query to equivalent to:
SELECT return_field FROM file_name WHERE select_field=select_field_value
24-4
lang_preference( lang ) Returns the current language table selection. The function takes as a parameter the current language value. The function takes care of saving new language settings in the scuser preference for future reference. It also forces the user interface to update its language table and repaint as necessary.
Other examples
A special form called dep.g has been prepared to demonstrate Dynamic View Dependencies. This form can be viewed using Forms Designer. Try interacting with the different fields before entering Design Mode to observe how View properties change dynamically. Then inspect the form in Design Mode to see how different View properties are set up.
24-5
Chapter 25 Forms Designer Elements

What is Forms Designer?
Forms Designer is the utility you use to design, create, and update ServiceCenter forms. This utility gives you access to a Drawing Canvas upon which you construct your forms, a Tools Palette from which you can create any of 18 design objects, and a Properties Window that you use to set attributes for each object. In addition, Forms Designer provides a Form Wizard that you can use to automatically create forms based on a particular Database Dictionary.
Forms Designer Elements
25-1
The Drawing Canvas

When you access Forms Designer to create a new form, you are provided with a Drawing Canvas on which you build the form. Note: The Tools Palette shown in Figure 25-1 includes a new tool, the Wrapping Label, that was added to the palette with ServiceCenter 3.0SP1a. If you are using a 3.0 version prior to this service pack, your Tools Palette will be slightly different.
Figure 25-1. The Drawing Canvas
To work effectively with the canvas, you should know the following: The structure of the canvas. How to size your forms on the canvas. How to position multiple objects.
25-2
Structure of the canvas

The canvas contains an invisible grid to which all design objects are referenced. Figure 25-2 illustrates this invisible grid. X coordinates 0 0 30 60 90 120 150 180
10
Y coordinates
20
30
40
Figure 25-2. The Invisible Grid
Items to note about the invisible grid include: Grid coordinates start at (0,0) in the top left corner of the canvas. The X (horizontal) coordinates increase as you move to the right. The Y (vertical) coordinates increase as you move down. There is approximately a 3 to 1 ratio between X units and Y units. For example, 30 X units cover approximately the same amount of space as 10 Y units.
Sizing your forms on the canvas

Before creating a form, you should consider the forms ultimate size. Ideally, you will want to create a form that is completely visible on the users screen so that the user does not have to scroll to view any area of the form.
Forms Designer Elements 25-3
The actual drawing canvas extends well beyond the boundaries shown in figure 25-2. However, to size a form so that it is completely visible to the user, stay within the boundaries shown. These boundaries represent the normal viewing area on most users monitors. If you need to size a form beyond the normal viewing area, consider extending the form downward. Users are more accustomed to scrolling vertically than they are horizontally.
Positioning multiple objects

You can use the invisible grid to help you position multiple objects on the drawing canvas. For instance, if you want to position multiple objects with the same left border, be sure all the objects display the same X property. The Y property can be used in a similar way to position objects with the same top border.
25-4
The Tools Palette

The Tools Palette allows you to create any of 18 design objects. These design objects are the building blocks of your form, each offering a unique look and functionality. Figure 25-3 shows the Tools Palette and indicates the design objects that can be created with each tool. Note: The Pointer allows you to select and modify design objects after they have been created.
Pointer
Label
Text Box
Button MultiLine Text Check Box
Bevel
Frame
Fill Box
Picture
Radio Button Subformat
Combo Box
Marquee
Chart
Table
Tab
Wrapping Label
OLE Container
Figure 25-3. The Tools Palette
Refer to Chapter 28 Forms Designer Elements for a complete description of the tools and the design objects they create. Note: If you are using a 3.0 version of ServiceCenter prior to service pack 1a, the Tools Palette will not include the Wrapping Label.
25-5
The Properties Window

When you create or select a design object, the Properties Window becomes populated with all the properties that apply to that object. Some of the properties that appear are common to all design objects, while others are specific only to that object. Use the edit area at the top of the Properties Window to set values for each property to give the object the attributes you desire. Figure 25-4 shows an example Properties Window for a Label object.
Edit Area
Figure 25-4. Properties Window for a Label
For more information about the Properties Window and how to set properties, refer to Chapter 27, The Properties Window.
25-6
The Form Wizard

The Form Wizard allows you to create forms based on a particular Database Dictionary. For example, you can automatically create both table-type QBE lists and single record display forms. Figure 25-5 shows the screen that prompts you to access the Form Wizard.
Figure 25-5. Accessing the Form Wizard
Refer to Chapter 29, The Form Wizard for a complete description of how to access and use the Form Wizard to create new forms.
25-7
25-8
Chapter 26 The Forms Design Process

Accessing Forms Designer
To start Forms Designer: 1. Click the Toolkit tab located on the Main Menu. The selections available in the Toolkit are displayed. 2. Click the Forms Designer button. The initial Forms Designer screen (Figure 26-1) is displayed.
Figure 26-1. Initial Forms Designer Screen
The Forms Design Process
26-1
3. Choose to create a new form or search for an existing form. To create a new form, enter a name for the form and then click New.
Note: If you do not enter a name for the new form, you will be prompted for a name when you save the form. To search for an existing form, enter the name of the form and press Enter. If you are not sure of the forms name, enter your best guess and click Search.
As an example, click New to create a new form. 4. The system asks if you want to use the Form Wizard to create your new form. (See The Form Wizard on page 29-1 for more information)
In this example, choose to not use the Form Wizard by clicking No.
26-2
5. A Drawing Canvas, Properties Window, and Tools Palette are displayed.

Properties Window
Drawing Canvas
Tools Palette
Figure 26-2. Tools Used to Create a ServiceCenter Form
With the Drawing Canvas, Tools Palette, and Properties Window you can begin to design and create ServiceCenter forms.
26-3
Preview of the Forms Design Process

To give you an idea of the forms design process, we will use the construction of a label as an example. 1. Select the label tool by clicking on the label icon in the Tools Palette. 2. Draw a label by holding down the left mouse button and dragging the cursor across the Drawing Canvas. Release the mouse button to create the label. The label and the corresponding Properties Window are displayed on the Drawing Canvas.
Edit Area
3. The default caption for a new label is Caption. Enter the text you want displayed in the label by clicking on the word Caption in the body of the Properties Window (this enables the edit area for that property) and type your new text. For example, type New Label. 4. Click Yes or press Enter.
26-4
The New Label caption is displayed on the Drawing Canvas and in the Properties Window. To modify your labels position on the canvas, font characteristics, and so forth, make changes to the Properties Window as described in The Properties Window on page 27-1. This is the basic process for creating design objects in Forms Designer. The next chapter describes the types of properties that appear in the Properties Window and how to set property values.
26-5
26-6
Chapter 27 The Properties Window

The Properties Window is used to set property values for each design object in your form. The values you set determine how the object appears on the form and how the object interrelates with the user and with the ServiceCenter database. For an overview of properties and how the values you enter on this panel operate, please see Dynamic View Dependencies on page 24-1.
Using the Properties Window

The Properties Window is divided into two parts: the Body and the Edit Area. The Body is where you select a property. The Edit Area is where you enter a value for the property.
Edit Area
Body
27-1
Sizing the Properties Window

To size the Properties Window, place the mouse cursor near the outside border of the Properties Window and the cursor will change to a sizing tool. Modify the window size by holding down the left mouse button, dragging the edge or corner of the window until the proper size is achieved, and then releasing the mouse button. The Property and Value columns can also be modified in this way.
Selecting a property
The Body of the Properties Window is the area from which you select a property. Note that this is a read-only area. 1. Select (highlight) a property by clicking on the property (or after you have clicked on a property, you can use the arrow keys to move up and down the Properties Window). You can also use the scroll button located on the right side of the Properties Window to view any properties that are not currently visible. 2. The Edit Area becomes enabled for that property. You are now ready to enter a value.
Entering a value manually

The Edit Area of the Properties Window is where you enter a value for the property. Once you have selected a property, the edit area becomes enabled for that property. 1. Type the new value. The new value is displayed in the Edit Area, but not in the property field. 2. Press Enter or click Yes to set the new value for the design object. Clicking on another property will also set the new value. The new value is now displayed in the property field. If you want to restore the original value of the property (and delete the new value), click No. Clicking anywhere outside the Properties Window will also restore the original value.
27-2
Entering a Value from the Edit Area list

For some properties, such as Font, the Edit Area allows you to select from a drop-down list. You will know when a property has a drop-down list because the List button will change from shaded to black. 1. Click the List button. 2. Make your selection from the drop-down list by clicking on the selection or by using the arrow keys. 3. Press Enter or click Yes. For a shortcut, you can select from a drop-down list as follows: 1. Select a property that has a drop-down list. 2. Type the first letter of the selection. For instance, with a Font property you could type T for Times. Note that the letter you type is case sensitive. All fonts begin with a capital letter. 3. Press Enter or click Yes.
27-3
Understanding Properties
When you look at the properties that are displayed for a design object, think of them in terms of the following categories: Common properties Font properties Box properties Object specific properties
Common properties
The first 10 properties in the Properties Window are common to all design objects. These properties are: Property Value _____________________________________________________________ Name Enter a unique identifier to associate a name with the component on the screen. This name is used by external applications such as RAD to change the properties of the component dynamically. This property is optional. The Caption property allows you to enter text for design objects that are capable of displaying text. For instance, if the object is a label, enter the text for your label in this property field. The default value is Caption, which you replace with your own text. Enter a condition for evaluating the Caption property at runtime. The result of this evaluation is used to override the value assigned to the property. Input The Input property allows you to enter the name of the appropriate database field, variable (or structure, for a subform) that corresponds to the design object. The X property refers to the position of the object on the X (horizontal) axis of the alignment grid. The value corresponds to the left edge of the object. The Y property refers to the position of the object on the Y (vertical) axis of the alignment grid. The value corresponds to the top edge of the object. The Height property refers to the height of the object in
Caption
Caption Condition
Height
27-4
alignment grid units. Width Visible The Width property refers to the width of the object in alignment grid units. Indicates whether the property is visible or not. A property can be created and used as a reference point rather than displaying it on a form. Can be used to establish a condition under which a field may or may not be visible.
Visible Condition
Font Properties
Font Properties allow you to modify the appearance of text that is used in the design object. These properties are only displayed for Labels and Frames. Property Value _____________________________________________________________ Font ForeColor BackColor You can select one of seven fonts available from the dropdown list. The default font is Helvetica. Text color. You can select one of 17 colors available from the drop-down list. The default color is Blue. Text background color. You can select one of eleven colors available from the drop-down list. Note that the Opaque property must be set to Yes in order for the BackColor to have effect. Applies bold to the text. Applies italics to the text. Justifies the text to the Left, Right, or Center. Select from the drop-down list. Enables the BackColor property. Font size is initially set to a standard size. To increase or decrease this standard size, change the numeric value of FontIncrease. The default for FontIncrease is 0 (which means no change to the standard font size). Increase font size by making the value larger than 0. Decrease font size by making the value less than 0. This attribute allows you to specify the name of an output conversion routine. If specified, the routine is called at runtime to convert the contents of the field before it is
27-5
Bold Italic Justification Opaque FontIncrease
OutputConv
displayed on the screen. For instance, you could have a function that converts dollars to French francs.
Box Properties
Box Properties apply to any box design object: text box, multi-line text box, fill box, or combo box. Property Value _____________________________________________________________ TabStop When a user tabs through a form, objects are selected in a certain order. If all objects have the default TabStop setting of 0, then each object is visited based on its top-to-bottom, left-to-right position on the form. You can alter the tab order for an object using the following guidelines: - An object with TabStop = -1 is skipped during tabbing. - An object with TabStop = 1 is given focus when the screen is first displayed. - All objects numbered with a non-zero TabStop are tabbed to in increasing TabStop order. Objects with duplicate TabStops are tabbed in a top-to-bottom, left-to-right order. - After all objects with TabStops > 0 are visited, tabbing proceeds to all objects with TabStops of 0. These objects are visited in top-to-bottom, left-to-right order. - ReadOnly objects are skipped during tabbing. ReadOnly Password MaxChars Only allows the user to view the field. Makes the users password entry invisible on the screen. Specifies the number of characters the user can enter in the field. The default is 0, which means an unlimited number of characters can be entered.
MaxCharsBeep Notifies the user (by sounding a beep) that the maximum number of characters has been reached. CaseConversion Changes the case of any text entered in the field. You can select None (allows upper- and lowercase), Upper, or Lower from the drop-down list. Decimals Keeps numeric values from having several numbers to the right of the decimal point (for example, 5.00375). You can select None (allows the long number), 0.0, or 0.00. If Parse is set to Yes, the text entered in a field is parsed to
Parse
27-6
verify that it is of the correct syntax. The syntax for the field is defined by the type of field it is displaying (date, expression, number, and so forth).
Object-specific properties
Refer to Chapter 28, The Tools Palette for a description of all properties that are specific to each design object.
27-7
27-8
Chapter 28 The Tools Palette

The Tools Palette allows you to create any of 18 design components. These components are the building blocks of your forms, each offering a unique look and functionality. Figure 28-1 shows the Tools Palette and indicates the design components that can be created with each tool. Note: The Pointer allows you to select and modify design components after they have been created.
Pointer
Label
Text Box
Button
Bevel
Frame
MultiLine Text Fill Box Box Check Box Radio Button Subformat
Picture
Combo Box
Marquee
Chart
Table
Tab
Wrapping Label
OLE Container
Figure 28-1. The Tools Palette
The Tools Palette
28-1
Pointer
The Pointer allows you to select, deselect, and modify design components. Usage Instructions: To select one component: Click on the component. Corner handles are displayed, indicating that the component is selected.
Or, hold down the left mouse button and drag a lasso across any part of the component. After lassoing the component, handles are displayed.
To select multiple components: Hold down the Shift key and click on multiple components one at a time. Handles are displayed on each component. The properties box is enabled for the last component selected. Or, drag and release a lasso across any part of the desired components. After lassoing the components, handles are displayed on each component. To deselect one component: Hold down the Shift key and click on the component. Corner handles disappear, indicating that the component is no longer selected. To deselect all components: Click on a blank area of the drawing canvas. To position one component: Click on the component and continue holding down the left mouse button. Drag the component to the desired position.
28-2
To resize a component: Select the component. Drag the component handles to resize the component. To delete one or more components: Select the component(s). Press the Delete key.
The Tools Palette
28-3
Label
Description: A Label is a single line of text you can use to give titles to forms, give labels to components within the form, or otherwise place text on the form.
The label tool can also be used to place a data field in a form that displays a QBE list. Example:
All of the headers in this example are standard labels. The dashed boxes (data fields) were also created using the label tool. For more information on using the label tool to create data fields, see More About Labels on page 28-7.
Property Name
Value Enter a unique identifier to associate a name with the component on the screen. This name is used by external applications such as RAD to change the properties of the component dynamically. This property is optional. Enter the text for your label in this property. Enter a formula that will override the Caption property, if the conditions of the formula are met. See Specifying property conditions on page 24-3 for more information. No Input is required for a label, unless you are creating a QBE field (see More About Labels on page 28-7). Horizontal position based on the left edge of the component.
Vertical position based on the top edge of the component.
Caption Caption Condition
Input
X Y Height
28-4
Height of the component in alignment grid units.

Property Width Visible Visible Condition
Value Width of the component in alignment grid units. If Visible is set to false, the component is hidden from view when the form is displayed. Enter a formula that will override the Visible property, if the conditions of the formula are met. See Specifying property conditions on page 24-3 for more information on constructing formulas.
Determines the width and height of an object in relation to its parent window.
Elastic
This property can have one of four values: Nonethe default. If the parent window is resized, the object will not resize with it. Horizontalautomatically adjusts the width of the object in proportion to the width of the parent window. Verticalautomatically adjusts the height of the object in proportion to the height of the parent window. Bothautomatically adjusts both the width and the height in proportion to the parent window. Min Width Used only when the Elastic property is set to Horizontal. If Min Width is set to the default value (-1), then the smallest width of the object will be equal to the value set for the Width property. If Min Width is set to any other value (for example, 20), the object will use this value for the minimum width of the object instead of the value set for the Width property. Used only when the Elastic property is set to Horizontal. If Min Height is set to the default value (-1), then the smallest height of the object will be equal to the value set for the Height property. If Min Height is set to any other value (for example, 20), the object will use this value for the minimum height of the object instead of the value set for the Height property. Select a font for your label from the drop-down list.
Min Height
Font
The Tools Palette
28-5
Property ForeColor ForeColor Condition
Value Text color. Select from 17 available colors. Enter a formula for evaluating the ForeColor property at run time. The result of this evaluation is used to override the value assigned to the property. Background color. The Opaque property must be set to Yes in order for the BackColor to have effect. Enter a formula that will override the BackColor Condition property, if the conditions of the formula are met. See Specifying property conditions on page 24-3 for more information on constructing formulas. When set to Yes, applies bold to your label. Enter a formula that will override the Bold Condition property, if the conditions of the formula are met. See Specifying property conditions on page 24-3 for more information on constructing formulas. When set to Yes, applies italics to your label. Enter a formula that will override the Italic property, if the conditions of the formula are met. See Specifying property conditions on page 24-3 for more information on constructing formulas. You can justify your label to the Left, Right, or Center. Enables the BackColor property. Allows you to increase or decrease the standard font size.
BackColor BackColor Condition
Bold Bold Condition
Italic Italic Condition
Justification Opaque FontIncrease
28-6
Property FontIncrease Condition
Value Enter a formula that will override the FontIncrease property, if the conditions of the formula are met. See Specifying property conditions on page 24-3 for more information on constructing formulas. This property does not apply to labels.
When a screen component is associated with an array data structure, this property specifies the size of the scrolling region that is used to view array entries. For example, if a field is assigned an Array Length of 5, the form will stack five fields vertically to allow viewing of five array entries. A scroll bar appears beside the fields to allow viewing of the array entries. If Array Length is set to -1, the form dynamically creates as man fields as there are entries in the array. If the Input data type is scalar, only a single Text Box is displayed. The default is 0, which means one vertical line of information is displayed.
OutputConv ArrayLength
More About Labels

The Label tool can also be used to create data fields in a form that contains a Query By Example (QBE) list. A QBE list contains fields (the dashed boxes under the column headings in the example below) that display data from the ServiceCenter database.
To create data fields, use the Label tool as follows: 1. Select the Label tool and place a label component on the form. 2. Enter an Input property. For example, for the data field under Category you would enter header.category. 3. Leave the Caption property blank.
The Tools Palette
28-7
Text Box
Description: A Text Box displays the contents of a database field or variable, and conditionally allows the user to enter or modify its contents.
Example:
Property
Value
Name
Enter a unique identifier to associate a name with the component on the screen. This name is used by external applications such as RAD to change the properties of the component dynamically. This property is optional. This property does not apply to text boxes. Enter a formula that will override the Caption property, if the conditions of the formula are met. See Specifying property conditions on page 24-3 for more information on constructing formulas. Enter the name of the appropriate database field or variable.
Horizontal position based on the left edge of the component. Vertical position based on the top edge of the component.
Input X Y Height Width Visible Visible Condition
Height of the component in alignment grid units. Width of the component in alignment grid units. If Visible is set to false, the component is hidden from view when the form is displayed. Enter a formula that will override the Visible property, if the conditions of the formula are met. See Specifying property conditions on page 24-3 for more information on constructing formulas.
28-8
Property
Value Determines the width and height of an object in relation to its parent window.
Elastic
This property can have one of four values: Nonethe default. If the parent window is resized, the object will not resize with it. Horizontalautomatically adjusts the width of the object in proportion to the width of the parent window. Verticalautomatically adjusts the height of the object in proportion to the height of the parent window. Bothautomatically adjusts both the width and the height in proportion to the parent window. Min Width Used only when the Elastic property is set to Horizontal. If Min Width is set to the default value (-1), then the smallest width of the object will be equal to the value set for the Width property. If Min Width is set to any other value (for example, 20), the object will use this value for the minimum width of the object instead of the value set for the Width property. Used only when the Elastic property is set to Horizontal. If Min Height is set to the default value (-1), then the smallest height of the object will be equal to the value set for the Height property. If Min Height is set to any other value (for example, 20), the object will use this value for the minimum height of the object instead of the value set for the Height property. You will almost always use the default of 0 for TabStop. See Box Properties on page 27-6 for more information on tabstops. Prohibits the user from changing the contents of the field. Enter a formula that will override the ReadOnly property, if the conditions of the formula are met. See Specifying property conditions on page 24-3 for more information on constructing formulas.
Min Height
TabStop
ReadOnly ReadOnly Condition
The Tools Palette
28-9
Property
Value
Password MaxChars MaxCharsBeep
Makes the users password entry invisible on the screen. Specifies the number of characters the user can enter in the field. The default is 0 (unlimited). If set to Yes, the system notifies the user (by sounding a beep) that the maximum number of characters has been reached (not available on UNIX systems). Changes the case of text entered in the field. Modifies numbers entered in the field to a number of decimal points you specify. If Parse is set to Yes, the text entered in a field is parsed to verify that it is of the correct syntax. The syntax for the field is defined by the type of field it is displaying (date, expression, number, and so forth). When this property is set to true, the event value is sent to the RAD application when the field loses focus (when you leave the field). Refer to the Dynamic RAD documentation for further information. When Mandatory is set to true, this indicates that the field is required. As a result, the field is flagged with a visible indication that the user must enter input before changes can be saved. The actual enforcement of the mandatory rule is handled by the RAD application.
CaseConversion Decimals Parse
Focus Out Event
Mandatory
28-10
Property
Value When a screen component is associated with an array data structure, this property specifies the size of the scrolling region that is used to view array entries. For example, if a field is assigned an Array Length of 5, the form will stack five fields vertically to allow viewing of five array entries. A scroll bar appears beside the fields to allow viewing of the array entries. If Array Length is set to -1, the form dynamically creates as man fields as there are entries in the array.
ArrayLength
If the Input data type is scalar, only a single Text Box is displayed. The default is 0, which means one vertical line of information is displayed. InputConv
Does not apply to most text boxes you will create. This property is used for RAD subroutines that are designed to mask the display of data on an input field, or check and validate the entry of data into an input field.
For instance, if the text box displays date/time information, entering input.time in the InputConv property will append a time entered in the field to the current date. OutputConv Same as InputConv, but applies to output values.
The Tools Palette
28-11
Button
Description: A Button activates a Control ID when clicked. You can use text or graphics, or both, to customize buttons.
Examples:
Property Name
Value Enter a unique identifier to associate a name with the component on the screen. This name is used by external applications such as RAD to change the properties of the component dynamically. This property is optional. If you want a caption on the button, enter it in this property. Enter a formula that will override the Caption property, if the conditions of the formula are met. See Specifying property conditions on page 24-3 for more information on constructing formulas. Enter the name of the appropriate database field or variable. Horizontal position based on the left edge of the component.
Vertical position based on the top edge of the component
Input X Y Height Width Visible
Height of the component in alignment grid units. Width of the component in alignment grid units. If Visible is set to false, the component is hidden from view when the form is displayed.
28-12
Property Visible Condition
Value Enter a formula that will override the Visible property, if the conditions of the formula are met. See Specifying property conditions on page 24-3 for more information on constructing formulas.
Determines the width and height of an object in relation to its parent window. This property can have one of four values:
Elastic
Nonethe default. If the parent window is resized, the object will not resize with it. Horizontalautomatically adjusts the width of the object in proportion to the width of the parent window. Verticalautomatically adjusts the height of the object in proportion to the height of the parent window. Bothautomatically adjusts both the width and the height in proportion to the parent window. Min Width Used only when the Elastic property is set to Horizontal. If Min Width is set to the default value (-1), then the smallest width of the object will be equal to the value set for the Width property. If Min Width is set to any other value (for example, 20), the object will use this value for the minimum width of the object instead of the value set for the Width property. Used only when the Elastic property is set to Horizontal. If Min Height is set to the default value (-1), then the smallest height of the object will be equal to the value set for the Height property. If Min Height is set to any other value (for example, 20), the object will use this value for the minimum height of the object instead of the value set for the Height property. You will almost always use the default of 0 for TabStop. See Box Properties on page 27-6 for more information on tabstops.
Min Height
TabStop
The Tools Palette
28-13
Property ButtonID
Value Numeric. Specifies a Control ID to transmit to a RAD rio or fdisp panel when clicked. For example, 3 corresponds to F3. 0 corresponds to Enter. Refer to the ServiceCenter RAD Guide for more details. Enter a formula that will override the ButtonID property, if the conditions of the formula are met. See Specifying property conditions on page 24-3 for more information on constructing formulas. You can justify your label to the Left, Right, or Center. Enables the looping display of two or more images specified by the Bitmaps property.
The name(s) of one or more Microsoft Windows bit mapped image files (.BMP file format) to display on the button.
ButtonID Condition
Justification Animated Bitmaps
Bitmaps must reside in the path specified by bitmap_path: in the sc.ini file. You do not need to include the .BMP file suffix for this property. Use a semicolon (;) to delimit multiple file names for use in animation sequences: sc0;sc1;sc2;sc3;sc4 This example sets up an animation loop that consists of five bitmaps. For tips on using images in ServiceCenter, refer to the Graphics and Animation on page 31-8. Push Bitmap
The name of a Microsoft Windows bit-mapped image (.BMP file format) to display when the button is pressed. Bitmaps must reside in the path specified by bitmap_path: in the sc.ini file. You do not need to include the .BMP file suffix for this property. For tips on using images in ServiceCenter, refer to the Graphics and Animation on page 31-8.
28-14
Property Speed
Value Integer. Delay in milliseconds between animation frames. Small values speed up animations. The Microsoft Windows minimum cycle time is 55.
A popup help description that ServiceCenter displays while the cursor is over a button.
BalloonHelp
Bitmap and Caption
If this property is set to true, the button displays its bitmap and caption simultaneously. The placement of the caption depends on the value of the Justification property.
The Tools Palette
28-15
Bevel
Description: Example: A Bevel is a cosmetic rectangular border. Use bevels to make your forms more attractive or easier to understand.
Property Name
Input X Y
28-16
Property Height Width Visible Elastic
Value Height of the component in alignment grid units. Width of the component in alignment grid units. If Visible is set to false, the component is hidden from view when the form is displayed.
Nonethe default. If the parent window is resized, the object will not resize with it. Horizontalautomatically adjusts the width of the object in proportion to the width of the parent window. Verticalautomatically adjusts the height of the object in proportion to the height of the parent window. Bothautomatically adjusts both the width and the height in proportion to the parent window. Min Width Used only when the Elastic property is set to Horizontal. If Min Width is set to the default value (-1), then the smallest width of the object will be equal to the value set for the Width property. If Min Width is set to any other value (for example, 20), the object will use this value for the minimum width of the object instead of the value set for the Width property. Used only when the Elastic property is set to Horizontal. If Min Height is set to the default value (-1), then the smallest height of the object will be equal to the value set for the Height property. If Min Height is set to any other value (for example, 20), the object will use this value for the minimum height of the object instead of the value set for the Height property. Yes or No. Yes forms an opaque rectangle within the bevel boundariesif the bevel is placed over components that were created previously, those components are obscured. No forms only the bevel components behind the bevel are visible.
28-17
Min Height
Opaque
The Tools Palette
Property OuterBevelWidth InnerBevelWidth BackColor
Value Integer. Width of the outer bevel. Default is 2. Integer. Width of the inner bevel. Default is 2. Background color. The Opaque property must be set to Yes in order for the BackColor to have effect.
28-18
Frame
Description: Example: A Frame is a rectangular border that is used to group logically associated items.
This example shows a frame with the caption Coordinator. The frame has been added to group fields which give information about the coordinator.
Property Name
Value
Enter a unique identifier to associate a name with the component on the screen. This name is used by external applications such as RAD to change the properties of the component dynamically. This property is optional. If you want a caption on the button, enter it in this property. Enter a formula that will override the Caption property, if the conditions of the formula are met. See Specifying property conditions on page 24-3 for more information on constructing formulas. Enter the name of the appropriate database field or variable. Horizontal position based on the left edge of the component.
The Tools Palette
28-19
Property Visible Condition
Value
Enter a formula that will override the Visible property, if the conditions of the formula are met. See Specifying property conditions on page 24-3 for more information on constructing formulas.
Elastic
Nonethe default. If the parent window is resized, the object will not resize with it. Horizontalautomatically adjusts the width of the object in proportion to the width of the parent window. Verticalautomatically adjusts the height of the object in proportion to the height of the parent window. Bothautomatically adjusts both the width and the height in proportion to the parent window. Min Width Used only when the Elastic property is set to Horizontal. If Min Width is set to the default value (-1), then the smallest width of the object will be equal to the value set for the Width property. If Min Width is set to any other value (for example, 20), the object will use this value for the minimum width of the object instead of the value set for the Width property. Select a font for the frame caption from the dropdown list. Text color. Choose one of 17 colors available from the drop-down list. Enter a formula that will override the ForeColor property, if the conditions of the formula are met. See Specifying property conditions on page 24-3 for more information on constructing formulas. Background color. The Opaque property must be set to Yes in order for the BackColor to have effect.
Font ForeColor ForeColor Condition
BackColor
28-20
Property BackColor Condition
Value
Enter a formula that will override the BackColor property, if the conditions of the formula are met. See Specifying property conditions on page 24-3 for more information on constructing formulas. When set to Yes, applies bold to your frame caption. Enter a formula for evaluating the Bold property at run time. The result of this evaluation is used to override the value assigned to the property. When set to Yes, applies italics to your frame caption. Enter a formula that will override the Italic property, if the conditions of the formula are met. See Specifying property conditions on page 24-3 for more information on constructing formulas. You can justify your frame caption to the Left, Right, or Center. Enables the BackColor property. Allows you to increase or decrease the standard font size. Enter a formula that will override the FontIncrease property, if the conditions of the formula are met. See Specifying property conditions on page 24-3 for more information on constructing formulas.
Bold Bold Condition
Justification Opaque FontIncrease FontIncrease Condition
The Tools Palette
28-21
Property OutputConv ArrayLength
Value
This property does not apply to frames.

ShadowStyle
Changes the appearance of the border. You can select Inset or Raisedtwo variations of a shaded border. The example shown on the previous page has a ShadowStyle of Inset.
28-22
Multi-Line Text Box

Description: A Multi-line Text Box allows the user to input several lines of data. This component contains scroll bars and allows text wrapping.
Note: A multi-line text box field must be defined as an array of characters in the Database Dictionary. Example: This is a multi-line text box. The user can input several lines of data.
Property
Value
Name
Input X Y Height Width
Height of the component in alignment grid units. Width of the component in alignment grid units.
The Tools Palette
28-23
Property
Value
Visible Visible Condition
If Visible is set to false, the component is hidden from view when the form is displayed. Enter a formula that will override the Visible property, if the conditions of the formula are met. See Specifying property conditions on page 24-3 for more information on constructing formulas.
Elastic
Nonethe default. If the parent window is resized, the object will not resize with it. Horizontalautomatically adjusts the width of the object in proportion to the width of the parent window. Verticalautomatically adjusts the height of the object in proportion to the height of the parent window. Bothautomatically adjusts both the width and the height in proportion to the parent window. Min Width Used only when the Elastic property is set to Horizontal. If Min Width is set to the default value (-1), then the smallest width of the object will be equal to the value set for the Width property. If Min Width is set to any other value (for example, 20), the object will use this value for the minimum width of the object instead of the value set for the Width property. Used only when the Elastic property is set to Horizontal. If Min Height is set to the default value (-1), then the smallest height of the object will be equal to the value set for the Height property. If Min Height is set to any other value (for example, 20), the object will use this value for the minimum height of the object instead of the value set for the Height property. You will almost always use the default of 0 for TabStop. See Box Properties on page 27-6 for more information on tabstops.
Min Height
TabStop
28-24
Property
Value
Prohibits the user from changing the contents of the field. Enter a formula that will override the ReadOnly property, if the conditions of the formula are met. See Specifying property conditions on page 24-3 for more information on constructing formulas. This property does not apply to multi-line text boxes. This property does not apply to multi-line text boxes. This property does not apply to multi-line text boxes. Changes the case of text entered in the field. This property does not apply to multi-line text boxes. If Parse is set to Yes, the text entered in a field is parsed to verify that it is of the correct syntax. The syntax for the field is defined by the type of field it is displaying (date, expression, number, and so forth). When this property is set to true, the event value is sent to the RAD application when the field loses focus (when you leave the field). Refer to the Dynamic RAD documentation for further information. When Mandatory is set to true, this indicates that the field is required. As a result, the field is flagged with a visible indication that the user must enter input before changes can be saved. The actual enforcement of the mandatory rule is handled by the RAD application.
Password MaxChars MaxCharsBeep CaseConversion Decimals Parse
Focus Out Event
Mandatory
The Tools Palette
28-25
Fill Box
Description: A Fill Box allows the user to input data by clicking on an ellipsis button and then selecting data from a QBE list. This type of component allows the user to look up and browse information in another file, validity table, and so forth. It can also be used to copy (fill) information from another table to the users current screen.
Example:
Property
Value
Name
28-26
Property
Value
Visible Condition
Elastic
Nonethe default. If the parent window is resized, the object will not resize with it. Horizontalautomatically adjusts the width of the object in proportion to the width of the parent window. Verticalautomatically adjusts the height of the object in proportion to the height of the parent window. Bothautomatically adjusts both the width and the height in proportion to the parent window. Min Width Used only when the Elastic property is set to Horizontal. If Min Width is set to the default value (-1), then the smallest width of the object will be equal to the value set for the Width property. If Min Width is set to any other value (for example, 20), the object will use this value for the minimum width of the object instead of the value set for the Width property. Used only when the Elastic property is set to Horizontal. If Min Height is set to the default value (-1), then the smallest height of the object will be equal to the value set for the Height property. If Min Height is set to any other value (for example, 20), the object will use this value for the minimum height of the object instead of the value set for the Height property. You will almost always use the default of 0 for TabStop. See Box Properties on page 27-6 for more information on tabstops. Prohibits the user from changing the contents of the field.
Min Height
TabStop
ReadOnly
The Tools Palette
28-27
Property
Value
ReadOnly Condition
Enter a formula that will override the ReadOnly property, if the conditions of the formula are met. See Specifying property conditions on page 24-3 for more information on constructing formulas. This property does not apply to fill boxes. Specifies the number of characters the user can enter in the field. The default is 0 (unlimited). If set to Yes, the system notifies the user (by sounding a beep) that the maximum number of characters has been reached. Changes the case of text entered in the field. Modifies numbers entered in the field to a number of decimal points you specify. If Parse is set to Yes, the text entered in a field is parsed to verify that it is of the correct syntax. The syntax for the field is defined by the type of field it is displaying (date, expression, number, and so forth). When this property is set to true, the event value is sent to the RAD application when the field loses focus (when you leave the field). Refer to the Dynamic RAD documentation for further information. When Mandatory is set to true, this indicates that the field is required. As a result, the field is flagged with a visible indication that the user must enter input before changes can be saved. The actual enforcement of the mandatory rule is handled by the RAD application. Numeric. Specifies a Control ID to transmit a RAD rio or fdisp panel when clicked. For example, 3 corresponds to F3. 0 corresponds to Enter. Refer to the ServiceCenter RAD Guide for more details.
Password MaxChars MaxCharsBeep
Focus Out Event
Mandatory
ButtonID
28-28
Property
Value
ButtonBitmap ArrayLength
Select one of 16 possible button and color combinations:

When a screen component is associated with an array data structure, this property specifies the size of the scrolling region that is used to view array entries. For example, if a field is assigned an Array Length of 5, the form will stack five fields vertically to allow viewing of five array entries. A scroll bar appears beside the fields to allow viewing of the array entries. If Array Length is set to -1, the form dynamically creates as man fields as there are entries in the array. If the Input datatype is scalar, only a single Text Box is displayed. The default is 0, which means one vertical line of information is displayed.
HideEdit
If the value of the HideEdit property for a Fill object is set to Yes, the text in the Fill object cannot be displayed or edited.
The Tools Palette
28-29
Picture
Description: . Example: A Picture displays a cosmetic image from a Microsoft Windows BMP file
Property Name
Value
Input X Y Height Width
Height of the component in alignment grid units. Width of the component in alignment grid units.
28-30
Property Visible Visible Condition
Value
If Visible is set to false, the component is hidden from view when the form is displayed. Enter a formula that will override the Visible property, if the conditions of the formula are met. See Specifying property conditions on page 24-3 for more information on constructing formulas.
Elastic
This property can have one of four values: Nonethe default. If the parent window is resized, the object will not resize with it. Horizontalautomatically adjusts the width of the object in proportion to the width of the parent window. Verticalautomatically adjusts the height of the object in proportion to the height of the parent window. Bothautomatically adjusts both the width and the height in proportion to the parent window. Min Width Used only when the Elastic property is set to Horizontal. If Min Width is set to the default value (-1), then the smallest width of the object will be equal to the value set for the Width property. If Min Width is set to any other value (for example, 20), the object will use this value for the minimum width of the object instead of the value set for the Width property. Used only when the Elastic property is set to Horizontal. If Min Height is set to the default value (-1), then the smallest height of the object will be equal to the value set for the Height property. If Min Height is set to any other value (for example, 20), the object will use this value for the minimum height of the object instead of the value set for the Height property.
Min Height
The Tools Palette
28-31
Property Bitmap
Value The name of a Microsoft Windows bit-mapped image file (.BMP file format). The bitmap must reside in the path specified by bitmap_path: in the sc.ini file. You do not need to include the .BMP file suffix for this property.
Bitmap Condition
Enter a formula that will override the Bitmap property, if the conditions of the formula are met. See Specifying property conditions on page 24-3 for more information on constructing formulas. Yes or No. Yes displays the full image regardless of the dimensions of the Picture component. No resizes the image at run time to fit the dimensions of the Picture component. Yes or No. Yes displays a beveled frame around the image. Yes or No. No is the default. Used only if AutoResize is turned on. AutoResize allows a bitmap to be stretched or shrunk to fit the rectangular border defined in Forms Designer to hold the bitmap. Setting Constrain to Yes will allow the bitmap to be reduced to fit inside the rectangle, but will not expand the bitmap if it is smaller than the rectangle. Prohibits the user from changing the contents of the field. Enter a formula that will override the ReadOnly property, if the conditions of the formula are met. See Specifying property conditions on page 24-3 for more information on constructing formulas.
AutoResize
Frame Constrain
28-32
Check Box
Description: A Check Box is a Boolean (logical) field that can evaluate to true, false, unknown, or null.
Note: Check boxes are not supported on a QBE list.
Example:
Property
Value
Name
The Tools Palette
28-33
Property
Value
Visible Condition
Elastic
This property can have one of four values: Nonethe default. If the parent window is resized, the object will not resize with it. Horizontalautomatically adjusts the width of the object in proportion to the width of the parent window. Verticalautomatically adjusts the height of the object in proportion to the height of the parent window. Bothautomatically adjusts both the width and the height in proportion to the parent window. Min Width Used only when the Elastic property is set to Horizontal. If Min Width is set to the default value (-1), then the smallest width of the object will be equal to the value set for the Width property. If Min Width is set to any other value (for example, 20), the object will use this value for the minimum width of the object instead of the value set for the Width property. Used only when the Elastic property is set to Horizontal. If Min Height is set to the default value (-1), then the smallest height of the object will be equal to the value set for the Height property. If Min Height is set to any other value (for example, 20), the object will use this value for the minimum height of the object instead of the value set for the Height property. You will almost always use the default of 0 for TabStop. See Box Properties on page 27-6 for more information on tabstops. Prohibits the user from changing the contents of the field.
Min Height
TabStop
ReadOnly
28-34
Property
Value
Focus Out Event
When this property is set to true, the event value is sent to the RAD application when the field loses focus (when you leave the field). Refer to the Dynamic RAD documentation for further information.
Left or Right. Specifies the position of the caption with respect to the check box.
TextLocation
State State Condition
Integer. Reserved for future use. Enter a formula that will override the State property, if the conditions of the formula are met. See Specifying property conditions on page 24-3 for more information on constructing formulas.
When a screen component is associated with an array data structure, this property specifies the size of the scrolling region that is used to view array entries. For example, if a field is assigned an Array Length of 5, the form will stack five fields vertically to allow viewing of five array entries. A scroll bar appears beside the fields to allow viewing of the array entries. If Array Length is set to -1, the form dynamically creates as man fields as there are entries in the array. If the Input datatype is scalar, only a single Text Box is displayed. The default is 0, which means one vertical line of information is displayed.
ArrayLength
The Tools Palette
28-35
Property
Value
ForeColor Data Changed Event Mandatory
Text color. Choose one of 17 colors available from the drop-down list. Specify the option number (such as button ID) to call if the data contained in the object has changed. This sends an event to the RAD application. When Mandatory is set to true, this indicates that the field is required. As a result, the field is flagged with a visible indication that the user must enter input before changes can be saved. The actual enforcement of the mandatory rule is handled by the RAD application.
28-36
Radio Button
Description: A Radio Button allows the user to select one value from a set of mutually-exclusive values. The items in the set are associated with a database field or variable.
Important: A Frame must be placed around one or more radio buttons in order for the button(s) to be functional.
Use radio buttons to give the user a quick way to choose one option from a set of fixed and mutually exclusive string values. Follow these rules: Group related radio buttons within a frame or bevel. All radio buttons within a frame must specify the same input property. The input property must specify a character or number data type. If the choice is logical (true or false), use a check box instead. If choices are extensive or if the user may need to enter a choice manually, use a combo box instead. Note: Radio buttons are not supported on a QBE list. Example:
The Tools Palette
28-37
Property Name
28-38
Property Elastic
Value
This property can have one of four values: Nonethe default. If the parent window is resized, the object will not resize with it. Horizontalautomatically adjusts the width of the object in proportion to the width of the parent window. Verticalautomatically adjusts the height of the object in proportion to the height of the parent window. Bothautomatically adjusts both the width and the height in proportion to the parent window. Min Width Used only when the Elastic property is set to Horizontal. If Min Width is set to the default value (-1), then the smallest width of the object will be equal to the value set for the Width property. If Min Width is set to any other value (for example, 20), the object will use this value for the minimum width of the object instead of the value set for the Width property. Used only when the Elastic property is set to Horizontal. If Min Height is set to the default value (-1), then the smallest height of the object will be equal to the value set for the Height property. If Min Height is set to any other value (for example, 20), the object will use this value for the minimum height of the object instead of the value set for the Height property. You will almost always use the default of 0 for TabStop. See Box Properties on page 27-6 for more information on tabstops. Prohibits the user from changing the contents of the field.
Min Height
TabStop
ReadOnly
The Tools Palette
28-39
Property Focus Out Event
Value When this property is set to true, the event value is sent to the RAD application when the field loses focus (when you leave the field). Refer to the Dynamic RAD documentation for further information.
Left or Right. Specifies the position of the caption with respect to the Radio Button.
TextLocation
State Value
Integer. Reserved for future use. Value to assign to the field or variable specified in the Input property when this Radio Button is selected. Text color. Choose one of 17 colors available from the drop-down list. Specify the option number (such as button ID) to call if the data contained in the object has changed. This sends an event to the RAD application. When Mandatory is set to true, this indicates that the field is required. As a result, the field is flagged with a visible indication that the user must enter input before changes can be saved. The actual enforcement of the mandatory rule is handled by the RAD application.
ForeColor Data Changed Event Mandatory
28-40
Combo Box
Description: A Combo Box allows the user to click on a dedicated button and select from a drop-down list. The items in the list are associated with a database field or variable.
Example:
the combo box as displayed in Forms Designer
The first example shows how the combo box is displayed on the Drawing Canvas when you create it in Forms Designer. Note that the drop-down list is not visible.
the combo box as seen by the user
The second example shows how the user will see the combo box once the dedicated button is clicked.
Property
Value
Name
Enter a unique identifier to associate a name with the component on the screen. This name is used by external applications such as RAD to change the properties of the component dynamically. This property is optional. If you want a caption on the button, enter it in this property. Enter a formula that will override the Caption property, if the conditions of the formula are met. See Specifying property conditions on page 24-3 for more information on constructing formulas.
The Tools Palette
28-41
Property
Value
Enter the name of the appropriate database field or variable. Horizontal position based on the left edge of the component.
Elastic
This property can have one of four values: Nonethe default. If the parent window is resized, the object will not resize with it. Horizontalautomatically adjusts the width of the object in proportion to the width of the parent window. Verticalautomatically adjusts the height of the object in proportion to the height of the parent window. Bothautomatically adjusts both the width and the height in proportion to the parent window. Min Width Used only when the Elastic property is set to Horizontal. If Min Width is set to the default value (-1), then the smallest width of the object will be equal to the value set for the Width property. If Min Width is set to any other value (for example, 20), the object will use this value for the minimum width of the object instead of the value set for the Width property.
28-42
Property
Value
Min Height
Used only when the Elastic property is set to Horizontal. If Min Height is set to the default value (-1), then the smallest height of the object will be equal to the value set for the Height property. If Min Height is set to any other value (for example, 20), the object will use this value for the minimum height of the object instead of the value set for the Height property. You will almost always use the default of 0 for TabStop. See Box Properties on page 27-6 for more information on tabstops. Prohibits the user from changing the contents of the field. Enter a unique identifier to associate a name with the component on the screen. This name is used by external applications such as RAD to change the properties of the component dynamically. This property is optional. If you want a caption on the button, enter it in this property. Enter a formula that will override the Caption property, if the conditions of the formula are met. See Specifying property conditions on page 24-3 for more information on constructing formulas. Enter the name of the appropriate database field or variable. This property does not apply to combo boxes. Specifies the number of characters the user can enter in the field. The default is 0 (unlimited). If set to Yes, notifies the user (by sounding a beep) that the maximum number of characters has been reached. Changes the case of text entered in the field. Modifies numbers entered in the field to a number of decimal points you specify.
TabStop
ReadOnly Name
Input Password MaxChars MaxCharsBeep
CaseConversion Decimals
The Tools Palette
28-43
Property
Value
Parse
If Parse is set to Yes, the text entered in a field is parsed to verify that it is of the correct syntax. The syntax for the field is defined by the type of field it is displaying (date, expression, number, and so forth). When this property is set to true, the event value is sent to the RAD application when the field loses focus (when you leave the field). Refer to the Dynamic RAD documentation for further information. When Mandatory is set to true, this indicates that the field is required. As a result, the field is flagged with a visible indication that the user must enter input before changes can be saved. The actual enforcement of the mandatory rule is handled by the RAD application.
Focus Out Event
Mandatory
28-44
Property
Value This property (in conjunction with the Input property) defines how the DisplayList values are identified in the database. For example, on the previous page we have a drop-down list that displays the following values:
ValueList
number character date/time logical

The DisplayList for this drop-down list is a semicolondelimited list that reads as follows:
number;character;date/time;logical
For the ValueList, you define how the DisplayList values are identified in the database (i.e., you give them a code that the database uses). For instance, you may enter the following semicolon delimited values in ValueList:
n;c;d;l (for number, character, date/time, logical)

If, for instance, the user selects number from the dropdown list, the corresponding value in the ValueList (n) is assigned to the field specified by the Input property. There must be a one-to-one correspondence between the values for ValueList and for DisplayList. Value and Display Lists are entered using the List Editing Dialog. You can enter hard coded entries for each list, or you can supply a variable as the first and only entry. The run time values of the variable are used to populate these lists.
Value List Condition
Enter a formula that will override the Value List property, if the conditions of the formula are met. See Specifying property conditions on page 24-3 for more information on constructing formulas.
This property defines the values that are displayed in the drop-down list at run time. You can specify a literal list of semicolon-delimited values, or you can specify the name of an array containing the list of values. There must be a one-to-one correspondence between the values for ValueList and for DisplayList.
DisplayList
The Tools Palette
28-45
Property
Value
DisplayList Condition
Enter a formula that will override the DisplayList property, if the conditions of the formula are met. See Specifying property conditions on page 24-3 for more information on constructing formulas. Integer. Window size of the drop-down list.
Yes or No. Yes requires the user to select from the combo box dropdown list. If the user makes a manual entry, the value must already exist in the drop-down list (defined in the ValueList and DisplayList properties). A setting of No allows the user to select from the dropdown list or to manually enter a value. No will work with or without a drop-down list as defined in the ValueList and DisplayList properties.
BoxLines SelectOnly
ArrayLength
Data Changed Event
Specify the option number to call if the data contained in the object has changed. This sends an event to the RAD application.
28-46
Marquee
Description: Example: A Marquee is an attention-getting text message that scrolls continuously across the screen from right to left.
Property
Value
Name
The Tools Palette
28-47
Property
Value
Visible Condition
Elastic
This property can have one of four values: Nonethe default. If the parent window is resized, the object will not resize with it. Horizontalautomatically adjusts the width of the object in proportion to the width of the parent window. Verticalautomatically adjusts the height of the object in proportion to the height of the parent window. Bothautomatically adjusts both the width and the height in proportion to the parent window. Min Width Used only when the Elastic property is set to Horizontal. If Min Width is set to the default value (-1), then the smallest width of the object will be equal to the value set for the Width property. If Min Width is set to any other value (for example, 20), the object will use this value for the minimum width of the object instead of the value set for the Width property. Used only when the Elastic property is set to Horizontal. If Min Height is set to the default value (-1), then the smallest height of the object will be equal to the value set for the Height property. If Min Height is set to any other value (for example, 20), the object will use this value for the minimum height of the object instead of the value set for the Height property. Text color. One of 17 colors available from the dropdown list. Background color. The Background color for a marquee is Black.
Min Height
ForeColor BackColor
28-48
Property
Value
FontIncrease Font Bold Italic
Allows you to increase or decrease the standard font size. Select a font for your marquee caption from the drop-down list. Applies bold to your marquee caption. Applies italics to your marquee caption.
The Tools Palette
28-49
Subformat
Description: A Subformat is a grouping of information (structure) that is imported into a larger form. Subformats generally contain information that is used in multiple formsa header, for instance. The advantage of subformats is that they allow you to create a structure once and then use the structure over again by importing it into other forms. In this way, subformats make it easier for you to create and maintain forms. Example #1 shows the form cc.incquick.g as it is displayed to a user at run time. This form was created using two subformatsone for contact information and the other for device information. Example #2 shows how the form is displayed to you in Forms Designer. Example #1:
Subformats
cc.contact.vj
cc.device.vj
28-50
Example #2:
Subformats
cc.contact.vj
cc.device.vj
In design mode, subformat components are displayed as dashed boxes. The three dashed boxes on the left of the drawing canvas correlate with the three subformats shown in Example #1. Note that the width of each box is not importanta subformat will assume the size you specify in its individual Properties Window. This example shows the subformat cc.contact.vj selected. The Properties Window displays the values that correspond to this subformat.
The Tools Palette
28-51
Property
Values
Name
28-52
Property
Values Determines the width and height of an object in relation to its parent window.
Elastic
This property can have one of four values: Nonethe default. If the parent window is resized, the object will not resize with it. Horizontalautomatically adjusts the width of the object in proportion to the width of the parent window. Verticalautomatically adjusts the height of the object in proportion to the height of the parent window. Bothautomatically adjusts both the width and the height in proportion to the parent window. Min Width Used only when the Elastic property is set to Horizontal. If Min Width is set to the default value (-1), then the smallest width of the object will be equal to the value set for the Width property. If Min Width is set to any other value (for example, 20), the object will use this value for the minimum width of the object instead of the value set for the Width property. Used only when the Elastic property is set to Horizontal. If Min Height is set to the default value (-1), then the smallest height of the object will be equal to the value set for the Height property. If Min Height is set to any other value (for example, 20), the object will use this value for the minimum height of the object instead of the value set for the Height property.
Min Height
The Tools Palette
28-53
Property
Values
Format VirtualJoin
Format used to display the structure. Yes or No. Yes associates virtual join run time processing with the subformat component. For more information on Virtual Joins, refer to the Link and Join Utilities Users Guide. Yes or No. Only for VirtualJoins. Yes displays the subformat even if no records were found for the virtual join. No displays the format only if the virtual join found matching records. This property is available only in ServiceCenter versions 2 and above.
DisplayBlank
28-54
Chart
Description: A Chart displays the contents of a numeric array as a twodimensional, color-coded bar chart with (optional) definable buttons.
Example:
Property
Value
Name
Input X Y Height
Height of the component in alignment grid units.
The Tools Palette
28-55
Property
Value
Width Visible Visible Condition
Width of the component in alignment grid units. If Visible is set to false, the component is hidden from view when the form is displayed. Enter a formula that will override the Visible property, if the conditions of the formula are met. See Specifying property conditions on page 24-3 for more information on constructing formulas.
Elastic
This property can have one of four values: Nonethe default. If the parent window is resized, the object will not resize with it. Horizontalautomatically adjusts the width of the object in proportion to the width of the parent window. Verticalautomatically adjusts the height of the object in proportion to the height of the parent window. Bothautomatically adjusts both the width and the height in proportion to the parent window. Min Width Used only when the Elastic property is set to Horizontal. If Min Width is set to the default value (-1), then the smallest width of the object will be equal to the value set for the Width property. If Min Width is set to any other value (for example, 20), the object will use this value for the minimum width of the object instead of the value set for the Width property. Used only when the Elastic property is set to Horizontal. If Min Height is set to the default value (-1), then the smallest height of the object will be equal to the value set for the Height property. If Min Height is set to any other value (for example, 20), the object will use this value for the minimum height of the object instead of the value set for the Height property. Integer. Width of bars in alignment grid units.
Min Height
BarWidth
28-56
Property
Value Integer. Specifies the maximum vertical bar height. Columns that exceed the ScaleMax setting will appear clipped. A setting of 0 causes the chart to automatically scale vertically to the tallest column.
ScaleMax
ButtonBase BaseButtonID
Yes or No. Yes enables a row of buttons across the base of the chart, one button per column.
Numeric. Specifies the Control ID for the left-most chart button. The BaseButtonID is incremented by one from left to right for additional buttons. Using the default value of 801 as an example, the leftmost button would transmit 801, the second button from the left would transmit 802, the third 803, and so forth. Like the Button component itself, a chart button transmits a Control ID to a RAD rio panel when clicked.
ColorList
Specifies a list of semicolon delimited colors. The ColorScale and ColorPercent properties determine how the list is applied to the columns. The available colors are: Black, Red, Green, Blue, Gray, Light Gray, Dark Gray, Yellow, Cyan, Magenta, White, Forest, Navy, Purple, Teal, Brick, and Manila Specifies a list of semicolon delimited numeric values that determine the color of a column. Yes or No. Yes indicates that ColorScale as a list of percentages from 1 to 100. Text color. Select from seventeen colors available from the drop-down list. A one-line help description that ServiceCenter displays while the users cursor is over the button.
ColorScale ColorPercent ForeColor BalloonHelp
More about the Input property

The input property most commonly specifies a numeric array. For example, a global variable such as $category.first.response might store the average number of minutes between the first report of trouble and the first response by a technician for each of eight categories:
18,29,62,19,37,45,16,30
The Tools Palette 28-57
The elements in this array would be charted from left to right. If you needed to create a static chart (for example, for testing), you could specify a literal list of numbers delimited by semicolons in the Input property:
18;29;62;19;37;45;16;30
More about column colors

There are four methods for assigning column colors: Default (all red)to keep all columns red, leave the ColorList and ColorScale properties blank. Alternate colorsto alternate the column colors, specify a ColorList and leave ColorScale blank. The colors in ColorList are applied to the columns repeatedly from left to right. For example, a ColorList property of Blue;Yellow specifies blue odd numbered columns and yellow even numbered columns. Color based on column valueto assign a color based on the value of a column, specify a ColorList and ColorScale, and set ColorPercent to No. For example, you could have a ColorScale property of:
30;45
and a ColorList property of:
Green;Yellow;Red
This sets up a three-tiered ColorScale that determines which ColorList color to apply to a column. column value <= 30 30 < column value <= 45 column value > 45 use 1st ColorList (Green) use 2nd ColorList (Yellow) use 3rd ColorList (Red)
Color based on relative column valueto assign a color based on the relative value of a column, specify a ColorList and set ColorPercent to Yes. For ColorScale, specify percentages from 1 to 100. Relative value for a column is computed as follows:
100 * (column value)/ScaleMax
28-58
Table
Description: A Table allows you to display one or more columns of data in a scrollable pane. For more information about other features that are supported by this tool, refer to More about tables on page 28-66.
Example:
Table Properties (fields editable by clicking inside the table):
Property
Value
Name
Enter a unique identifier to associate a name with the component on the screen. This name is used by external applications such as RAD to change the properties of the component dynamically. This property is optional. If you want a caption on the button, enter it in this property. Enter a formula that will override the Caption property, if the conditions of the formula are met. See Specifying property conditions on page 24-3 for more information on constructing formulas. Enter the name of the appropriate database field or variable.
Input
The Tools Palette
28-59
Property
Value
X Y Height Width Visible Visible Condition
Horizontal position based on the left edge of the component.

Elastic
28-60
Property
Value
Min Height
Used only when the Elastic property is set to Horizontal. If Min Height is set to the default value (-1), then the smallest height of the object will be equal to the value set for the Height property. If Min Height is set to any other value (for example, 20), the object will use this value for the minimum height of the object instead of the value set for the Height property. You will almost always use the default of 0 for TabStop. See Box Properties on page 27-6 for more information on tabstops. List of columns in the table. If Yes, headings are displayed above the columns. If Yes, the user can highlight several rows. If Yes, the cells in the table cannot be edited. If Yes, the user can delete rows by pressing the Delete key. If Yes/Prompted, the user is first prompted before deletion is done. The color of the table background. Enter a formula that will override the BackColor property, if the conditions of the formula are met. See Specifying property conditions on page 24-3 for more information on constructing formulas. Color used for the table contents (text). Enter a formula that will override the ForeColor property, if the conditions of the formula are met. See Specifying property conditions on page 24-3 for more information on constructing formulas. Background color of a selected row. Foreground color of selected text. Background color of the top row used to display column headings. Color used to draw the column and row separators.
TabStop
Columns ColumnHeadings MultipleSelections ReadOnly AllowRowDelete
ForeColor ForeColor Condition
SelectedBackColor SelectedForeColor HeadingBackColor SeparatorColor
The Tools Palette
28-61
Property
Value
InvertReadOnly Colors OldStyleFdisp
If Yes, the table is drawn in inverted colors (background and separator colors are swapped, normally resulting in a grayed-out table). If Yes, the tables used in FDISP panels will revert row selections to ROW 0 as soon as the user makes a function key selection in the tool. If an individual column ButtonID is set to 0, the DefaultButtonID is used. See the definition for the ButtonID property in the Column Properties definitions.
The ID generated when a selected row is double clicked.
DefaultButtonID
DoubleClick ButtonID Refresh Rate
See the definition for the DoubleClick ButtonID property in the Column Properties definitions. Specify the refresh rate (how often the client queries the server for an update) for the table, in seconds. Select a font for your table from the drop-down list. Allows you to increase or decrease the standard font size. When set to Yes, applies bold to the default font. When set to Yes, applies italics to the default font.
Font FontIncrease Bold Italic
Column Properties (editable by clicking on the column heading after you have created it):
28-62
Property
Value
Name
Enter a unique identifier to associate a name with the component on the screen. This name is used by external applications such as RAD to change the properties of the component dynamically. This property is optional. Enter the text for your table heading in this property. Enter the array variable used as Input for the column. Horizontal position based on the components left edge. Vertical position based on the components top edge. Height of the component in alignment grid units. Width of the component in alignment grid units. If Visible is set to false, the component is hidden from view when the form is displayed. Enter a formula that will override the Visible property, if the conditions of the formula are met. See Specifying property conditions on page 24-3 for more information on constructing formulas.
Caption Input
X
Height Width Visible Visible Condition
Elastic
This property can have one of four values: Nonethe default. If the parent window is resized, the object will not resize with it. Horizontalautomatically adjusts the width of the object in proportion to the width of the parent window. Verticalautomatically adjusts the height of the object in proportion to the height of the parent window. Bothautomatically adjusts both the width and the height in proportion to the parent window.
The Tools Palette
28-63
Property
Value
Min Width
Used only when the Elastic property is set to Horizontal. If Min Width is set to the default value (-1), then the smallest width of the object will be equal to the value set for the Width property. If Min Width is set to any other value (for example, 20), the object will use this value for the minimum width of the object instead of the value set for the Width property. Used only when the Elastic property is set to Horizontal. If Min Height is set to the default value (-1), then the smallest height of the object will be equal to the value set for the Height property. If Min Height is set to any other value (for example, 20), the object will use this value for the minimum height of the object instead of the value set for the Height property. If the array variable used as Input is an array of structures, you may enter the field name within the structure that should be displayed in the column. Size of the column as a percentage of the tables visible width. If Yes, the user can resize the column using the mouse. If Yes, the columns heading acts as a clickable button. The ID generated when a clickable title button is pressed. Behaves just like other components with a ButtonID property. If Yes, the heading for the column is visible. List of display choices for editing cells in the column. If this list is empty, cells in the column are edited using an edit control. If the list is not empty, cells in the column are edited using a combo box with the choices in the ValueList available in a drop-down menu.
Min Height
Field
Column Width% Sizeable Clickable Title ButtonID
ShowTitle ValueList
28-64
Property
Value
Bitmaps
List of display bitmaps. This option works in conjuction with ValueList. If the input to a cell matches a value in the ValueList, the Bitmap with the corresponding index is displayed instead.
This property defines the values that are displayed in the drop-down list at run time. You can specify a literal list of semicolon-delimited values, or you can specify the name of an array containing the list of values. There must be a one-to-one correspondence between the values for ValueList and for DisplayList.
DisplayList
DisplayList Condition
Enter a formula that will override the DisplayList property, if the conditions of the formula are met. See Specifying property conditions on page 24-3 for more information on constructing formulas. This property is relevant only if a ValueList is provided. If Yes, the column allows selections from a combo box populated with values from the ValueList but will not allow manual editing of the cell text. If Yes, cells in the column cannot be edited. Specifies the number of characters the user can enter in the field. The default is 0 (unlimited). If set to Yes, the system notifies the user (by sounding a beep) that the maximum number of characters has been reached. Changes the case of text entered in the column cells. Modifies numbers entered in the column cells to a number of decimal points you specify. If Parse is set to Yes, the text entered in a field is parsed to verify that it is of the correct syntax. The syntax for the field is defined by the type of field it is displaying (date, expression, number, and so forth). Allows you to align column contents to the Left, Center, or Right.
SelectOnly
ReadOnly MaxChars MaxCharsBeep
Justification
The Tools Palette
28-65
More about tables

The tables you create in Forms Designer appear as a rectangular region subdivided by rows and columns. The look and feel mimics tables in Microsoft Windows 95 applications like Exchange or Explorer. Tables support many features, including the following: Cells may display text or bitmaps. Columns may vary in width. The user can resize the columns using the mouse. Columns may have an optional heading button which can be mapped to perform any action in RAD. All rows are the same height, defined by the table's font. The user can scroll through data by use of scrollbars or the keyboard. All expected keyboard navigation is supported (Up, Down, Next, Prev, Last, First, and so forth). Cells can be editable or read-only. Selecting a read-only cell results in a highlight of the entire row. Selecting an editable cell results in the in-place creation of an edit field or drop-down combo box that lets the user edit the cell. Users can edit a field by clicking on it or by pressing the Enter key while the table has focus. Tabbing events received while the table is in edit mode result in navigation from one cell to the next. Pressing Enter while a cell is being edited results in the changes being accepted and the cell's row being highlighted. Tabbing events received when a row is highlighted are handled by passing focus to the next component in the window.
28-66
Tab
Description: Tabs (or Tabbed Notebooks) allow you to subdivide the contents of a screen into logical groups or categories. They provide an aesthetic way of organizing large amounts of data into small spaces. This tool supports many features which are described in detail in More about tabs on page 28-69. Example:
Property
Value
Name
Enter a unique identifier to associate a name with the component on the screen. This name is used by external applications such as RAD to change the properties of the component dynamically. This property is optional. Enter the text for your tab heading in this property. Enter the array variable used as Input for the column. Horizontal position based on the components left edge. Vertical position based on the components top edge.
Caption Input
X
The Tools Palette
28-67
Property
Value
Elastic
28-68
Property
Value
Min Height
Used only when the Elastic property is set to Horizontal. If Min Height is set to the default value (-1), then the smallest height of the object will be equal to the value set for the Height property. If Min Height is set to any other value (for example, 20), the object will use this value for the minimum height of the object instead of the value set for the Height property. Allows you to override the default tabbing order within a form. By default, the TAB key navigates the focus on a form from top to bottom and left to right. However, if some components have a tabstop of non-zero, they are visited first, in ascending order. A semicolon-delimited list of the tab headings.
TabStop
Pages
More about tabs

A tabbed notebook can have two or more pages. Each page provides its own drawing canvas where you can insert other controls. Navigate to each page by selecting its tab with the mouse or from the keyboard by using the right and left arrow keys. You can assign tabstops to the components inside each page, but remember that the component with tabstop 1 is given focus first. This means that inserting a component with tabstop 1 inside a page will cause that page to be the first opened page when a screen is constructed. In Forms Designer, you create components inside each page simply by flipping to the correct page and drawing inside. You can paste components into a page by first selecting the notebook and clicking inside the target page before performing the paste command.
The Tools Palette
28-69
Wrapping Label
Description: The Wrapping Label tool allows you to place multiline text on a label. You can give titles to forms, give labels to components within the form, or otherwise place text on the form. Example:
The wrapping label tool can also be used to place a data field in a form that displays a QBE list. See More About Wrapping Labels on page 28-74.
Property
Value
Name
Enter a unique identifier to associate a name with the component on the screen. This name is used by external applications such as RAD to change the properties of the component dynamically. This property is optional. Enter the text for your wrapping label in this property. Enter the array variable used as Input for the column. Horizontal position based on the components left edge. Vertical position based on the components top edge. Height of the component in alignment grid units. Width of the component in alignment grid units. If Visible is set to false, the component is hidden from view when the form is displayed.
Caption Input
X
Height Width Visible
28-70
Property
Value
Visible Condition
Elastic
This property can have one of four values: Nonethe default. If the parent window is resized, the object will not resize with it. Horizontalautomatically adjusts the width of the object in proportion to the width of the parent window. Verticalautomatically adjusts the height of the object in proportion to the height of the parent window. Bothautomatically adjusts both the width and the height in proportion to the parent window. Min Width Used only when the Elastic property is set to Horizontal. If Min Width is set to the default value (-1), then the smallest width of the object will be equal to the value set for the Width property. If Min Width is set to any other value (for example, 20), the object will use this value for the minimum width of the object instead of the value set for the Width property. Used only when the Elastic property is set to Horizontal. If Min Height is set to the default value (-1), then the smallest height of the object will be equal to the value set for the Height property. If Min Height is set to any other value (for example, 20), the object will use this value for the minimum height of the object instead of the value set for the Height property. Select a font for your label from the drop-down list. Text color. Select from 17 available colors.
Min Height
Font ForeColor
The Tools Palette
28-71
Property
Value
ForeColor Condition
Enter a formula for evaluating the ForeColor property at run time. The result of this evaluation is used to override the value assigned to the property. Background color. The Opaque property must be set to Yes in order for the BackColor to have effect. Enter a formula that will override the BackColor property, if the conditions of the formula are met. See Specifying property conditions on page 24-3 for more information on constructing formulas. When set to Yes, applies bold to your label. Enter a formula that will override the Bold property, if the conditions of the formula are met. See Specifying property conditions on page 24-3 for more information on constructing formulas. When set to Yes, applies italics to your label. Enter a formula that will override the Italic property, if the conditions of the formula are met. See Specifying property conditions on page 24-3 for more information on constructing formulas. Enables the BackColor property. Allows you to increase or decrease the standard font size.
Bold Bold Condition
Opaque FontIncrease
28-72
Property
Value
FontIncrease Condition
Enter a formula that will override the FontIncrease property, if the conditions of the formula are met. See Specifying property conditions on page 24-3 for more information on constructing formulas. This property does not apply to labels.
When a screen component is associated with an array data structure, this property specifies the size of the scrolling region that is used to view array entries. For example, if a field is assigned an ArrayLength of 5, the form will stack five fields vertically to allow viewing of five array entries. A scroll bar appears beside the fields to allow viewing of the array entries. If ArrayLength is set to -1, the form dynamically creates as many fields as there are entries in the array.
OutputConv ArrayLength
If the Input data type is scalar, only a single Text Box is displayed. The default is 0, which means one vertical line of information is displayed.
The Tools Palette
28-73
More About Wrapping Labels

The Wrapping Label tool can also be used to create data fields in a form that contains a Query By Example (QBE) list. A QBE list contains fields (the dashed boxes under the column headings in the example below) that display data from the ServiceCenter database. The Wrapping Label tool allows you to create a field that will allow data to wrap to the next line when necessary.
To create data fields, use the Wrapping Label tool as follows: 1. Select the Wrapping Label tool and place a label component on the form. 2. Assign a variable to the Input property. You can then include this variable in a RAD program to dynamically fill data into the field.
28-74
OLE Container
Description: The OLE Container tool allows the user to attach a nonServiceCenter document (for example, from Microsoft Word or Microsoft Excel) to a ServiceCenter document such as an incident ticket or SLA agreement. In the example shown below, an Excel spreadsheet has been added to the Attachments tab of an incident ticket.
Example:
Property Name
Value
Enter a unique identifier to associate a name with the component on the screen. This name is used by external applications such as RAD to change the properties of the component dynamically. This property is optional. Enter the text for your Ole tab in this field. Enter a formula that will override the Caption property, if the conditions of the formula are met. See Specifying property conditions on page 24-3 for more information on constructing formulas.
The Tools Palette
28-75
Property
Value Enter the name of the appropriate database field or variable. This is not where the object is stored, but rather what field is used to store the relationship between the objects. For example, in the contacts file (contacts.g), the input value can be contact.name. This unique key allows each contact to have their own picture. For devices, you can use devtype to allow all PCs to have the same picture.
Input
Horizontal position based on the left edge of the component. Vertical position based on the top edge of the component. Height of the component in alignment grid units. Width of the component in alignment grid units. If Visible is set to false, the component is hidden from view when the form is displayed. Enter a formula that will override the Visible property, if the conditions of the formula are met. See Specifying property conditions on page 24-3 for more information on constructing formulas.
Determines the width and height of an object in relation to its parent window. his property can have one of four values:
Elastic
Nonethe default. If the parent window is resized, the object will not resize with it. Horizontalautomatically adjusts the width of the object in proportion to the width of the parent window. Verticalautomatically adjusts the height of the object in proportion to the height of the parent window. Bothautomatically adjusts both the width and the height in proportion to the parent window.
28-76
Property
Value
Min Width
Used only when the Elastic property is set to Horizontal. If Min Width is set to the default value (-1), then the smallest width of the object will be equal to the value set for the Width property. If Min Width is set to any other value (for example, 20), the object will use this value for the minimum width of the object instead of the value set for the Width property. Used only when the Elastic property is set to Horizontal. If Min Height is set to the default value (-1), then the smallest height of the object will be equal to the value set for the Height property. If Min Height is set to any other value (for example, 20), the object will use this value for the minimum height of the object instead of the value set for the Height property. Allows you to override the default tabbing order within a form. By default, the TAB key navigates the focus on a form from top to bottom and left to right. However, if some components have a tabstop of non-zero, they are visited first, in ascending order. Disables editing capabilities, providing only viewing access. When this property is set to true, the event value is sent to the RAD application when the field loses focus (when you leave the field). Refer to the Dynamic RAD documentation for further information. A straight number field that sets the absolute size of an attachment for the form being modified. A condition statement that varies the maximum allowed size of an attachment based on the capabilities of a user. For example, a system administrator could have a higher limit than a manager, who in turn could have a higher limit than a help desk user
Min Height
TabStop
ReadOnly Focus Out Event
MaxAttachSize MaxAttachSize Condition
The Tools Palette
28-77
More about OLE Containers

OLE Containers allow you to drag and drop or copy and paste files into ServiceCenter. When you open a record that contains an OLE Container, you can double-click any attachment and Windows will open that file in the appropriate application. Following are examples of how OLE Containers can be used: To attach a Microsoft Word document describing the original agreement between parties involved in a Service Level Agreement to the SLA form. To attach a spreadsheet which is causing problems directly to the problem ticket opened to deal with the spreadsheet. The OLE Container will work only on 32-bit Microsoft Windows platforms. The Container is a separate input field that can contain only attachments. OLE documents are stored in the ServiceCenter repository and are accessible to all ServiceCenter users.
28-78
Chapter 29 The Form Wizard

The Form Wizard allows you to create forms based on a particular Database Dictionary. You can automatically create both table-type QBE lists and singlerecord display forms. This feature is used only to create new forms and cannot be used to modify existing forms. This chapter describes how to: Access the Form Wizard. Create a form using the Form Wizard.
The Form Wizard
29-1
Accessing the Form Wizard

To access the Form Wizard: 1. Click the Toolkit tab located on the Main Menu. The selections available in the Toolkit are displayed. 2. Click the Forms Designer button. The initial Forms Designer screen appears. 3. Enter a name for the form in the Form field. 4. Click the New button. 5. The system asks if you want to use the Form Wizard to create your new form. 6. Click Yes to use the Form Wizard. 7. The system asks you to enter the name of the file for which you want to create a format. Click the down arrow button and select a name from the drop-down list. For example, select incidents. 8. Click OK or press Enter. The system asks what type of format you want to create. 9. Click the down arrow button and select a format from the drop-down list. Choose List of Records or Detail of a Single Record. 10. Click OK or press Enter.
29-2
The fd.wizard.show.g form is displayed (figure 29-1).
Figure 29-1. Fd.wizard.show.g Form
The Form Wizard
29-3
Creating a Form Using the Form Wizard

The following example continues the process of using the Form Wizard. In the example, Detail of a Single Record was chosen as the type of format to use (see the dialog box on page 29-2). To use the Form Wizard: 1. With the fd.wizard.show.g form displayed (refer to Accessing the Form Wizard on page 29-2), click in the fields you want to modify. All of the fields except Control Type are text boxes, which means you click in the table cell and type a new value to change the field. For example, change the Field Label for the format entry to Format Name.
Figure 29-2. Fd.wizard.show.g Form
2. Change the true statement to false if you do not want a particular field included on the completed form.
29-4
3. Click Proceed. The form is displayed in Forms Designer.
Figure 29-3. New Form
4. Click OK to view the completed form. 5. Click OK again to save the form.
The Form Wizard
29-5
29-6
Chapter 30 Tutorial: Creating a New Form

This chapter guides you through the process of creating a new form in Forms Designer. As you create the form, feel free to experiment with the designer elements. If you are not sure what a particular property does, you can try different settings before entering the final value to see what happens. This will make your work in Forms Designer more informative.
Tutorial: Creating a New Form
30-1
The Practice Form

Figure 30-1 shows the practice form department as it will appear when completed. Refer to this illustration as your guide while creating the form.
Figure 30-1. The Completed Practice Form
Placing design objects on the practice form

Follow these steps to place design objects on the practice form: 1. Select the tool for the object you want to create. 2. Use your mouse to draw the object on the form. Approximate the size and position of the object based on how it appears in the finished form. 3. Use the Properties Window to enter the prescribed values for the object. If you wish, experiment with any of the properties/values before finalizing the object.
Creating the Form

The following steps describe how to create the practice form department. These steps begin at the point where you have accessed Forms Designer and a blank Drawing Canvas is displayed along with a Properties Window and Tools Palette. 1. Add a Picture.
Property X Y Height Width Bitmap AutoResize Frame 2. Add a Label.
Value 49 5 4 46 sc no no
Property Caption X Y Height Width Bold Justification FontIncrease
Value Department Information 45 10 3 62 Yes Center 8
30-3
3. Add a Bevel (around the Picture and Label).
Property X Y Height Width 4. Add a Label.
Value 11 3 12 117
Property Caption X Y Height Width Justification
Value Dept Code 15 18 2 19 Left
5. Add a Text Box (next to Dept Code).
Property Input X Y Height Width
Value dept.code 30 18 2 27
30-4
6. Add a Label.
Value Manager 15 22 2 12 Left
7. Add a Fill Box (next to Manager)
Property Input X Y Height Width ButtonID ButtonBitmap 8. Add a Label.
Value manager 30 22 2 27 9 1

Value Office Hours 94 17 2 25 Center

30-5
9. Add a Text Box (under Office Hours).
Value start.time 94 19 2 12
10. Add a Text Box (under Office Hours).
Value end.time 108 19 2 12
11. Add a Radio Button.
Property Caption Input X Y Height Width TextLocation Value

30-6
Value Main Office office 18 27 2 25 Right main

12. Add a Radio Button.
Property Caption Input X Y Height Width TextLocation Value
Value Annex A office 18 30 2 22 Right annexa
13. Add a Frame (around the two Radio Buttons).
Property Caption X Y Height Width Bold Justification
Value Location 15 25 8 29 Yes Left
14. Add a Check Box.
30-7
Property Caption Input X Y Height Width TextLocation 15. Add a Button.
Value Special special 18 34 2 21 Right
Property Caption X Y Height Width ButtonID Justification 16. Add a Label.
Value List 70 18 2 14 0 Center
Value Description 83 23 2 30 Center
30-8
17. Add a Multi Line Text Box.
Property Input X Y Height Width ReadOnly Property Caption X Y Height Width
Value description 70 26 10 42 No Value (leave blank) 11 16 22 117
18. Add a Frame (around all the objects from steps 4 - 17).
30-9
Saving the Form and Creating a File

Once you have created the new form you need to: Save the form. Create a file for the form.
Saving the form

Follow these steps to save the form: 1. Click OK. 2. The tools and properties windows disappear, leaving only the form. Click OK. 3. The system prompts you to enter the name for the record. Enter the name department and click OK again. The system returns you to the initial Forms Designer screen. You are now ready to create a file for the form.
30-10
Creating a File
To create a file for a new form: 1. For this example, use the form, department, created in the last section. In the initial Forms Designer screen (figure 30-2), type the form name, department. Press Enter.
Figure 30-2. Initial Forms Designer Screen
2. The department form is displayed. Select Create File from the Options menu. The system prompts you to enter the filename for the form. Note that a default filename is provided. This default filename is the same as the forms name (department). 3. Click OK to use the default filename of department.
30-11
The system advances you to the file that has been created for department (figure 30-3).
Figure 30-3. The File for the Department Form
4. Verify that the values in the file are correct. If you need to make any changes, click the Edit button. 5. Click OK to save the file. This completes the process of creating a new form, saving the form, and creating a file for the form.
30-12
Modifying an Existing Form

To modify an existing form in Forms Designer: 1. From the initial Forms Designer screen (figure 30-4) you can retrieve an existing form in one of two ways: If you know the name of the form, enter the name in the Form text box and press Enter. If you only know a portion of the name, you can type the partial name and press Enter to narrow your search. To search for the form, click the Search button. A QBE list is displayed from which you can select the name of the form.
As an example, enter the form name department and press Enter.
Search Figure 30-4. Initial Forms Designer Screen
30-13
The department form (figure 30-5) is displayed.
Figure 30-5. The Department Form
2. Click the Design button to activate the Forms Designer elements. 3. Modify the form as needed using the Tools Palette and Properties Window. 4. Click OK to preview your changes. 5. Click OK to save the form. 6. If you accessed the form from a QBE list, you will be returned to the list. Click the Back button to return to the initial Forms Designer screen.
30-14
Using the Options menu

The Options menu (figure 30-6) allows you to perform several functions with your form.
Figure 30-6. The Options Menu
Below is a description of each item in the Options menu: Option Description _____________________________________________________________ Copy/Rename Help Topic Filename Create File Copy or rename the form and (optionally) its associated link record or format control record. Reserved for future use. Set or change the file name associated with the form. Create a database dictionary for the form.
Validate Format Displays the Input values (as they appear in the database dictionary) for each field in the form.
30-15
(Options Menu Continued) Option Description _____________________________________________________________ dbdict Runs the Database Dictionary Maintenance utility for the file name associated with the form. Runs the Database Manager using the form and its associated database dictionary. Format Control Runs the Format Control Maintenance utility. Link Format Detail Runs the Link Maintenance utility. Displays text-based format detail information. Connects you to the Format Control Wizard where you can establish format control for a form. Sub Form Editor Allows you to edit any sub forms that are part of a form.
Database Manager
Format Control Wizard
30-16
Chapter 31 Designer Tips

This chapter provides additional tips for designing forms that meet your specific needs. The following topics are covered: Form style guidelines ServiceCenter and bitmaps Graphics and animation
Designer Tips
31-1
Form Style Guidelines

This section outlines the style guidelines used by Peregrine Systems, Inc. in form design. Users who modify their forms according to these guidelines can ensure a consistent look and feel when compared with the system as shipped. These guidelines were established with the goal of generating forms which display well on a variety of platforms and with different screen resolutions and fonts.
Understanding ServiceCenter screen layouts

The size of ServiceCenter forms and the objects on them are defined in terms of grid units. For instance, a combo box may be defined to be 36 units wide and 2 units tall. Objects are also placed on forms using the same units, for example, the same combo box may have its upper left corner at a location 5 units to the right of the form edge and 4 units beneath the top of the form. The size of a ServiceCenter grid unit varies depending upon the currently selected ServiceCenter font. The grid unit is always defined as being half as wide as the lower case e in the current font, and half as tall as the lower case e in the current font. Thus, in a font whose letter e is 8 pixels wide by 12 pixels tall, the ServiceCenter grid unit will be 4 pixels wide and 6 pixels tall. Changing the systems font will change the size of a form on the screen. Just as importantly, it may change the relative shape of the objects therein. If a screens grid unit goes from 4x4 to 6x8, then objects on the screen will become 50% taller, but will double in width. Thus, the screen will appear to stretch and will have different proportions than it did originally. An important point to recognize is that Windows true-type fonts are nondeterministic. Each video driver manufacturer can bundle its own hardware mapping of common fonts, and most modern video cards do so. Many manufacturers improve upon the base Microsoft Windows definition of what constitutes a particular font. Thus, the letter e in Arial 8 pt. bold when displayed at 640x480 on one video card may have a different metric than the same letter displayed at the same resolution on a different video card.
ServiceCenter default fonts

By default, ServiceCenter always launches in MS Sans Serif 8 pt. on a Microsoft Windows client. On other platforms, ServiceCenter uses Helvetica 8 pt. Bold. The only exception to this rule is that ServiceCenter will default to Arial 7 pt. Bold if launched on a 640x480 machine. Users can, of course,
31-2
change this font after they log into ServiceCenter and their preference will be saved.
Using the Courier font

It is best to initially lay out your form using the Courier font. This font is a fixed font that offers the widest possible character spacing. Otherwise, you run the risk of creating objects that are too small or that overlap. For example, suppose you create the label below using the Times font. The caption fits well within the labels boundaries.
However, Times is a proportional font that compresses character spacing. Later, if a user views the label using a wider system font such as Courier, the caption will not fit.
Style guidelines
Form Size The right edge of any form should be at grid unit 156. The bottom of any form should be at grid unit 42. Forms which follow this guideline will fit in the default fonts at 640x480 and 800x600. Additionally, these forms provide enough room along the edges for a scroll bar if required. Label Text All label text is to be black. Labels are to be left aligned and end in a full colon.
Designer Tips
31-3
Combo Boxes Combo boxes are to have 8 drop down lines unless the drop-down set contains a fixed number of elements <=7, in which case the combo box is to have box lines equal to the number of elements in the drop down set. Check Boxes Check boxes are to have label text on the right. Find/Fill Boxes Find and fill boxes are to use bitmap id=7. Under NO circumstances should a find or fill use the down array bitmap that makes the find or fill look like a combo box. Tabbed Notebook Forms with tabs should include a header section which is not part of the tab. This header should include important description information about the record. For example, problem tickets should show, at a minimum, the problem number. Do not nest tabs within tabs. Buttons Navigational buttons on forms should be placed along the left edge or top border of the form. No button that is on the tool tray should have a replicate button on the form itself. QBE Formats All GUI mode QBE formats are to use the new table-type QBE format. Column headings should follow in book title capitalization rules, for example, File Name not file name or file.name. Menu Labels Labels on menu forms (for example, menu.gui.home) should have a font increase of 2. Tab Stops Read-only fields should have a tab-stop value of -1 to prevent users from tabbing into them.
Rules of good screen design

Avoid excessive color. The human eye is keyed to look for edges in black and
white, and whole images in color. If a form contains too many different colors, the human eye usually ceases to view it as text and instead tends to view it as art. Avoid pale colors. The human eye keys for contrast. Pale colors such as yellow, pink, and so forth do not contrast well enough to be readily visible. Line objects up, even if it means stretching some objects bigger than you think they should be. When the human eye scans an object, it instinctively follows edges. If most of the edges in your form line up vertically, then the form will appear neat and organized. In contrast, failure to line up the edges of your controls can make your forms appear sloppy. Cluster similar data together. If you have ten fields that all deal with problem ticket update history, place them near one another on the form. This simplifies the process of finding data for your user. Use tabs, frames, and bevels to group data into discreet units. Large forms with many fields can seem overwhelming to many users. By drawing enclosing shapes around groups of objects, you allow the human brain to process the set of container objects rather than the full set of on-screen objects. This makes the screen appear simpler. Use combo boxes, not Finds. If your users are to select from a set of n objects, and n is less than or equal to 100, then use the global list manager to build a list and use that list and a combo box to allow the user choices. Find and Fill are unfamiliar processes for most users and should be avoided where possible. Do not use a tabbed notebook unless necessary. The tabbed notebook breaks up data so that users cannot view it all at once. A single form is preferable to one with tabs. Use tabs instead of views. Views require that users change screens to see extra data. A tabbed form is preferable to a form with multiple views.
Designer Tips
31-5
ServiceCenter and Bitmaps

ServiceCenter can store bitmaps directly in the ServiceCenter database system, regardless of the type of physical database being used. Thus, ServiceCenter can store bitmaps natively in Oracle, Sybase, SQL Server, DB/2 or the P4 system. These bitmaps are stored inside of a file named SYSBLOB. The structure of the SYSBLOB file is as follows: Field Name Application Topic Type Segment Data Description. The table with which this bitmap is associated. The key value from the table with which this bitmap is associated. The type of data stored here. Bitmaps are type 3. The segment counter for this section of the bitmap. The data block for this section of the bitmap.
Bitmaps are typically large objects, i.e., > 32 KB. In order to store large objects such as bitmaps inside the ServiceCenter system, these objects are broken down into multiple 2 KB pages and stored sequentially as multiple records in the SYSBLOB table. Thus, a bitmap that is 8 KB in size will actually have 4 entries in the SYSBLOB table: segment 0,1,2,3. Each segment will contain 2 KB of the bitmap. This data will be stored in order so that segment 0 contains the first 2 KB, segment 1 the next 2 KB, and so forth. Each bitmap is associated with a particular table and is further associated with a particular key value from the table. If this key value is unique, then the bitmap will display for only one record. However, it is possible to associate a bitmap with a non-unique key, in which case all records in a particular table which have that key value will share that bitmap. For example, a bitmap associated with the Type field in the device table would be stored only once, but displayed for every device of a particular type.
Adding a bitmap to an object

Use the following procedure to add a bitmap: 1. Access a form. 2. Open Forms Designer. 3. Using the Picture tool, draw a box on the form that is the size and shape of the bitmap you would like displayed.
31-6
4. Set the Input property of the box to the key field with which you would like to associate this bitmap (for example, to associate a bitmap with the contact.name field in the contacts file, set the image controls input to contact.name. 5. Save the form. Your form is now ready to accept bitmaps. 6. Bring up the form in Database Manager or another editor. 7. Place your cursor over the box you have drawn to contain the bitmap. Right click to bring up a menu and select Insert bitmap from the menu. 8. A new entry in the right click menu at the bottom will read Insert bitmap. 9. In the file location box that appears, select a bitmap image to insert. 10. Save the record, and the associated bitmap will be saved to the file as well. Note: RLE or other compressed bitmaps are not supported. Only native Microsoft Windows DIB bitmaps are supported.
Designer Tips
31-7
Graphics and Animation

You can use Microsoft Windows bitmaps to customize ServiceCenter with still images, 3D effects, and animation. Images can be mapped to pictures and buttons. The BMP file format supports many different levels of color resolution. Forms Designer supports them all, however 4-bit color (16 colors) is the most efficient for Forms Designer to display. You can use bitmaps with 256 or more colors, but Forms Designer must dither them at runtime. This extra processing can degrade the appearance of the image and degrade client performance.
Optimum performance and image appearance

For optimum performance, use a graphics utility to convert 256 and highercolor bitmaps to 16 colors before using them in Forms Designer. If the size of a bitmap exceeds the dimensions of its button or picture object, Forms Designer may resize the image at run time to fit the object. This extra processing at runtime can degrade the appearance of the image and degrade client performance. For optimum performance, use objects that are at least as large as the images they display. Another option is to use the graphics utility to resize large images before using them in Forms Designer.
Text and graphics

To include text and graphics in an object, use a graphics editing package to add the text and graphics to the Microsoft Windows bitmap.
31-8
Index
A
accessing Forms Designer, 26-1 Accessing the Document Engine, 1-2 adding records, 5-2, 15-3 mass adding using literal value, 5-2 single record, 4-1 structures to the Database Dictionary, 10-9 additional file queries process (Format Control), 143, 16-33 examples, 16-32 fields, 16-29 additional options, 14-4, 16-53, 17-1, 17-4, 17-12, 17-19 example, 16-58 fields, 16-55 Administration Mode, 2-2 animation, 31-8 applications called from Format Control axces.fax, 22-10 axces.page, 22-8 axces.write, 22-9 database, 22-7 determining parameters, 22-13 fill.fc, 22-2 fingerprint, 22-11 getnumb.fc, 22-3 message.fc, 22-4 post.fc, 22-2 query.stored, 22-7 sort.array, 22-11 validate.fields, 22-6 arrayed structures, 16-24 as.copy, 17-8 parameters, 17-8 as.delete, 17-9 parameters, 17-9 as.get.name, 17-15 as.insert, 17-10 parameters, 17-10 as.move, 17-11 example, 17-12
parameters, 17-11 as.options, 17-2, 17-3 example, 17-4 parameters, 17-3 as.sort, 17-15 parameters, 17-16 subformats, 17-2, 17-9 user options copy, 17-7, 17-14 delete, 17-7, 17-14 insert, 17-7, 17-14 move, 17-7, 17-15 replace, 17-8, 17-15 arrays, 10-5 arrayed structure maintenance utility, 10-20 arrayed structures, 10-14 denulling, 16-26 editing, 16-1, 19-6 editor, 17-1 expanding, 4-7 fields, 9-2 sorting, 17-23 to 17-28 auditing audit log, 6-21 accessing, 6-6 audit.g, 6-23 fields, 6-8 audit specifications entry, 6-9 audit specifications file, 6-3 audit.compare, 6-17 audit.compare application, 6-17 auditspecs, 6-5 error correction, 6-9 triggers example.audit.trigger.update, 6-17
B
backups, 11-2 basic.employee.info structure, 10-13 Bevel tool, 28-16 boolean fields, 14-7, 16-31, 16-35 box properties, 27-6 Button tool, 28-12 I-1
Index
C
calculations process (Format Control), 14-3, 16-11, 16-21, 16-22, 16-23, 16-33 canvas invisible grid, 25-3 capability words logical operators, 3-4 Change Management approvals Format Control record, 21-3 changes opening, 19-19, 19-30 detail record, 21-3 master record, 21-2 processing considerations, 21-2 character fields, 9-5, 10-4 character strings identifying, 3-29 to 3-30 specifying length, 3-30 Chart tool, 28-55 chart tool ColorList, 28-58 ColorScale, 28-58 Check Box tool, 28-33 Clear option, 3-17 colors on charts, 28-58 Combo Box tool, 28-41 command line, 9-5 common properties, 27-4 conditional statements dynamic functions, 24-4 field comparisons, 24-3 field value matching, 24-4 Courier font, 31-3 creating new forms, 26-2 creating a file, 30-11 creating a new form, 26-2, 30-1 Creating an oncall schedule, 12-14 Creating Objects, 1-2 Creating Processes, 1-11 Creating States, 1-9 customer support, Preface-2
D
data creating fields, 28-7 data fields creating, 28-7, 28-74 data fields, creating, 28-74 data map, 5-27 unload script utility, 8-4, 8-5, 8-7, 8-8 data pools, 11-11 I-2
data types, 9-5 array, 9-5 character, 9-5 changing to number, 10-39 date/time, 9-5 expression, 9-5 logical, 9-5 number, 9-5 record, 9-5 structure, 9-5 database loading, 5-58 to 5-64 background, 5-62 to 5-64 foreground, 5-58 to 5-62 messages, 5-60 to 5-62 regenerating keys, 7-5 to 7-7 retrieving records all, 3-12 using array fields, 3-15 to 3-16 using multiple fields, 3-13 to 3-14 scheduling regeneration, 7-6 to 7-7 unloading records, 5-22 Database Dictionary only, 5-45 from multiple databases, 5-38 messages, 5-25 to 5-27 multiple records from one database QBE method, 5-29 value list method, 5-33 single records, 5-22 unloading reports, 5-48 Database Dictionary, 5-45 accessing, 9-3 from Forms Designer, 9-3 to 9-5 backing up a file, 11-2 copying, 11-1 data pools, 11-11 deleting, 11-7 field names graph.of.unavailibility-array, 10-16 index pools, 11-11 level, 9-5 pools, 11-11 to 11-12 record description, 9-2 renaming, 11-5 resetting records, 11-8 Database Manager accessing, 2-2 administration mode, 2-2 character strings identifying, 3-29 to 3-30 specifying length, 3-30 queries using functions, 3-27 to 3-31 query expressions, 3-25 to 3-27 Database manager System Tailoring, Vol. 1
standard mode, 2-2 date/time fields, 9-5, 10-4 default fonts in ServiceCenter, 31-2 deleting objects, 28-3 deleting an object, 28-3 descriptor, 10-3 field, 10-1 deselecting objects, 28-2 design guidelines, 31-4 process, 26-4 tips, 31-1 Document Engine Standard Variables, 1-14 drawing canvas introduction to, 25-2 dynamic functions, 24-4 dynamic view dependencies, 24-1
label, 10-5 logical, 9-5, 10-5 number, 9-5, 10-4 record, 9-5, 10-5 structure, 9-5, 10-5 Database Dictionary data types, 9-5 descriptor field, 10-1 field name, 9-4 index, 9-5 keys, 9-5 deleting, 10-47 modifying, 10-36 to 10-41 scalar, 10-2 searching for, 11-13 unload script utility, 8-3 to 8-4 value matching, 24-4 files arrayed structure maintenance utility, 10-20 commonly used in unload script utility, 8-6 to 87 creating from Forms Designer, 30-11 maintenance regenerating keys, 7-5 to 7-7 reset a database, 7-1 problem, 10-19 probsummary, 10-19 Fill Box tool, 28-26 font properties, 27-5 fonts, 31-2 default in ServiceCenter, 31-2 properties in Forms Designer, 27-5 form style guidelines, 31-2 Form Wizard, 25-7 accessing, 29-2 creating a form, 29-4 introduction, 29-1 Format Control accessing from a menu, 15-2 from Forms Designer, 15-1 creating records, 17-24, 18-13, 19-16, 19-25 editing records, 16-12 privileges, 16-35 process views, 14-4 processes additional file queries, 14-3, 16-29 additional options, 14-4, 16-53 calculations, 14-3, 16-11, 16-21, 16-33 examples, 16-23 fields, 16-22 initializations, 14-3, 16-3 fields, 16-4 security, 14-4, 16-35, 16-36 I-3
E
Edit Area list, 27-3 enduser file fields, 6-6 equal to, 3-3 errors messages, 20-1 record/key conflicts, 4-6 example.audit.trigger.update, 6-17 expressions boolean fields, 14-7 definitions primary file, 14-6 semicolon, 14-6 statements, 14-6 variable, 14-6 error messages, 20-1
F
field comparisons, 24-3 field value matching, 24-4 fields adding, 10-1 arrays, 9-2, 10-5 changing data types, 10-39 comparisons, 24-3 data types, 10-4 array, 9-5 arrays, 10-5 character, 9-5, 10-4 date/time, 9-5, 10-4 expression, 9-5, 10-5 Index
selecting a view, 14-4 subroutines, 14-4, 16-41 validations, 14-3, 16-13 views, 16-62 QBE forms, 16-62, 19-6 creating, 16-8, 16-64 default, 16-7 scripts, 16-9 forms creating, 30-1 modifying, 30-13 protecting in unload script utility, 8-7 to 8-8 saving, 30-10 searching for, 26-2 style guidelines, 31-2, 31-3, 31-4 Forms Designer accessing, 26-1 accessing Database Dictionary, 9-3 to 9-5 bevel tool, 28-16 button tool, 28-12 case sensitivity, 27-3 chart tool, 28-55 check box tool, 28-33 combo box tool, 28-41 creating files, 30-11 new forms, 30-1 practice forms, 30-3 deselecting objects, 28-2 design process, 26-4 design tips, 31-1 dialog box, 26-1 fill box tool, 28-26 Form Wizard accessing, 29-2 creating a form, 29-4 introduction, 29-1 frame tool, 28-19 graphics and animation, 31-8 introduction, 25-1 introduction to, 25-1 invisible grid, 25-3 label tool, 28-4 lassoing an object, 28-2 modifying a form, 30-13 multi line text box, 28-23 OLE container tool, 28-75 options menu, 30-15 picture tool, 28-30 pointer tool, 28-2 positioning an object, 28-2 preview of the design process, 26-4 properties, 27-4 to 27-7 box, 27-6
common, 27-4 conditional statements, 24-3 Edit Area list, 27-3 entering a value manually, 27-2 fonts, 27-5 introduction, 25-6, 27-1 sizing the properties window, 27-2 window, 27-1 to 27-3 properties window selecting a property, 27-2 radio button tool, 28-37 resizing an object, 28-3 saving a form, 30-10 selecting objects, 28-2 sizing on the drawing canvas, 25-4 style guidelines, 31-2, 31-3, 31-4 subformat tool, 28-50 tab tool, 28-67 table tool, 28-59 text box tool, 28-8 validating formats, 19-11 wrapping label tool, 28-70 Frame tool, 28-19 functions add field function, 10-1 denull, 14-6 index, 14-6 lng, 14-7 nullsub, 14-7 operator, 14-7 str, 14-7 substr, 14-7 tod(), 14-7 val, 14-7, 17-3, 17-9
G
graph.of.unavailability, 10-16 graphics and animation, 31-8 grid units, 31-2
I
importing Import/Export utility, 5-22 index number, 9-5 pools, 11-11 initialization expressions, 16-10, 17-17 incorrect, 20-1 initializations process (Format Control), 14-3, 16-3 fields, 16-4 invisible grid, 25-3 IR Expert, 3-17
I-4
K
keys, 3-1, 9-2, 9-5 adding, 10-26 first key, 10-26 keys to bottom of key list, 10-32 deleting, 10-50 inserting, 10-29 modifying, 10-42 regenerating, 7-5 to 7-7 types, 10-27 knowledge requirements, Preface-2
O
Objects about, 1-2 field descriptions, 1-3 OLE Container tool, 28-75 OLE container tool, 28-78 On Call Scheduling, 12-12 oncall schedule creating, 12-14 modifying, 12-15 Oncall Schedule Panel fields, 12-13 operators logical, See logical operators relational, See relational operators operators (symbols) unload script utility, 8-5 Options menu, 30-15
L
Label tool, 28-4 lassoing an object, 28-2 link records creating, 19-13 links records fields, 19-2 fields in link line definition file, 19-5 link line definition file, 19-4 posting, 19-2 system tray in link line definition file, 19-6 logical fields, 9-5, 10-5 logical operators, 3-2, 3-3
P
paging, 6-2 palette, tools, 25-5 parameters application, 22-13 Peregrine Systems, Inc., contacting, Preface-2 performance, graphics, 31-8 Picture tool, 28-30 Pointer tool, 28-2 pools Database Dictionary, 11-11 to 11-12 positioning an object, 28-2 posting additional options set up, 19-9 additional options setup, 19-9 automatic confirmation function, 19-34 example, 19-11 compared with Fill, 19-1 confirmation function, 19-33 link records, 19-2 fields, 19-2 link line definition file, 19-4 post.fc, 19-9 subroutines set up, 19-17 user options confirmation function, 19-34 example, 19-24 variables, 19-7 printing records, 4-4 privileges, 16-35 Problem Management I-5
M
Marquee tool, 28-47 marquees tool, 28-47 menus accessing Database Dictionary, 9-5 messages database unload, 5-25 to 5-27 loading, 5-60 to 5-62 modifying a form, 30-13 msglog file, 10-19 Multi-Line Text Box tool, 28-23
N
no duplicates, 10-27 no nulls, 10-27 not equal to, 3-27 Notification Definitions, 12-20 Notification Messages, 12-9 Notification Record adding new fields, 12-6 editing, 12-4 Notifications File, 12-2 nulls & duplicates, 10-27 number fields, 9-5, 10-4 Index
alert records, 21-7 eventout records, 21-4 problem file, 10-19 probsummary file, 10-19 processing considerations, 21-1 Process Panel field descriptions, 1-12 Processes, 1-11 Properties Window, 25-6, 27-1 to 27-7 box properties, 27-6 common properties, 27-4 Edit Area list, 27-3 entering a value manually, 27-2 font properties, 27-5 selecting a property, 27-2 sizing, 27-2 using the window, 27-1 property conditions, 24-3 purge/archive accessing, 10-19
Q
QBE list, 3-1 defined, 3-1 forms, 16-62, 19-6 creating, 16-8, 16-64 default, 16-7 selecting views in Format Control, 14-4 query method, 5-33 queries character string length, 3-30 greater than/less than, 3-27 to 3-29 query window, 3-1 accessing, 3-18 unload script utility, 8-4 to 8-5 using functions, 3-27 to 3-31
R
RAD data types label, 10-5 record, 10-5 Radio Button tool, 28-37 records adding, 4-1 mass adding, 5-2 using a variable, 5-6 with literal value, 5-2 multiple records, 5-2 Clear option, 3-17 counting in QBE list, 5-20 Database Dictionary, 9-2 deleting, 4-2, 5-18 I-6
duplicating, 4-1 editing, 16-12 key conflicts, 4-6 printing, 4-4, 5-19 purging, 8-15 to 8-16 record level options, 4-7 resetting, 11-8, 11-9 retrieving all records, 3-12 complex query expression, 3-25 to 3-27 logical operators, 3-3 query window, 3-1, 3-18 query window, using, 3-19 relational operators, 3-2 to 3-3 equal to, 3-6 to 3-7 greater than, 3-7 to 3-8 less than, 3-9 like, 3-10 not, 3-10 starts with, 3-5 to 3-6 simple query expression, 3-20 using array fields, 3-15 to 3-16 using multiple fields, 3-13 to 3-14 within a database, 3-1 unloading, 8-13 to 8-14 updating multiple records, 5-10 multiple records with a literal value, 5-10 multiple records with a variable, 5-12 single record, 4-2 relational operators, 3-2 to 3-3 equal to, 3-3, 3-6 to 3-7 greater than, 3-3, 3-7 to 3-8, 3-27 less than, 3-9, 3-27 like, 3-10 not, 3-10 starts with, 3-5 to 3-6, 3-10, 3-20, 3-21, 3-26 reserved words, 10-2 resizing an object, 28-3
S
saving forms, 30-10 saving a new form, 30-10 SCAutomate page messages, 21-6 scheduling regenerating a database, 7-6 to 7-7 reset a database, 7-3 scripts, 16-9 unload creating, 8-2 to 8-8 editing, 8-9 validating, 8-11 to 8-12 System Tailoring, Vol. 1
searching for forms, 26-2 security process (Format Control), 14-4, 16-35, 1636 selecting objects, 28-2 sequential numbering data types, 18-2 getnumb.fc, 18-1, 18-3, 18-10 number file, 18-10 fields, 18-11 parameters, 18-3, 22-3 prefixes, 18-2, 18-12, 18-13 simple, 18-5 suffixes, 18-2, 18-12, 18-13 ServiceCenter loading database, 5-58 to 5-64 background, 5-62 to 5-64 foreground, 5-58 to 5-62 messages, 5-60 to 5-62 reserved words, 10-2 sizing forms, 25-4 sizing the Properties Window, 27-2 sort.array, 17-23 example, 17-23 standard, 2-2 Standard mode, 2-2 statements not, 3-27 OR/AND, 3-25 to 3-26 States, 1-9 field descriptions, 1-10 structures, 10-9 adding arrayed structures, 10-9 arrayed structures, 10-14 basic employee.info, 10-13 fields within, 10-11 style guidelines, 31-3 Subformat tool, 28-50 subformats, 8-1, 8-3, 8-7, 8-8 subroutines, 16-41, 18-1, 18-13 to 18-14, 21-5 fields, 16-42 parameters, 16-43 process in Format Control, 14-4
tools palette introduction to, 25-5, 25-7, 28-1 reference, 28-1 Tools Palette Bevel tool, 28-16 Button tool, 28-12 Chart tool, 28-55 Check Box tool, 28-33 Combo Box tool, 28-41 Fill Box tool, 28-26 Frame tool, 28-19 introduction to, 28-1 Label tool, 28-4 Marquee tool, 28-47 Multi-line Text Box tool, 28-23 OLE Container tool, 28-75 Picture tool, 28-30 Pointer tool, 28-2 Radio Button tool, 28-37 Subformat tool, 28-50 Tab tool, 28-67 Table tool, 28-59 Text Box tool, 28-8 Wrapping Label tool, 28-70 tools palette, 25-5 trigger.invoke.auditor, 6-17 triggers example.audit.trigger.update, 6-17 trigger.invoke.auditor, 6-17 tutorial, creating a new form, 30-1
U
unique, 10-28 unload script utility commonly scripted files, 8-6 to 8-7 creating an unload script, 8-2 to 8-8 editing records, 8-9 fields, 8-3 to 8-4 introduction, 8-1 protected formats, 8-7 to 8-8 purging records, 8-15 to 8-16 unloading, 8-13 to 8-14 validating scripts, 8-11 to 8-12 updating records, 4-2
T
tab pages, 28-69 Tab tool, 28-67 tab tool, 28-69 Table tool, 28-59 table tool, 28-66 tabs navigating, 28-69 technical support, Preface-2 Text Box tool, 28-8 Index
V
validation formats, 19-11 unload scripts, 8-11 to 8-12 validations process (Format Control), 14-3, 16-13 examples, 16-15 fields, 16-14 I-7
validity, 16-13 value-list method, 5-33 views Format Control processes, 14-4 views process (Format Control), 16-62 fields, 16-63
W
Wrapping Label tool, 28-70
X
X coordinates, 25-3
Y
Y coordinates, 25-3
I-8

Sct4 System Tailoring Vol.1

Загружено:

Сведения о документе

Исходное описание:

Авторское право

Доступные форматы

Поделиться этим документом

Поделиться или встроить документ

Параметры публикации

Этот документ был вам полезен?

Это неприемлемый материал?

Авторское право:

Доступные форматы

Sct4 System Tailoring Vol.1

Загружено:

Авторское право:

Доступные форматы

ServiceCenter

This edition applies to version 4.0 of the licensed program ServiceCenter

Contacting Peregrine Systems, Inc.

System Tailoring, Vol. 1

Knowledge Requirements .................................................................................................Preface-ii Contacting Peregrine Systems, Inc. ..................................................................................Preface-ii

Chapter 1: The Document Engine

Chapter 2: Introduction to the Database Manager

Chapter 3: Record Use

System Tailoring, Vol. 1

Chapter 4: Single Record Functions

Chapter 5: Multiple-Record Functions

Chapter 6: Database Record Auditing

Chapter 7: File Maintenance

Chapter 8: Unload Script Utility

Chapter 9: Introduction to the Database Dictionary

Chapter 10: Adding and Modifying

Chapter 11: Advanced Operations

System Tailoring, Vol. 1

Chapter 12: Notification Engine

Chapter 13: Introduction to Format Control

Chapter 14: What is Format Control?

Chapter 15: Getting Started

Chapter 16: Format Control Processes

System Tailoring, Vol. 1

Chapter 17: Array Maintenance

Chapter 18: Sequential Numbering for Format Control

System Tailoring, Vol. 1

Chapter 19: Posting

Chapter 20: Error Messages Chapter 21: Special Processing Considerations

Chapter 22: Common Applications Called from Format Control

System Tailoring, Vol. 1

Determining Parameters .................................................................................................................22-13

Chapter 23: Introduction to Forms Designer

Chapter 24: Dynamic View Dependencies

Chapter 25: Forms Designer Elements

Chapter 26: The Forms Design Process

Chapter 27: The Properties Window

Chapter 28: The Tools Palette

Chapter 29: The Form Wizard

Chapter 30: Tutorial: Creating a New Form

Chapter 31: Designer Tips

System Tailoring, Vol. 1

Chapter 1 The Document Engine

The Document Engine

Accessing the Document Engine

Objects Shipped with ServiceCenter

System Tailoring, Vol. 1

Figure 1-1. Object Info Tab

Fields on the Objects panel

The Object Info Tab

The Document Engine

System Tailoring, Vol. 1

The Locking Tab

Figure 1-2. The Locking Tab

The Document Engine

Variable/Global Lists Tab

Figure 1-3. The Variable/Global Lists Tab

System Tailoring, Vol. 1

The Alerts Tab

Figure 1-4. The Alerts Tab

The Approvals Tab

Figure 1-5. The Approvals Tab

Approval FC - Enter the Format Control record to run after approval.