Sct4 System Tailoring Vol.1

630
Peregrine Systems, Inc. 3611 Valley Centre Drive San Diego, CA 92130 ServiceCenter ® Version 4.0 System Tailoring Volume 1 March 2001 SCT-4-ENG-01013-00012

Transcript of Sct4 System Tailoring Vol.1

Page 1: Sct4 System Tailoring Vol.1

Peregrine Systems, Inc.3611 Valley Centre DriveSan Diego, CA 92130

ServiceCenter®

Version 4.0

System TailoringVolume 1

March 2001

SCT-4-ENG-01013-00012

Page 2: Sct4 System Tailoring Vol.1

© 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

Page 3: Sct4 System Tailoring Vol.1

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

• Volume two

– 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

Topics covered in the System Tools chapters include:

• Macros

• Audits

• Clocks

• DDE support

• System events

• Sequential Numbers.

i

Page 4: Sct4 System Tailoring Vol.1

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 User’s 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

Page 5: Sct4 System Tailoring Vol.1

Contents

Knowledge Requirements .................................................................................................Preface-ii

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

Chapter 1: The Document EngineAccessing 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 ManagerAdministration Mode ....................................................................................................................2-2

Accessing a Record from the Database Manager .......................................................................2-2

Contents i

Page 6: Sct4 System Tailoring Vol.1

Chapter 3: Record UseRetrieving 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 System Tailoring, Vol. 1

Page 7: Sct4 System Tailoring Vol.1

Chapter 4: Single Record FunctionsAdding 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

Page 8: Sct4 System Tailoring Vol.1

Unload complication messages .......................................................................................... 5-37

Unloading records from multiple databases .............................................................................. 5-38

Part I—Unload from the first file.......................................................................................... 5-39

Part II—Unload 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 I—Report structure unload .......................................................................................... 5-48

Part II—Report record unload ............................................................................................. 5-50

Unload complication messages .......................................................................................... 5-52

Part III—Format Control...................................................................................................... 5-53

Part IV—Link 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

Page 9: Sct4 System Tailoring Vol.1

Chapter 7: File MaintenanceResetting 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

Page 10: Sct4 System Tailoring Vol.1

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 System Tailoring, Vol. 1

Page 11: Sct4 System Tailoring Vol.1

Chapter 12: Notification EngineThe 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

Page 12: Sct4 System Tailoring Vol.1

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 System Tailoring, Vol. 1

Page 13: Sct4 System Tailoring Vol.1

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

Page 14: Sct4 System Tailoring Vol.1

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

x System Tailoring, Vol. 1

Page 15: Sct4 System Tailoring Vol.1

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

Page 16: Sct4 System Tailoring Vol.1

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 System Tailoring, Vol. 1

Page 17: Sct4 System Tailoring Vol.1

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

Chapter 23: Introduction to Forms Designer

Knowledge Requirements.................................................................................................................23-2

Chapter 24: Dynamic View DependenciesSpecifying 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 WindowUsing the Properties Window ....................................................................................................27-1

Sizing the Properties Window ....................................................................................................27-2

Selecting a property ...................................................................................................................27-2

Entering a value manually..........................................................................................................27-2

Contents xiii

Page 18: Sct4 System Tailoring Vol.1

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

Page 19: Sct4 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

Page 20: Sct4 System Tailoring Vol.1

Graphics and Animation ................................................................................................................... 31-8

Optimum performance and image appearance ......................................................................... 31-8

Text and graphics ...................................................................................................................... 31-8

xvi System Tailoring, Vol. 1

Page 21: Sct4 System Tailoring Vol.1

Chapter 1The 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 user’s 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

Page 22: Sct4 System Tailoring Vol.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 System Tailoring, Vol. 1

Page 23: Sct4 System Tailoring Vol.1

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.

Figure 1-1. Object Info Tab

The Document Engine 1-3

Page 24: Sct4 System Tailoring Vol.1

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 System Tailoring, Vol. 1

Page 25: Sct4 System Tailoring Vol.1

The Locking Tab

The locking panel is used to determine the locking behavior for the Object.

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 record’s 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.

Figure 1-2. The Locking Tab

The Document Engine 1-5

Page 26: Sct4 System Tailoring Vol.1

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.

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.

Figure 1-3. The Variable/Global Lists Tab

1-6 System Tailoring, Vol. 1

Page 27: Sct4 System Tailoring Vol.1

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.

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

Figure 1-4. The Alerts Tab

The Document Engine 1-7

Page 28: Sct4 System Tailoring Vol.1

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.

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.

Figure 1-5. The Approvals Tab

1-8 System Tailoring, Vol. 1

Page 29: Sct4 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

Page 30: Sct4 System Tailoring Vol.1

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.

Figure 1-6. The States Panel

1-10 System Tailoring, Vol. 1

Page 31: Sct4 System Tailoring Vol.1

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

Page 32: Sct4 System Tailoring Vol.1

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 System Tailoring, Vol. 1

Page 33: Sct4 System Tailoring Vol.1

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.

Figure 1-8. The RAD tab

The Document Engine 1-13

Page 34: Sct4 System Tailoring Vol.1

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 System Tailoring, Vol. 1

Page 35: Sct4 System Tailoring Vol.1

Chapter 2Introduction 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 level—add, update, delete, retrieve, load, and unload individual records.

• Multiple-record level—perform all the single-record functions on a subset of the records in a database.

• File level—rebuild 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 single-record 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

Page 36: Sct4 System Tailoring Vol.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 System Tailoring, Vol. 1

Page 37: Sct4 System Tailoring Vol.1

The Database Manager dialog box is displayed.

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.

Figure 2-1. Database Manager Dialog box

Introduction to the Database Manager 2-3

Page 38: Sct4 System Tailoring Vol.1

2-4 System Tailoring, Vol. 1

Page 39: Sct4 System Tailoring Vol.1

Chapter 3Record 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

Page 40: Sct4 System Tailoring Vol.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 user’s 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)

¬# (MVS) does not start with

~# (UNIX)

= equal to

¬= (MVS) not equal to

~= (UNIX)

<> ><

< less than

3-2 System Tailoring, Vol. 1

Page 41: Sct4 System Tailoring Vol.1

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:

The relational and logical operators are demonstrated throughout this chapter.

<= or =< less than or equal to

> greater than

>= or => greater than or equal to

isin is element in

like is similar to (This operator is used only when querying character fields and enables wildcard searches on these fields.)

Table 3-1. Relational Operators

Relational Operator Definition

Table 3-2. Logical Operators

Logical Operator Syntax Symbol

NOT NOT ¬ (MVS) ~ (UNIX, WinNT)

AND and AND &

OR OR or |

Record Use 3-3

Page 42: Sct4 System Tailoring Vol.1

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

Used in combination, these capability words help control performance degradation due to inefficient queries.

Refer to the ServiceCenter System Administrator’s Guide for more information on capability words.

partial.key Allows operator to execute a partially keyed or non-keyed query.

partial.key.msg.skip Allows operator to bypass the partial key warning screen.

mod.time.limit Allows operator to modify the default time limit for partially keyed or non-keyed database searches.

3-4 System Tailoring, Vol. 1

Page 43: Sct4 System Tailoring Vol.1

Retrieving Records via the P4/QBE MethodP4 (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

Page 44: Sct4 System Tailoring Vol.1

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.

starts with O /#O

Figure 3-1. . Record List

3-6 System Tailoring, Vol. 1

Page 45: Sct4 System Tailoring Vol.1

The matching records are displayed.

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

Figure 3-2. Result of using “equal to”

Record Use 3-7

Page 46: Sct4 System Tailoring Vol.1

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.

6. Click on the record that you want to view.

Figure 3-3. Result of using “greater than”

3-8 System Tailoring, Vol. 1

Page 47: Sct4 System Tailoring Vol.1

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.

6. Click on the record that you want to view.

Figure 3-4. Result of using “less than”

Record Use 3-9

Page 48: Sct4 System Tailoring Vol.1

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 System Tailoring, Vol. 1

Page 49: Sct4 System Tailoring Vol.1

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

Figure 3-5. Wildcard query using the Like operator

Record Use 3-11

Page 50: Sct4 System Tailoring Vol.1

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 System Tailoring, Vol. 1

Page 51: Sct4 System Tailoring Vol.1

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.

Figure 3-6. Result of retrieving all records

Record Use 3-13

Page 52: Sct4 System Tailoring Vol.1

7. Click on the record that you want to view

Reminder: A warning screen, indicating an attempt to initiate a partially-keyed 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.

Figure 3-7. Result of a multiple field query

3-14 System Tailoring, Vol. 1

Page 53: Sct4 System Tailoring Vol.1

Important: Database Manager always forms QBE queries on scalar (non-arrayed) 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.

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

Figure 3-8. Operator record Startup tab

Record Use 3-15

Page 54: Sct4 System Tailoring Vol.1

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.

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.

Figure 3-9. Operator Record List

3-16 System Tailoring, Vol. 1

Page 55: Sct4 System Tailoring Vol.1

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

Page 56: Sct4 System Tailoring Vol.1

Retrieving Records via the Query WindowThe 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 Administrator’s 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 user’s 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 System Tailoring, Vol. 1

Page 57: Sct4 System Tailoring Vol.1

The query window and query buttons are shown below.

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

6. Press the Execute Search button.

Figure 3-10. Advanced Search Window

Figure 3-11. Search window

Record Use 3-19

Page 58: Sct4 System Tailoring Vol.1

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.

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.

Figure 3-12. Device Record

3-20 System Tailoring, Vol. 1

Page 59: Sct4 System Tailoring Vol.1

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.

9. Select Options>Select Sort.

Figure 3-13. Operator form with Advanced Search

Record Use 3-21

Page 60: Sct4 System Tailoring Vol.1

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 fully-keyed queries.

10. Enter the key number (3 for this example). Selecting 3 places the application.name key in the query.

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.

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.

Figure 3-14. Keylist form

Figure 3-15. Search Window with new sort field

3-22 System Tailoring, Vol. 1

Page 61: Sct4 System Tailoring Vol.1

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.

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.

Figure 3-16. Stored Query Maintenance form

Record Use 3-23

Page 62: Sct4 System Tailoring Vol.1

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.

The stored query record is displayed.

This form provides additional options that allow the user to ensure a fully-keyed query is established.

7. Click Select from the toolbar to choose this query to run as it appears against the opened operator form.

Figure 3-17. Stored query list

Figure 3-18. Stored query record

3-24 System Tailoring, Vol. 1

Page 63: Sct4 System Tailoring Vol.1

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

Stored query options

The options available for a stored query are:

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.

Figure 3-19. Stored Query Option buttons

Option key Function Definition

F1 Append using & This option adds another query to the end of your original query with the word AND separating the two queries.

F2 Append using | This option adds another query to the end of the original query with the word OR separating the two queries.

F3 Insert using & This option inserts another query at the beginning of the original query with the word AND separating the two queries.

F4 Insert using | This option inserts another query at the beginning of the original query with the word OR separating the two queries.

Record Use 3-25

Page 64: Sct4 System Tailoring Vol.1

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.

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:

Figure 3-20. Search window with complex query expression

3-26 System Tailoring, Vol. 1

Page 65: Sct4 System Tailoring Vol.1

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

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.

Figure 3-21. Search window using “not”

Record Use 3-27

Page 66: Sct4 System Tailoring Vol.1

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 System Tailoring, Vol. 1

Page 67: Sct4 System Tailoring Vol.1

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.

Figure 3-22. Search results

Record Use 3-29

Page 68: Sct4 System Tailoring Vol.1

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.

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.

Figure 3-23. Search window identifying characters

3-30 System Tailoring, Vol. 1

Page 69: Sct4 System Tailoring Vol.1

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.

Figure 3-24. Search window specifying length of character string

Record Use 3-31

Page 70: Sct4 System Tailoring Vol.1

3-32 System Tailoring, Vol. 1

Page 71: Sct4 System Tailoring Vol.1

Chapter 4Single 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)

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.

Table 4-1.

Field Record Value

Contact Name HOSKINS,BOB

Company Acme

Single Record Functions 4-1

Page 72: Sct4 System Tailoring Vol.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 System Tailoring, Vol. 1

Page 73: Sct4 System Tailoring Vol.1

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.

6. Click Yes to continue with the record deletion.

The following message is displayed in the status bar: contacts record deleted.

Figure 4-1. Deleting an enduser record

Single Record Functions 4-3

Page 74: Sct4 System Tailoring Vol.1

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.

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

Figure 4-2. Printing a record

4-4 System Tailoring, Vol. 1

Page 75: Sct4 System Tailoring Vol.1

Administrator’s 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).

Single Record Functions 4-5

Page 76: Sct4 System Tailoring Vol.1

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 Description Recovery

Record contains invalid duplicate key.

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. If caused by an add function, either rename the record or select the existing record and update it.

2. If caused by an update function, delete the existing record and then add the new one.

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

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. Enter data into the field(s) defined as no nulls or unique keys and add or update the record.

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

4-6 System Tailoring, Vol. 1

Page 77: Sct4 System Tailoring Vol.1

Record level options

Several advanced user options exist once a record has been selected. These options are available from the Options menu.

Expand Array—expands 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.

This record has been changed since you selected it.

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.

Reselect the record and proceed with the update or deletion.

The record has already been deleted.

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.

1. If caused by a delete function, the record has already been deleted and no further action is needed.

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

Table 4-2. Possible Error Messages (Continued)

Error Description Recovery

Single Record Functions 4-7

Page 78: Sct4 System Tailoring Vol.1

A new form appears with an extended version of the selected field.

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.

Figure 4-3. Expanded array form

4-8 System Tailoring, Vol. 1

Page 79: Sct4 System Tailoring Vol.1

Expand array options

End—checks for differences and prompts for confirmation.

Mark starting line—used 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 space—inserts a space at the start of the line the cursor is on.

Delete space—deletes the first space on the line the cursor is on.

Truncate—removes all line values below the line the cursor is on.

Insert line—insets a blank line above the line the cursor is on.

Delete line—removes the line the cursor is on from the array.

Copy—selects 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

Single Record Functions 4-9

Page 80: Sct4 System Tailoring Vol.1

fields down if necessary, retaining original line, replace replaces line the cursor is on.

Move—same as Copy, except it removes the original value from the selected line.

Clear—removes all lines in array.

4-10 System Tailoring, Vol. 1

Page 81: Sct4 System Tailoring Vol.1

Format Control SettingsThe 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.

Single Record Functions 4-11

Page 82: Sct4 System Tailoring Vol.1

4-12 System Tailoring, Vol. 1

Page 83: Sct4 System Tailoring Vol.1

Chapter 5Multiple-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

Page 84: Sct4 System Tailoring Vol.1

Adding Multiple RecordsHaving 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 System Tailoring, Vol. 1

Page 85: Sct4 System Tailoring Vol.1

5. Enter the desired location value preceded by =. For this example, enter =alh100.

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-1. Querying for records to duplicate

Figure 5-2. Calling Mass Add action

Multiple-Record Functions 5-3

Page 86: Sct4 System Tailoring Vol.1

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 System Tailoring, Vol. 1

Page 87: Sct4 System Tailoring Vol.1

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.

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.

Figure 5-4. Querying for duplicate records, based on modified location

Multiple-Record Functions 5-5

Page 88: Sct4 System Tailoring Vol.1

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.

Figure 5-5. Record duplicates with modified logical.name and location values

5-6 System Tailoring, Vol. 1

Page 89: Sct4 System Tailoring Vol.1

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.

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=”bru100”—which 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+=1—which 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.

Figure 5-6. Calling Mass Add action

Multiple-Record Functions 5-7

Page 90: Sct4 System Tailoring Vol.1

Note: The Mass Add function is performed in foreground, which means your session is devoted to the add task until completed.

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.

Figure 5-7. Mass Add instructions

5-8 System Tailoring, Vol. 1

Page 91: Sct4 System Tailoring Vol.1

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.

The original records listed before the Mass Add remain in the enduser file with no changes to the original data.

Figure 5-8. Querying for new records

Figure 5-9. Duplicated record with modified name and location values

Multiple-Record Functions 5-9

Page 92: Sct4 System Tailoring Vol.1

Updating Multiple RecordsHaving 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 System Tailoring, Vol. 1

Page 93: Sct4 System Tailoring Vol.1

4. Select List Options > Mass Update from the menu bar to start the process of updating the records shown in the record list.

The initial format is re-displayed with new option buttons.

5. Enter tony jones in the primary contact field

6. Click Simple update.

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.

Figure 5-10. Selecting Mass Update option

Figure 5-11. Defining Mass Update field value

Multiple-Record Functions 5-11

Page 94: Sct4 System Tailoring Vol.1

The newly updated records are displayed in the record list.

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.

Figure 5-12. Displaying records with Mass Updated field value

5-12 System Tailoring, Vol. 1

Page 95: Sct4 System Tailoring Vol.1

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.

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.

Figure 5-13. Displaying records with Mass Updated field value

Multiple-Record Functions 5-13

Page 96: Sct4 System Tailoring Vol.1

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 System Tailoring, Vol. 1

Page 97: Sct4 System Tailoring Vol.1

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

Multiple-Record Functions 5-15

Page 98: Sct4 System Tailoring Vol.1

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.

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.

Figure 5-16. Updating record list

5-16 System Tailoring, Vol. 1

Page 99: Sct4 System Tailoring Vol.1

.At this point, a user has several options concerning the outcome of this

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.

Figure 5-17. Record updating error

Multiple-Record Functions 5-17

Page 100: Sct4 System Tailoring Vol.1

Deleting Multiple RecordsThe 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 System Tailoring, Vol. 1

Page 101: Sct4 System Tailoring Vol.1

Printing Multiple RecordsThe 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.

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 Only—prints the list exactly as shown with a total count at the bottom.

Print All Records—prints the corresponding records of all items listed

Background—prints 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.

Figure 5-18. Print confirmation window for Server printer settings

Multiple-Record Functions 5-19

Page 102: Sct4 System Tailoring Vol.1

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.

Figure 5-19. Available system printers

5-20 System Tailoring, Vol. 1

Page 103: Sct4 System Tailoring Vol.1

4. Select List Options > Count (count recds).

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.

Figure 5-20. Record count option

Multiple-Record Functions 5-21

Page 104: Sct4 System Tailoring Vol.1

Unloading ServiceCenter DataThe 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 server’s 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 System Tailoring, Vol. 1

Page 105: Sct4 System Tailoring Vol.1

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.

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.

Figure 5-21. Preparing to unload a record

Multiple-Record Functions 5-23

Page 106: Sct4 System Tailoring Vol.1

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 System Tailoring, Vol. 1

Page 107: Sct4 System Tailoring Vol.1

Unload messages Table 5-1. Unload Message

Message Description

Invalid unload append/create parameter. Parameter must be append or create for the unload append/create input field.

Select one export format: binary.text or formatted text.

Valid entries are binary, text, and formatted text for the unload mode input field.

Invalid unload dbdict load parameter. Valid entries are create, replace, and remove for the unload dbdict input field.

Unload mode must be export. When an export descriptor record is specified, the unload type must be export for the unload mode input field.

Invalid unload record load parameter. Valid entries are update and add only for the record load input field.

No file is available to load. 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.

No unload file name. Unload requires an external file name.

The unload format must be binary for Purge/Archive. When unloads are accessed via Purge/Archive, the unload format must be binary. Refer to Base Utilities Guide, Chapter 14, Purge/Archive.

<database name> file unloaded to external file: <MVS file or UNIX filename>.

Unload processing the named database to the named MVS dataset or UNIX file complete.

config record: <config name> is not set up to be used for database unloads.

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.

External file: <MVS.FILENAME> or <UNIX.filename> is locked; try again later.

Another task has exclusive control over the named external dataset.

Invalid number of records found in config file. 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.

Multiple-Record Functions 5-25

Page 108: Sct4 System Tailoring Vol.1

The config record (database load/unload) is missing. 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 config record (database create) is missing. 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.

<nn> records unloaded so far from <database name> file.

The unload utility generates this message every hundredth record it attempts to unload.

<nn> records from <database name> unloaded into external file: <MVS.FILENAME> or <UNIX/NT.FILENAME>.

Unload processing nn records from the named ServiceCenter database to the named MVS dataset or UNIX/NT file completed.

<database name> file CANNOT be unloaded to external file: <MVS.FILENAME> or <UNIX/NT.FILENAME>.

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.

Unable to allocate. 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.

Table 5-1. Unload Message (Continued)

Message Description

5-26 System Tailoring, Vol. 1

Page 109: Sct4 System Tailoring Vol.1

Unload form fields

External File Name—fully 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.

Member—name of the member if the external file is an MVS partitioned dataset. Otherwise, leave the field blank.

Unload Type—determines 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 File—default 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 Map—default 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 Map—default 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 Messages—allows 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.

Application:file.unload has completed with errors; check other messages.

An error exit was taken; check the message log for the error message indicating which exit.

Invalid unload options specified for unload, no records unloaded.

Since the unload options were invalid, no records were unloaded.

Table 5-1. Unload Message (Continued)

Message Description

Multiple-Record Functions 5-27

Page 110: Sct4 System Tailoring Vol.1

Export Mode

Binary—writes the file in ServiceCenter internal binary formatted mode, which can only be read by the Database Manager’s Load facility.

Text—Writes 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 Manager’s Load facility.

Formatted Text—Exports information in a format that can be read by external programs, and structured to match an existing ServiceCenter text (not GUI) format.

Form Name—name 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 Description—used 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 Records—used 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 System Tailoring, Vol. 1

Page 111: Sct4 System Tailoring Vol.1

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.

Multiple-Record Functions 5-29

Page 112: Sct4 System Tailoring Vol.1

A record list of enduser records satisfying the query is displayed.

3. Select List Options -> Mass Unload to begin the unload process for this list of records.

Figure 5-23. Unloading a list of records

5-30 System Tailoring, Vol. 1

Page 113: Sct4 System Tailoring Vol.1

The default unload/export 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).

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

Figure 5-24. Setting multiple record unload configuration

Multiple-Record Functions 5-31

Page 114: Sct4 System Tailoring Vol.1

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.

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.

5-32 System Tailoring, Vol. 1

Page 115: Sct4 System Tailoring Vol.1

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:

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

• a101a01

• a101a03

• a102a02

• a105a03

• a106b01

• a106b02

• a106b03

• d100-1

Multiple-Record Functions 5-33

Page 116: Sct4 System Tailoring Vol.1

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.

Figure 5-25. Value list record selection

5-34 System Tailoring, Vol. 1

Page 117: Sct4 System Tailoring Vol.1

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

Multiple-Record Functions 5-35

Page 118: Sct4 System Tailoring Vol.1

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

Figure 5-27. Configuring multiple record unload

5-36 System Tailoring, Vol. 1

Page 119: Sct4 System Tailoring Vol.1

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.

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

Multiple-Record Functions 5-37

Page 120: Sct4 System Tailoring Vol.1

• 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 System Tailoring, Vol. 1

Page 121: Sct4 System Tailoring Vol.1

Part I—Unload 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.

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.

Figure 5-28. Initial record list for multiple database unload

Multiple-Record Functions 5-39

Page 122: Sct4 System Tailoring Vol.1

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 System Tailoring, Vol. 1

Page 123: Sct4 System Tailoring Vol.1

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 II—Unload 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.

Multiple-Record Functions 5-41

Page 124: Sct4 System Tailoring Vol.1

4. Pass a true query by pressing Enter to return a list of all records (or use any query to retrieve the desired 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.

Figure 5-29. Unloading a second group of records

5-42 System Tailoring, Vol. 1

Page 125: Sct4 System Tailoring Vol.1

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.

Figure 5-30. Appending a second group of records to existing unload file

Multiple-Record Functions 5-43

Page 126: Sct4 System Tailoring Vol.1

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

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 Microsoft’s (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.

Figure 5-31. Confirmation of unload on second block of data records

5-44 System Tailoring, Vol. 1

Page 127: Sct4 System Tailoring Vol.1

4. Select List Options -> Export 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.

Figure 5-32. Unloading data records to Excel

Multiple-Record Functions 5-45

Page 128: Sct4 System Tailoring Vol.1

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.

5. Click Unl Dbdict.

Figure 5-33. Unloading a dbdict

5-46 System Tailoring, Vol. 1

Page 129: Sct4 System Tailoring Vol.1

The Unload/Export Utility screen is displayed requesting unload parameters.

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.

Figure 5-34. Specifying external unload file

Multiple-Record Functions 5-47

Page 130: Sct4 System Tailoring Vol.1

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 I—Report structure unload

The qualified report record with primary file designation is displayed.

5-48 System Tailoring, Vol. 1

Page 131: Sct4 System Tailoring Vol.1

1. Select Options > Export/Unload to unload the report record.

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.

Figure 5-35. Report Writer prompt

Multiple-Record Functions 5-49

Page 132: Sct4 System Tailoring Vol.1

4. Click Unload/export.

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 II—Report 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.

Figure 5-36. Specifying unload file settings

5-50 System Tailoring, Vol. 1

Page 133: Sct4 System Tailoring Vol.1

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.

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.

Figure 5-37. Listing reports to unload

Multiple-Record Functions 5-51

Page 134: Sct4 System Tailoring Vol.1

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

Figure 5-38. Appending report records to existing unload file.

5-52 System Tailoring, Vol. 1

Page 135: Sct4 System Tailoring Vol.1

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 III—Format 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.

Multiple-Record Functions 5-53

Page 136: Sct4 System Tailoring Vol.1

5. Enter the two format control names as shown in Figure 5-40 in the Field Values array.

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.

Figure 5-39. Specifying Format Control records to unload

5-54 System Tailoring, Vol. 1

Page 137: Sct4 System Tailoring Vol.1

The Unload/Export Utility form is displayed with a prompt requesting unload parameters.

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 IV—Link 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.

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>

Figure 5-40. Appending report records to existing unload file.

Multiple-Record Functions 5-55

Page 138: Sct4 System Tailoring Vol.1

<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 System Tailoring, Vol. 1

Page 139: Sct4 System Tailoring Vol.1

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

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.

Figure 5-41. Messages returned from unload of Format Control report records

Multiple-Record Functions 5-57

Page 140: Sct4 System Tailoring Vol.1

Loading ServiceCenter DatabasesThe 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 System Tailoring, Vol. 1

Page 141: Sct4 System Tailoring Vol.1

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.

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.

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.

Figure 5-42. Selecting ServiceCenter unload file to load

Figure 5-43. Contents table of unload file data records

Multiple-Record Functions 5-59

Page 142: Sct4 System Tailoring Vol.1

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>.example11 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>.example11 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 System Tailoring, Vol. 1

Page 143: Sct4 System Tailoring Vol.1

*# 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 elapsedLoading 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 Description

<MVS.FILENAME>, <WINNT.FILENAME> or <UNIX.FILENAME> file loaded.

Load processing of the named dataset is complete.

File(s) loaded from external file: <MVS.FILENAME>, <WINNT.FILENAME> or <UNIX.FILENAME>

Load processing of all the files within the dataset or file completed.

<nn> records loaded into <database name> from external file: <MVS.FILENAME>, <WINNT.FILENAME> or <UNIX.FILENAME>

Load processing of nn records into the named ServiceCenter database from the named dataset or file completed.

Loading <database name> from external file: <MVS.FILENAME>, <WINNT.FILENAME> or <UNIX.FILENAME>.

Load processing of the named ServiceCenter database from the named dataset or file begins.

<nnn> records have been loaded so far into the <database name> file.

The load utility generates this message for every hundredth record it attempts to load into the named ServiceCenter database.

The config record (database load/unload is missing).

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.

Invalid number of records found in config file. The load utility found two or more hardware configuration records named database load/unload.mvs. There should be only one such record.

Config record is not set up to be used for database loads.

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 external file <MVS.FILENAME>, <WINNT.FILENAME> or <UNIX.FILENAME> is being written to and cannot be read at this time.

The load utility could not access the named external file because another task has exclusive control on it.

Multiple-Record Functions 5-61

Page 144: Sct4 System Tailoring Vol.1

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 administrator’s 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).

Invalid end of file encountered in external file <MVS.FILENAME>, <WINNT.FILENAME> or <UNIX.FILENAME>.

The load utility encountered an incomplete dataset, i.e., the unload which originally created this dataset was interrupted before completion.

All null keys:file: <database name>;rec no;<nn> in external file:<MVS.FILENAME>, <WINNT.FILENAME> or <UNIX.FILENAME>.

The load utility attempted to add record number <nn> to the named ServiceCenter database and encountered all null keys.

Invalid null key;file:<database name>;rec no:<nn> in external file <MVS.FILENAME>, <WINNT.FILENAME> or <UNIX.FILENAME>.

The load utility attempted to add record number <nn> to the named ServiceCenter database and encountered an invalid null key.

Invalid duplicate key:file:<database name>;rec no:<nn> in external file <MVS.FILENAME>, <WINNT.FILENAME> or <UNIX.FILENAME>.

The load utility attempted to add record number <nn> to the named ServiceCenter database and encountered an invalid duplicate key.

External file <MVS.FILENAME>, <WINNT.FILENAME> or <UNIX.FILENAME> is not in Peregrine Four Unload Format.

The named dataset is not in the proprietary format required by the load utility.

Table 5-2. Load Messages (Continued)

Message Description

5-62 System Tailoring, Vol. 1

Page 145: Sct4 System Tailoring Vol.1

7. Click Load bg.

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.

Figure 5-44. Identifying ServiceCenter unload file for background load

Multiple-Record Functions 5-63

Page 146: Sct4 System Tailoring Vol.1

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.

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 5-45).

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.

Figure 5-45. Scheduling background load

5-64 System Tailoring, Vol. 1

Page 147: Sct4 System Tailoring Vol.1

Chapter 6Database 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

Page 148: Sct4 System Tailoring Vol.1

Understanding AuditingAuditing 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 System Tailoring, Vol. 1

Page 149: Sct4 System Tailoring Vol.1

Accessing the Audit Specifications FileThe 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 administrator’s home menu.

2. Click Tools.

The ServiceCenter Tools menu is displayed.

3. Click Audit Specifications to bring up an audit specifications table.

Figure 6-1. Tools menu in the system administrator’s home menu

Database Record Auditing 6-3

Page 150: Sct4 System Tailoring Vol.1

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.

Figure 6-2. Audit specifications form.

6-4 System Tailoring, Vol. 1

Page 151: Sct4 System Tailoring Vol.1

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.

Filename—name of a valid ServiceCenter Database Dictionary file upon which Audit will be performed. This is a required field on the table.

Unique A - D—used 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 Name—defines 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

Page 152: Sct4 System Tailoring Vol.1

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.

Alias—defines 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 System Tailoring, Vol. 1

Page 153: Sct4 System Tailoring Vol.1

Accessing the Audit Log FileThe 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 administrator’s 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.

Database Record Auditing 6-7

Page 154: Sct4 System Tailoring Vol.1

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.

File—file name with which this Audit Log record is associated.

Unq A through D—The contents of the source record fields defined as Unique A through D in the Audit Specifications file.

Date—creation date and time that the Audit Log entry was created.

Oper—userid of the operator who modified the source record, causing the Audit Log entry to be generated.

Field—field 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 System Tailoring, Vol. 1

Page 155: Sct4 System Tailoring Vol.1

Defining an Audit Specifications EntryThe 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 administrator’s home menu.

2. Click Tools.

The Tools menu is displayed.

3. Click Audit Specifications.

A blank Audit Specifications Table form is displayed.

Figure 6-4. Tools menu

Database Record Auditing 6-9

Page 156: Sct4 System Tailoring Vol.1

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.

When the Filename value is invalid, the message The filename ‘filename’ is not valid. Select one from the list is issued.

Figure 6-5. Audit specifications table

6-10 System Tailoring, Vol. 1

Page 157: Sct4 System Tailoring Vol.1

A QBE list is displayed, showing valid ServiceCenter Database Dictionary file names.

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

Figure 6-6. QBE of valid system filenames

Database Record Auditing 6-11

Page 158: Sct4 System Tailoring Vol.1

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 System Tailoring, Vol. 1

Page 159: Sct4 System Tailoring Vol.1

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.

Database Record Auditing 6-13

Page 160: Sct4 System Tailoring Vol.1

.

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 administrator’s home menu.

b. Click Tools

Figure 6-7. Activating history tracking option

6-14 System Tailoring, Vol. 1

Page 161: Sct4 System Tailoring Vol.1

c. Click Format Control.A blank Format Control Maintenance form appears.

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.

Figure 6-8. Main format control settings screen

Database Record Auditing 6-15

Page 162: Sct4 System Tailoring Vol.1

The subroutine panel is presented, as shown in Figure 6-9.

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:

Add—This 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.

Before—This 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.

Application—This 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.

Figure 6-9. Setting up format control subroutine

6-16 System Tailoring, Vol. 1

Page 163: Sct4 System Tailoring Vol.1

Message—This field provides the error message, which appears if the process cannot be completed as planned.

Names—This 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

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

Database Record Auditing 6-17

Page 164: Sct4 System Tailoring Vol.1

Figure 6-10. Trigger record for updates to enduser file

6-18 System Tailoring, Vol. 1

Page 165: Sct4 System Tailoring Vol.1

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:

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.

Table 6-1. Sample field values

Field Value

logical name a111

serial no. 8888

parent a111-a

vtam parent n87e34

vtam name n87d30

location carlsbac

fixed asset no. 12345

manufacturer crt international

model 553

type crt

vendor crt distributors

Database Record Auditing 6-19

Page 166: Sct4 System Tailoring Vol.1

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-11. Enduser record

6-20 System Tailoring, Vol. 1

Page 167: Sct4 System Tailoring Vol.1

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.

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.

Figure 6-12. Enduser—modified fields

Figure 6-13. Enduser - audit record QBE

Database Record Auditing 6-21

Page 168: Sct4 System Tailoring Vol.1

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.

7. For further information regarding the modifications to the enduser file, click show detail.

Figure 6-14. Updated record

6-22 System Tailoring, Vol. 1

Page 169: Sct4 System Tailoring Vol.1

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.

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.

Figure 6-15. Expanded audit log record

Database Record Auditing 6-23

Page 170: Sct4 System Tailoring Vol.1

6-24 System Tailoring, Vol. 1

Page 171: Sct4 System Tailoring Vol.1

Chapter 7File 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 administrator’s 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

Page 172: Sct4 System Tailoring Vol.1

A blank syslog form is displayed.

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.

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.

Figure 7-1. Blank system log file

Schedule button

Figure 7-2. Reset prompt

7-2 System Tailoring, Vol. 1

Page 173: Sct4 System Tailoring Vol.1

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

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

• Monthly—reset once a month.

• Quarterly—reset every three months.

• Semi-annually—reset every six months.

• Annually—reset once a year.

Figure 7-3. Scheduling form for resetting a file

File Maintenance 7-3

Page 174: Sct4 System Tailoring Vol.1

• Other—reset 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 System Tailoring, Vol. 1

Page 175: Sct4 System Tailoring Vol.1

Regenerating Database Keys from Database ManagerKeys 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 administrator’s 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

Page 176: Sct4 System Tailoring Vol.1

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

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.

Figure 7-5. Scheduling a regen time

7-6 System Tailoring, Vol. 1

Page 177: Sct4 System Tailoring Vol.1

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

• Monthly—regenerate once a month.

• Quarterly—regenerate every three months.

• Semi-annually—regenerate every six months.

• Annually—regenerate once a year.

• Other—regenerate 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

Page 178: Sct4 System Tailoring Vol.1

7-8 System Tailoring, Vol. 1

Page 179: Sct4 System Tailoring Vol.1

Chapter 8Unload 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

Page 180: Sct4 System Tailoring Vol.1

Creating an Unload ScriptTo create an unload script:

1. Select the Toolkit tab in the system administrator’s home menu.

2. Click Unload Script Utility.

A QBE list of existing unload script records is displayed.

3. Select Options>Add/Edit Unload Scripts.

Figure 8-1. QBE List of Available Unload Script Records

8-2 System Tailoring, Vol. 1

Page 181: Sct4 System Tailoring Vol.1

A blank unload script record form is displayed.

4. Complete the following fields:

Table 8-1. Unload Script Utility Fields

Field Description

Unload Script Descriptive name of the script.

Unload? Creates an unload file if checked

Purge? Purges the records returned by your queries (or the data map) from your system if checked

Show Unload Records Displays the list of files and the queries you have created to unload records

Show Protected Formats

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.

Figure 8-2. Blank Unload Script record

Unload Script Utility 8-3

Page 182: Sct4 System Tailoring Vol.1

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.

For this example, we have selected the following files:

• format

• menu

• operator

• pmenv

• smenv

• unload

9. Write the queries in the Query column needed to select the particular records you want to unload.

Filename Name of the ServiceCenter file from which the records are to be selected

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

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

Table 8-1. Unload Script Utility Fields (Continued)

Field Description

8-4 System Tailoring, Vol. 1

Page 183: Sct4 System Tailoring Vol.1

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.

Unload Script Utility 8-5

Page 184: Sct4 System Tailoring Vol.1

Your unload script record may look like the example in Figure 8-3.

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:

Figure 8-3. Unload Script Record—New

Table 8-2. Commonly Scripted Files and Field Names

File Field

format name

link name

formatctrl name

8-6 System Tailoring, Vol. 1

Page 185: Sct4 System Tailoring Vol.1

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

menu name

operator name

probsummary number

problem number

incidents incident.id

ocmq number

ocml number

ocmo number

cm3r number

cm3t number

Table 8-2. Commonly Scripted Files and Field Names

File Field

Unload Script Utility 8-7

Page 186: Sct4 System Tailoring Vol.1

• 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 System Tailoring, Vol. 1

Page 187: Sct4 System Tailoring Vol.1

Editing an Unload Script To edit an unload script:

1. Select the Toolkit tab in the system administrator’s 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.

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.

Figure 8-4. Unload Script Record—Read-Only Mode

Unload Script Utility 8-9

Page 188: Sct4 System Tailoring Vol.1

Figure 8-5. Unload Script Record—Edit Mode

8-10 System Tailoring, Vol. 1

Page 189: Sct4 System Tailoring Vol.1

Validating an Unload ScriptTo validate an unload script:

1. Select the Toolkit tab in the system administrator’s 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.

If the script is valid, the following message is displayed in the status bar: Unload script is valid.

Figure 8-6. Unload Script Record—Read-Only Mode

Unload Script Utility 8-11

Page 190: Sct4 System Tailoring Vol.1

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 System Tailoring, Vol. 1

Page 191: Sct4 System Tailoring Vol.1

Unloading records from an Unload ScriptThere are two methods for unloading files from an unload script:

• Peregrine Unload/Export Facility—accessed from the Options menu of an unload script record in the edit mode (refer to Database Administration).

• ServiceCenter Unload utility—described in the following section.

To unload files from an unload script:

1. Select the Toolkit tab in the system administrator’s 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

Unload Script Utility 8-13

Page 192: Sct4 System Tailoring Vol.1

6. Select one of the following options:

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.

Table 8-3. Unload Utility Fields

Field Description

Append to File 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.

Use existing dbdict Unloaded records are added using the existing Database Dictionary. Any changes to fields or keys are ignored.

Use dbdict of loaded record (replace old dbdict)

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.

Add new records and update existing records

Adds new records to the files of the new system and updates existing records with new information from records in the unload file.

Add new records only Adds new records to the files of the new system only. Does not replace existing records.

8-14 System Tailoring, Vol. 1

Page 193: Sct4 System Tailoring Vol.1

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.

Unload Script Utility 8-15

Page 194: Sct4 System Tailoring Vol.1

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.

Figure 8-8. Unload Script Record with Protected Format View

2

8-16 System Tailoring, Vol. 1

Page 195: Sct4 System Tailoring Vol.1

Chapter 9Introduction 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

Page 196: Sct4 System Tailoring Vol.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 file’s 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 System Tailoring, Vol. 1

Page 197: Sct4 System Tailoring Vol.1

Accessing the Database DictionaryThere 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.

Introduction to the Database Dictionary 9-3

Page 198: Sct4 System Tailoring Vol.1

The enduser Database Dictionary is displayed, as in Figure 9-1.

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 Name—name 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.

Figure 9-1. enduser Database Dictionary record.

9-4 System Tailoring, Vol. 1

Page 199: Sct4 System Tailoring Vol.1

Type—data type of the data item. The number values refer to the data types as follows:

Index—field’s 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.

Level—number 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 array’s parent is the descriptor structure.

Keys—keys 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.

Table 9-1. Data Types

Data Type Value

number 1

character 2

date/time 3

logical 4

record 6

array 8

structure 9

expression 11

Introduction to the Database Dictionary 9-5

Page 200: Sct4 System Tailoring Vol.1

2. At the File Name prompt, enter the name of any format associated with the database file you want to access.

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.

Figure 9-2. Database Dictionary file name prompt

9-6 System Tailoring, Vol. 1

Page 201: Sct4 System Tailoring Vol.1

Chapter 10Adding and Modifying

Important: Menu items and messages may appear differently than shown, depending on your version of ServiceCenter.

Adding a New FieldYou 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

Page 202: Sct4 System Tailoring Vol.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):

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.

AND IF NULL

BEGIN IN OR

DO ISIN STEP

ELSE LIKE THEN

END MONTH TRUE

FALSE NAME WHILE

FOR NOT UNKNOWN

10-2 System Tailoring, Vol. 1

Page 203: Sct4 System Tailoring Vol.1

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.

Figure 10-1. Example Database Dictionary record—device

Adding and Modifying 10-3

Page 204: Sct4 System Tailoring Vol.1

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

Number—allows you to input only numeric data in the field.

Character—allows you to input any available characters in the field (numbers, letters, special characters).

Date/Time—requires 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 System Tailoring, Vol. 1

Page 205: Sct4 System Tailoring Vol.1

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

Logical—contains 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.

Label—used only in RAD applications.

Record—used only in RAD applications.

Array—compound data element that contains one or more elements of a single data type.

Structure—compound data element that contains several sub-fields, each of which may have a different data type.

Expression—used 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

Adding and Modifying 10-5

Page 206: Sct4 System Tailoring Vol.1

the various components comprising a PC workstation.

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 array’s 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.

Figure 10-2. Enduser Database Dictionary record

10-6 System Tailoring, Vol. 1

Page 207: Sct4 System Tailoring Vol.1

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.

Adding and Modifying 10-7

Page 208: Sct4 System Tailoring Vol.1

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 System Tailoring, Vol. 1

Page 209: Sct4 System Tailoring Vol.1

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

Let’s assume you created a file called employee with many formats attached to the file (many different views depending on the user profile). Let’s 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.

Adding and Modifying 10-9

Page 210: Sct4 System Tailoring Vol.1

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.

Figure 10-4. Sample Database Dictionary record - employee (does not exist on default system)

10-10 System Tailoring, Vol. 1

Page 211: Sct4 System Tailoring Vol.1

8. 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. 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 drop-down list of valid data types.

Figure 10-5. Database Dictionary record with new structure

Adding and Modifying 10-11

Page 212: Sct4 System Tailoring Vol.1

5. Click Add to add the new field in this 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.

Figure 10-6. Adding fields to a new structure

10-12 System Tailoring, Vol. 1

Page 213: Sct4 System Tailoring Vol.1

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.

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.

Figure 10-7. New fields added to new structure

Adding and Modifying 10-13

Page 214: Sct4 System Tailoring Vol.1

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 Field Type

number.of.problems number

explicit.unavailability date/time

implicit.unavailability date/time

perceived.unavailability date/time

start.of.operating.hours date/time

end.of.operating.hours date/time

graph.of.unavailability array

graph.of.unavailability structure

date date/time

graph character

10-14 System Tailoring, Vol. 1

Page 215: Sct4 System Tailoring Vol.1

The field names need to be spelled exactly as they are shown in the above table and defined with the specified field type.

Let’s 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.

The message Enter data type of array’s element appears in the bottom of the screen and the pop-up window refreshes.

Figure 10-8. Adding structured array field

Adding and Modifying 10-15

Page 216: Sct4 System Tailoring Vol.1

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.

Figure 10-9. New structured array field

10-16 System Tailoring, Vol. 1

Page 217: Sct4 System Tailoring Vol.1

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.

Adding and Modifying 10-17

Page 218: Sct4 System Tailoring Vol.1

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.

Figure 10-10. Fields added to structure within array

10-18 System Tailoring, Vol. 1

Page 219: Sct4 System Tailoring Vol.1

Alias FieldsAn 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 Index Reference Number

Shared Level

Figure 10-11. Alias fields used in inventory Database Dictionary files

Adding and Modifying 10-19

Page 220: Sct4 System Tailoring Vol.1

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 administrator’s 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 System Tailoring, Vol. 1

Page 221: Sct4 System Tailoring Vol.1

6. Click Search.

Figure 10-12. Search form for dbdict records in Database Manager

Adding and Modifying 10-21

Page 222: Sct4 System Tailoring Vol.1

The probsummary record is displayed.

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.

Figure 10-13. System file record (probsummary) displayed in Database Manager

10-22 System Tailoring, Vol. 1

Page 223: Sct4 System Tailoring Vol.1

The screen is refreshed in write-protected mode disallowing input.

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.

Figure 10-14. flag field of probsummary file record

Adding and Modifying 10-23

Page 224: Sct4 System Tailoring Vol.1

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.

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.

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

Figure 10-15. Duplicate/alias flag field

Figure 10-16. Modifying alias flag field

10-24 System Tailoring, Vol. 1

Page 225: Sct4 System Tailoring Vol.1

The Database Dictionary record is re-displayed and the original options are available.

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.

Figure 10-17. probsummary file record with alias fields

Adding and Modifying 10-25

Page 226: Sct4 System Tailoring Vol.1

Adding a KeyA 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 System Tailoring, Vol. 1

Page 227: Sct4 System Tailoring Vol.1

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 & Duplicates—allows nulls and duplicates in the field(s) comprising the key.

No Nulls—allows duplicates but no nulls (i.e., must contain data in at least one of the fields in the key).

No Duplicates—allows nulls but no duplicates (i.e., data must be unique, but field may be left blank).

Figure 10-18. Adding a key to the enduser Database Dictionary record

Adding and Modifying 10-27

Page 228: Sct4 System Tailoring Vol.1

Unique—must 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.

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.

Figure 10-19. New key added as first key

10-28 System Tailoring, Vol. 1

Page 229: Sct4 System Tailoring Vol.1

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.

Adding and Modifying 10-29

Page 230: Sct4 System Tailoring Vol.1

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.

Figure 10-20. Inserting a key to the enduser Database Dictionary record

10-30 System Tailoring, Vol. 1

Page 231: Sct4 System Tailoring Vol.1

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.

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.

Figure 10-21. New key inserted between existing keys

Adding and Modifying 10-31

Page 232: Sct4 System Tailoring Vol.1

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 System Tailoring, Vol. 1

Page 233: Sct4 System Tailoring Vol.1

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.

Figure 10-22. Inserting a key at the end of the enduser Database Dictionary record

Adding and Modifying 10-33

Page 234: Sct4 System Tailoring Vol.1

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.

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.

Figure 10-23. Concatenated key added to end of the enduser record

10-34 System Tailoring, Vol. 1

Page 235: Sct4 System Tailoring Vol.1

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.

Adding and Modifying 10-35

Page 236: Sct4 System Tailoring Vol.1

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. Let’s 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 System Tailoring, Vol. 1

Page 237: Sct4 System Tailoring Vol.1

Notice the address field name is now old.address in the Field Name array.

Figure 10-24. Modifying an existing field name

Figure 10-25. Renamed field

Adding and Modifying 10-37

Page 238: Sct4 System Tailoring Vol.1

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 array’s 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 System Tailoring, Vol. 1

Page 239: Sct4 System Tailoring Vol.1

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. Let’s assume that data exists in the file.

1. Select the zip field name.

2. Click Edit.

Adding and Modifying 10-39

Page 240: Sct4 System Tailoring Vol.1

The field editing window is displayed.

3. Enter number in the Type field.

This replaces character with number in the Type field.

Figure 10-27. Modifying an existing field type

10-40 System Tailoring, Vol. 1

Page 241: Sct4 System Tailoring Vol.1

4. Click OK to close the window and commit the change to the file.

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.

Figure 10-28. Existing field with modified data type

Adding and Modifying 10-41

Page 242: Sct4 System Tailoring Vol.1

Modifying a KeyAs 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 System Tailoring, Vol. 1

Page 243: Sct4 System Tailoring Vol.1

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-29. Modifying an existing key type

Figure 10-30. Existing key with modifying type value

Adding and Modifying 10-43

Page 244: Sct4 System Tailoring Vol.1

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 System Tailoring, Vol. 1

Page 245: Sct4 System Tailoring Vol.1

4. Click OK to close the window.

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.

Figure 10-31. Adding concatenated value to existing key

Figure 10-32. Existing key modified to become concatenated

Adding and Modifying 10-45

Page 246: Sct4 System Tailoring Vol.1

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 System Tailoring, Vol. 1

Page 247: Sct4 System Tailoring Vol.1

Deleting a FieldAfter 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. Let’s 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.

Adding and Modifying 10-47

Page 248: Sct4 System Tailoring Vol.1

2. Click Edit.

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.

Figure 10-33. Deleting a field

10-48 System Tailoring, Vol. 1

Page 249: Sct4 System Tailoring Vol.1

Figure 10-34. Field removed from record

Adding and Modifying 10-49

Page 250: Sct4 System Tailoring Vol.1

Deleting a KeyAlong 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

Page 251: Sct4 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.

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.

Figure 10-36. Record with key deleted

Adding and Modifying 10-51

Page 252: Sct4 System Tailoring Vol.1

10-52 System Tailoring, Vol. 1

Page 253: Sct4 System Tailoring Vol.1

Chapter 11Advanced Operations

Copying a Database DictionaryYou 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

Page 254: Sct4 System Tailoring Vol.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.

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.

Figure 11-2. Copying the data structure record only

11-2 System Tailoring, Vol. 1

Page 255: Sct4 System Tailoring Vol.1

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.

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 non-peak operation times.

Figure 11-3. Copy/Rename Options menu selection

Advanced Operations 11-3

Page 256: Sct4 System Tailoring Vol.1

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.

Figure 11-4. Making backup of current record and data

11-4 System Tailoring, Vol. 1

Page 257: Sct4 System Tailoring Vol.1

Renaming a Database Dictionary RecordAfter 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.

5. Click OK.

Figure 11-5. Renaming current record and data

Advanced Operations 11-5

Page 258: Sct4 System Tailoring Vol.1

The renamed Database Dictionary record is displayed with the following message in the status bar: Dbdict successfully renamed.

6. Click OK to exit the record and save the file with the new name.

Figure 11-6. Renamed record

11-6 System Tailoring, Vol. 1

Page 259: Sct4 System Tailoring Vol.1

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

Page 260: Sct4 System Tailoring Vol.1

Resetting the Database and All RecordsIf 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 pre-implemented 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.

11-8 System Tailoring, Vol. 1

Page 261: Sct4 System Tailoring Vol.1

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.

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.

Figure 11-7. Scheduling file resetting action

Advanced Operations 11-9

Page 262: Sct4 System Tailoring Vol.1

You are returned to the Database Dictionary file which will be reset.

11-10 System Tailoring, Vol. 1

Page 263: Sct4 System Tailoring Vol.1

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

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.

Figure 11-8. Data and index pools

Advanced Operations 11-11

Page 264: Sct4 System Tailoring Vol.1

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 System Tailoring, Vol. 1

Page 265: Sct4 System Tailoring Vol.1

Searching for a FieldThe 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.

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.

Figure 11-9. Fieldname search capability

Advanced Operations 11-13

Page 266: Sct4 System Tailoring Vol.1

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 System Tailoring, Vol. 1

Page 267: Sct4 System Tailoring Vol.1

Chapter 12Notification 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

Page 268: Sct4 System Tailoring Vol.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 System Tailoring, Vol. 1

Page 269: Sct4 System Tailoring Vol.1

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.

Figure 12-1. The Notification Definition Panel

Notification Engine 12-3

Page 270: Sct4 System Tailoring Vol.1

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 System Tailoring, Vol. 1

Page 271: Sct4 System Tailoring Vol.1

the message will be sent, and the arguments the message will use, by editing the record’s 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 Record’s Name and Condition in the search fields, if you know them, and click Search. The related Notification Records will appear. If you didn’t 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 message’s 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 it’s 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

Page 272: Sct4 System Tailoring Vol.1

either a single person or a group name. If a group’s 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 Record’s 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 record’s 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 12-2.) The Notification Definition window will appear.

2. Enter the Notification Record’s Name and Condition in the search fields, if you know them, and click Search. The related Notification Records will appear. If you didn’t 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.

12-6 System Tailoring, Vol. 1

Page 273: Sct4 System Tailoring Vol.1

7. Enter the Arguments the message should use, if necessary.

Depending on the referenced message’s 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 it’s 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 name’s 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

Page 274: Sct4 System Tailoring Vol.1

Notification FlowChart

Notification Engine

ServiceCenter eventfires off a Notification.

Do theconditions in this

record evaluate totrue?

Yes

ServiceCenterMessenging sends out

the m essage asspecified in the

Notification Record.

Do theconditions in thisrow evaluate to

true?

Notification Engineloops through each row

in the Record, exitingwhen com plete.

Yes

Notification Engineloops through each rowin the Notification file,exiting when com plete

No

No

12-8 System Tailoring, Vol. 1

Page 275: Sct4 System Tailoring Vol.1

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 record’s 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 message’s 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 message’s Severity.

8. Edit the message’s 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

Page 276: Sct4 System Tailoring Vol.1

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.

Figure 12-2. The scmessage panel

12-10 System Tailoring, Vol. 1

Page 277: Sct4 System Tailoring Vol.1

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

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.

Figure 12-3. The Message Type Panel

Notification Engine 12-11

Page 278: Sct4 System Tailoring Vol.1

On Call SchedulingNotifications 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 System Tailoring, Vol. 1

Page 279: Sct4 System Tailoring Vol.1

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

Figure 12-4. The OnCall Schedule Panel

Notification Engine 12-13

Page 280: Sct4 System Tailoring Vol.1

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.

12-14 System Tailoring, Vol. 1

Page 281: Sct4 System Tailoring Vol.1

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 contact’s 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 contact’s 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

Page 282: Sct4 System Tailoring Vol.1

Oncall Flow

On Call Scheduling

New Oncall schedule isproduced at midnight.

Is this persononcall today?

Yes

A ServiceCenter Eventsends a notification tothe Oncall Notification

Group.

Notification engineloops

through the oncallrecords.

No

An Administratorenters the dailyschedules into

oncallsched

Message is sent viathe method specified

in the NotificationRecord.

Notification engine goesto the next row in therecord, exiting when

complete.

12-16 System Tailoring, Vol. 1

Page 283: Sct4 System Tailoring Vol.1

Daily On Call RecordsThe 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 administrator’s 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

Page 284: Sct4 System Tailoring Vol.1

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.

The members of the group have had their regular, daily schedules defined, as per the field definitions for this panel. Note FALCON’s 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.

Figure 12-6. Example On Call Schedule

12-18 System Tailoring, Vol. 1

Page 285: Sct4 System Tailoring Vol.1

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.

Figure 12-7. Example On Call Exceptions

Notification Engine 12-19

Page 286: Sct4 System Tailoring Vol.1

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:

Figure 12-8. Example Daily On Call Schedule

Notification Record Action

Clone Relation sent when a user copies associations of a cloned incident or call

CM Approve sent when a user approves a change phase

Table 12-1. Notifications

12-20 System Tailoring, Vol. 1

Page 287: Sct4 System Tailoring Vol.1

CM Change Close sent when a user closes a change phase

CM Change Open sent when a user opens a change phase

CM Change Update sent when a user updates a change phase or opens one that’s been deferred

CM Disapprove sent when a user disapproves a change

CM Task Close sent when a user closes a task phase

CM Task Open sent when a user opens a task phase

CM Task Update sent when a user updates a task phase or opens one that’s been deferred

CM Unapprove sent when a user unapproves a change phase

CM Unapprove All sent when a user unapproves all levels of a change phase

CM Unapprove One sent when a user unapproves one level of a change phase

due date notice sends the message that corresponds to the due date notice alert

ICM Attribute Add sent when a user adds an attribute

ICM Attribute Update sent when a user updates an attribute

ICM Children Update sent when a user updates a device's children

ICM Delete sent when a user deletes a device type

ICM Device Add sent when a user adds a device

ICM Device Update sent when a user updates a device

late notice sent when an item reaches due date

IM Action Alert sent when a user updates an incident’s alert status

IM Action Close sent when a user closes an incident

IM Action Open sent when a user opens an incident

IM Action Reopen sent when a user reopens an incident

IM Action Update sent when a user updates an incident

IM Alert Reassign sent when an incident exceeds the reassignment limit

IM Edit Close sent when a user closes an incident

Notification Record Action

Table 12-1. Notifications

Notification Engine 12-21

Page 288: Sct4 System Tailoring Vol.1

IM Edit Close Cascade sent when a user closes an incident and its related calls

IM Edit Close Linked sent when a user closes an incident but not its related calls

IM Edit Open sent when a user opens an incident

IM Edit Reopen sent when a user reopens an incident

IM Edit Resolve sent when a user resolves an incident

IM Edit Update sent when a user updates an incident

IM First Open sent when a user opens an incident

IM First Close sent when a user closes an incident

IM First Resolve sent when a user resolves an incident

IM Save Relation sent when a user opens a related incident for a call and ends up linking the call to an existing incident instead

RM Approval sent when any approval action is taken against the request or order

RM Denial sent when any denial action is taken against the request or order

RM Final Approval sent when the request is completely approved

RM Final Denial sent when the request is completely denied

RM Line Item Change Category

sent when a user manually changes the category of a line item

RM Line Item Close sent when a user manually closes a line item

RM Line Item Drop Avail

sent when a user marks a line item as unavailable

RM Line Item Mark Avail

sent when a user marks a line item as available to order

RM Line Item Open sent when a user opens a new line item

RM Line Item Reopen sent when a line item is reopened

RM Line Item Update sent when a line item is updated

RM Order Change Category

sent when a user manually changes the category of the order

Notification Record Action

Table 12-1. Notifications

12-22 System Tailoring, Vol. 1

Page 289: Sct4 System Tailoring Vol.1

RM Order Close sent when an order is closed

RM Order Open sent when an order is opened

RM Order Update sent when an order is updated

RM Request Change Category

sent when a user manually changes the request category

RM Request Close sent when an order is closed

RM Request Deferred sent when a request is deferred

Request Late Notice sent after a specified due date

Request Not Approved sent when a request is denied or not approved

Request Not Ordered sent if the request is not in the ordering phase within one day of the date that the first line item is ordered.

RM Request Open sent when a request is opened

RM Request Open Next Phase

sent when the quote moves from one phase to the next

RM Request Phase Change

sent when a user manually changes the phase of the request

RM Request Reopen sent when a request is reopened

RM Request Update sent when a request is updated

SM Add sent when a call is opened in an active state

SM Close sent when a call is closed

SM Save sent when a call is opened in an inactive state

SM Update sent when a call is updated

Save Association sent when linking two associated records

Save Relation sent when opening a related record

Notification Record Action

Table 12-1. Notifications

Notification Engine 12-23

Page 290: Sct4 System Tailoring Vol.1

12-24 System Tailoring, Vol. 1

Page 291: Sct4 System Tailoring Vol.1

Chapter 13Introduction to Format Control

OverviewChapters 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 user–defined 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

Page 292: Sct4 System Tailoring Vol.1

Knowledge Requirements

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 System Tailoring, Vol. 1

Page 293: Sct4 System Tailoring Vol.1

Chapter 14What 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

Page 294: Sct4 System Tailoring Vol.1

Format Control Process Flow

Validations Succeed Validations Succeed Validations Succeed

Validations Fail Validations Fail

File Opened by User

Format Control Applied Before

Display

Data Displayedon Screen

User Action

Add a New Record

Delete the Current Record

Format Control Applied Before

Add

Format Control Applied Before

Update

Format Control Applied Before

Delete

Record Updated in Database

Format Control Applied After

Update

Format Control Applied After

Delete

Initialization Process of Format Control

Format Control Applied After

Add

AA

A A

Update the Current Record

RecordDeleted From

Database

Record Added to Database

Record(s) Selected from

Database

Format Control Record Selected

14-2 System Tailoring, Vol. 1

Page 295: Sct4 System Tailoring Vol.1

Format Control ProcessesThere 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.

What is Format Control? 14-3

Page 296: Sct4 System Tailoring Vol.1

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 System Tailoring, Vol. 1

Page 297: Sct4 System Tailoring Vol.1

Long ViewLong ViewLong View

Short View

What is Format Control? 14-5

Page 298: Sct4 System Tailoring Vol.1

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 ServiceCenter’s 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

14-6 System Tailoring, Vol. 1

Page 299: Sct4 System Tailoring Vol.1

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 non–string 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

Page 300: Sct4 System Tailoring Vol.1

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 user’s 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 System Tailoring, Vol. 1

Page 301: Sct4 System Tailoring Vol.1

Chapter 15Getting Started

Accessing Format ControlYou 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 administrator’s 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

Page 302: Sct4 System Tailoring Vol.1

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 administrator’s 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.

Figure 15-1. Main Format Control Form

15-2 System Tailoring, Vol. 1

Page 303: Sct4 System Tailoring Vol.1

Adding a RecordTo 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 form’s 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

Page 304: Sct4 System Tailoring Vol.1

15-4 System Tailoring, Vol. 1

Page 305: Sct4 System Tailoring Vol.1

Chapter 16Format 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,

Format Control Processes 16-1

Page 306: Sct4 System Tailoring Vol.1

editing tools (Insert Line, Delete Line) are included in the menu. See Menu 2 below.

Menu 1Menu 2

16-2 System Tailoring, Vol. 1

Page 307: Sct4 System Tailoring Vol.1

InitializationsThe 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

Format Control Processes 16-3

Page 308: Sct4 System Tailoring Vol.1

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.

problem.initial

problem.initial.g

problem.initial.w

problem.initial

Form Name

Format Control Record

Figure 16-2. Naming Process for Format Control Records

16-4 System Tailoring, Vol. 1

Page 309: Sct4 System Tailoring Vol.1

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.

Format Control Processes 16-5

Page 310: Sct4 System Tailoring Vol.1

Figure 16-3. Contacts Query Form

16-6 System Tailoring, Vol. 1

Page 311: Sct4 System Tailoring Vol.1

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.

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.

Figure 16-4. Complete Contact Record

Format Control Processes 16-7

Page 312: Sct4 System Tailoring Vol.1

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 Input values

Contact Name contact.nameFirst Name first.nameCompany companyPhone phoneEmail email

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.

Figure 16-5. Custom QBE Form

16-8 System Tailoring, Vol. 1

Page 313: Sct4 System Tailoring Vol.1

Save Copy

If this option is selected, a copy or image of the primary file’s 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 file’s 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.

Format Control Processes 16-9

Page 314: Sct4 System Tailoring Vol.1

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 system’s 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 Syntaxcharacter $x=" "number $number=0date/time $dt= '00:00:00'boolean (true/false) $end=false or $end=farrays $array={}

Note: You can set the value of variables to NULL after establishing their types.

16-10 System Tailoring, Vol. 1

Page 315: Sct4 System Tailoring Vol.1

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’

Format Control Processes 16-11

Page 316: Sct4 System Tailoring Vol.1

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 System Tailoring, Vol. 1

Page 317: Sct4 System Tailoring Vol.1

ValidationsThe 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. Validations—Short Form

Format Control Processes 16-13

Page 318: Sct4 System Tailoring Vol.1

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 System Tailoring, Vol. 1

Page 319: Sct4 System Tailoring Vol.1

Comments

Brief comment about the field being validated.

Examples

Required Fields

Use the following values to make a field (location) required when adding a record or updating a database file:

Add Updatetrue true

Figure 16-7. Validations—Long Form

Format Control Processes 16-15

Page 320: Sct4 System Tailoring Vol.1

Validationsnot null (location in $file)

orlocation in $file~=NULL

orlocation in $file<>NULL

On Failed Validation Set Focus To

location

MessageThe location field is required.

Specific Values

To make a field begin with a specific value when adding or updating a record:

Add Updatetrue true

Validationstype in $file #“US”

On Failed Validation Set Focus To

type

MessageThe type field must begin with US.

Range of Values

To validate a value within a range:

• Add Updatetrue true

Validationsamount in $file<=100000

On Failed Validation Set Focus Toamount

MessageThe amount cannot be greater than 100000.00

• Add Updatetrue true

Validationsno.of.cables in $file>2 and no.of.cables in $file<25

On Failed Validation Set Focus Tono.of.cables

Message

16-16 System Tailoring, Vol. 1

Page 321: Sct4 System Tailoring Vol.1

The number of cables must be within 3 and 24.

• Add Updatetrue true

Validationsdept in $file#“101” or dept in $file#“102”

On Failed Validation Set Focus Todept

MessageInvalid 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 Update

True 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 Update

$atlsales $atlsales

Format Control Processes 16-17

Page 322: Sct4 System Tailoring Vol.1

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.

Add Update$charge $charge

Validationsrepair.charge in $file>0

On Failed Validation Set Focus To

repair.charge

MessageWhen 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 Updatetrue 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 System Tailoring, Vol. 1

Page 323: Sct4 System Tailoring Vol.1

will work.

A. Add Updatetrue true

Validationlng(denull($errorlist))=0

MessageFor each DEVICE COVERED you must supply a serial number

Format Control Processes 16-19

Page 324: Sct4 System Tailoring Vol.1

B. Add Updatelng(denull($errorlist))>0 lng(denull($errorlist))>0

Validationfalse

MessageFor each DEVICE COVERED you must supply a serial number.

16-20 System Tailoring, Vol. 1

Page 325: Sct4 System Tailoring Vol.1

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. Calculations—Short Form

Format Control Processes 16-21

Page 326: Sct4 System Tailoring Vol.1

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 System Tailoring, Vol. 1

Page 327: Sct4 System Tailoring Vol.1

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

Figure 16-9. Calculations—Long Form

Format Control Processes 16-23

Page 328: Sct4 System Tailoring Vol.1

• Perform expressions (math) on variables given below:

$a=8, $b=4, $c=5, $d=2

calculations results

$x=$c*$b+1 $x=21

$x=$c*($b+1) $x=25

$x=$a*$c/$b - $d $x=8

Note: Multiplication (*) and division(/) are calculated first—addition (+) 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 manufacturer’s 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.examplearrayed.structure.examplemanufacturermodelquantitypriceamount

16-24 System Tailoring, Vol. 1

Page 329: Sct4 System Tailoring Vol.1

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.00amount=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.00amount=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)

Format Control Processes 16-25

Page 330: Sct4 System Tailoring Vol.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 System Tailoring, Vol. 1

Page 331: Sct4 System Tailoring Vol.1

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:

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 1description line 2

UPDATE ACTIVITY

$action={"DESCRIPTION"}+denull(action in $file)+{"UPDATE ACTIVITY"}+denull(update.action in $file)+denull(resolution in $file)

Format Control Processes 16-27

Page 332: Sct4 System Tailoring Vol.1

update line 1update line 2update line 3

16-28 System Tailoring, Vol. 1

Page 333: Sct4 System Tailoring Vol.1

Additional File QueriesSelect 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.

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.

Figure 16-10. Additional File Queries—Short Form

Format Control Processes 16-29

Page 334: Sct4 System Tailoring Vol.1

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.

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

Figure 16-11. Additional File Queries—Long Form

16-30 System Tailoring, Vol. 1

Page 335: Sct4 System Tailoring Vol.1

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 number—that 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: Req’d)

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 contact’s 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

Format Control Processes 16-31

Page 336: Sct4 System Tailoring Vol.1

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 file—please re–enter.

Examples

Report Information

Create a report to list hardware problems associated with different vendors. A vendor’s 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 report’s detail form:

Field Values:

filename

16-32 System Tailoring, Vol. 1

Page 337: Sct4 System Tailoring Vol.1

vendor

queryname=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 calculation expressiontrue $address=address in $file1true $phone=phone in $file1

Explanation

display: true—To be performed on display of report (always true for reports).

filename: vendor—The vendor is the secondary file ($file1).

query: name=vendor.name in $file—The query needs to match the value of the name field in the vendor file with the vendor.name field in the problem file.

calculation expression—Moves 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.

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 querymodel model.name=model in $file

add update true true

Required Query? Required Field Nametrue (all records) model

Error MessageModel is not a valid model in the model file - please re-enter.

Format Control Processes 16-33

Page 338: Sct4 System Tailoring Vol.1

Explanation

AddTo be performed before adding record.

UpdateTo be performed before updating record.

FilenameThe secondary file query will access the model file.

Required Field NameThe validation only occurs if the model field is not NULL.

QueryThe 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 MessageThis 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 System Tailoring, Vol. 1

Page 339: Sct4 System Tailoring Vol.1

SecurityTo 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

Format Control Processes 16-35

Page 340: Sct4 System Tailoring Vol.1

SysAdmin privileges, SysAdmin users can click Administration Mode from the initial Database Manager screen..

Fields

Fields on the Standard Tab

Add

Controls a user’s ability to add a record to the database. This applies to Add and Add/Retain. The default value is true.

Figure 16-12. Security Process: Standard Tab

16-36 System Tailoring, Vol. 1

Page 341: Sct4 System Tailoring Vol.1

Update

Controls a user’s ability to update a record. The default value is true.

Delete

Controls a user’s 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.

Format Control Processes 16-37

Page 342: Sct4 System Tailoring Vol.1

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 System Tailoring, Vol. 1

Page 343: Sct4 System Tailoring Vol.1

.

Fields on the Advanced Tab

Load

Determines the user’s ability to load data from an external file into the current file. The default value is false.

Unload

Figure 16-13. Security Process: Advanced Tab

Format Control Processes 16-39

Page 344: Sct4 System Tailoring Vol.1

Controls a user’s 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 System Tailoring, Vol. 1

Page 345: Sct4 System Tailoring Vol.1

SubroutinesSelect 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. Subroutines—Short Form

Format Control Processes 16-41

Page 346: Sct4 System Tailoring Vol.1

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 System Tailoring, Vol. 1

Page 347: Sct4 System Tailoring Vol.1

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)

Figure 16-15. Subroutines—Long Form

Format Control Processes 16-43

Page 348: Sct4 System Tailoring Vol.1

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 System Tailoring, Vol. 1

Page 349: Sct4 System Tailoring Vol.1

5. The dbdict record for the contacts file is displayed.

6. Place the cursor in the descriptor field of the dbdict.

7. Click on the New button.

Figure 16-16. Contacts Database Record

Format Control Processes 16-45

Page 350: Sct4 System Tailoring Vol.1

8. Enter fingerprint in the Name field of the edit box and select array from the drop–down list.

9. Click on the OK button.

10. Enter fingerprint in the Name field of the edit box and select character from the drop–down 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 System Tailoring, Vol. 1

Page 351: Sct4 System Tailoring Vol.1

Note: Refer to the Forms Designer documentation for details on creating forms.

Property Value

Input fingerprintX 2Y 2Height 2Width 56Array Length 10

6. Select the Label tool and name the field Last Updated.

7. Your new form will look like this:

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.

Figure 16-17. The show.fingerprint Form

Format Control Processes 16-47

Page 352: Sct4 System Tailoring Vol.1

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.

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.

Figure 16-18. Initializations Form of Format Control

16-48 System Tailoring, Vol. 1

Page 353: Sct4 System Tailoring Vol.1

7. Enter the following data in the Alternate Views structure of the Views form:

Display Format Name Condition

show.fingerprint index("SysAdmin",$lo.ucapex)>0contacts true

The Condition expression for the show.fingerprint form restricts viewing privileges to users with System Administrator capabilities only.

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.

Figure 16-19. Using the Views Process for Fingerprinting

Format Control Processes 16-49

Page 354: Sct4 System Tailoring Vol.1

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 Add Update Beforefingerprint true true true

Parameters:

Name Value

record $fileindex val("10", 1)string1 Updated

4. Your Subroutines form will look like this:

Figure 16-20. Fingerprint Call from Subroutines

16-50 System Tailoring, Vol. 1

Page 355: Sct4 System Tailoring Vol.1

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.

Format Control Processes 16-51

Page 356: Sct4 System Tailoring Vol.1

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.

13. Select show.fingerprint to display the fingerprinting form you created.

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.

Figure 16-21. Views QBE List

Figure 16-22. Fingerprint Record

16-52 System Tailoring, Vol. 1

Page 357: Sct4 System Tailoring Vol.1

Additional OptionsSelect 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 F–keys) 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 user’s 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.

Format Control Processes 16-53

Page 358: Sct4 System Tailoring Vol.1

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 F–keys 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.

Figure 16-23. Additional Options—Short Form

16-54 System Tailoring, Vol. 1

Page 359: Sct4 System Tailoring Vol.1

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.

Figure 16-24. Additional Options—Long Form

Format Control Processes 16-55

Page 360: Sct4 System Tailoring Vol.1

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 browse–only 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 F–keys 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 1–12, 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/F–key 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 user’s 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 button’s function in the Command field. This label will appear on the button in the Service Tray.

16-56 System Tailoring, Vol. 1

Page 361: Sct4 System Tailoring Vol.1

For example:

Option# Command1 Location

This button/F–key accesses the location file.

Description

Enter a plain text description of the option’s 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:

namename

Format Control Processes 16-57

Page 362: Sct4 System Tailoring Vol.1

Value

Enter the name of the field, value or form to be passed to the application.

For example:

valuelocation

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 System Tailoring, Vol. 1

Page 363: Sct4 System Tailoring Vol.1

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

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.

Figure 16-25. Sample Additional Options Prompt Box

Option # Condition Command Application Reset on Return

Names Values

1 true Location database false name location

2 true Clients database false name company.g

Format Control Processes 16-59

Page 364: Sct4 System Tailoring Vol.1

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 System Tailoring, Vol. 1

Page 365: Sct4 System Tailoring Vol.1

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

Figure 16-26. Blank Clients Record

Format Control Processes 16-61

Page 366: Sct4 System Tailoring Vol.1

ViewsThe 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 System Tailoring, Vol. 1

Page 367: Sct4 System Tailoring Vol.1

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 operator’s 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.

Format Control Processes 16-63

Page 368: Sct4 System Tailoring Vol.1

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 Input values

Login Name nameCapabilities cap.execPassword passwordLast Login last.login

16-64 System Tailoring, Vol. 1

Page 369: Sct4 System Tailoring Vol.1

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.

Figure 16-28. Custom QBE Form

Format Control Processes 16-65

Page 370: Sct4 System Tailoring Vol.1

8. Click on the Yes button. You will see a Format Control record with operator.capability in the name field.

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.

Figure 16-29. Format Control Record for operator.capability Form

16-66 System Tailoring, Vol. 1

Page 371: Sct4 System Tailoring Vol.1

This Condition expression restricts viewing privileges to users with System Administrator capabilities only.

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

Figure 16-30. Establishing Security for the operator.capability Form

Format Control Processes 16-67

Page 372: Sct4 System Tailoring Vol.1

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 Condition

operator.capability index("SysAdmin", $lo.ucapex)>0operator.qbe true

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.

Figure 16-31. Views Process for operator File

16-68 System Tailoring, Vol. 1

Page 373: Sct4 System Tailoring Vol.1

The Condition expression for the operator form restricts viewing privileges to users with System Administrator capabilities only.

11. Click on the OK button.

Figure 16-32. Restricting Access in Security Process

Format Control Processes 16-69

Page 374: Sct4 System Tailoring Vol.1

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 System Tailoring, Vol. 1

Page 375: Sct4 System Tailoring Vol.1

6. Click on the Views button to display the available QBE list choices.

7. Select operator.capability from the list

Figure 16-34. Views QBE List

Figure 16-35. Custom QBE List Displayed

Format Control Processes 16-71

Page 376: Sct4 System Tailoring Vol.1

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 System Tailoring, Vol. 1

Page 377: Sct4 System Tailoring Vol.1

Chapter 17Array 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 StructuresThe 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 re–displays 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

Page 378: Sct4 System Tailoring Vol.1

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

Figure 17-1. Custom Form Illustrating Arrayed Structures

Structure

17-2 System Tailoring, Vol. 1

Page 379: Sct4 System Tailoring Vol.1

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

Page 380: Sct4 System Tailoring Vol.1

O

2

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 administrator’s 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:..

ption # Condition Desc Application Reset on Return Names Values

true Options as.options true file

name

$file

service

17-4 System Tailoring, Vol. 1

Page 381: Sct4 System Tailoring Vol.1

8. In addition, enter Could not execute into the Message field. The record appears as follows:

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

Figure 17-2. Format Control Record for service Form

Array Maintenance 17-5

Page 382: Sct4 System Tailoring Vol.1

8. Select a record from the QBE list. For this example, we have chosen ibm santa fe – Service Agreement # 123456.

17-6 System Tailoring, Vol. 1

Page 383: Sct4 System Tailoring Vol.1

9. The IBM Santa Fe Service Agreement record is displayed.

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.

Figure 17-3. Service Agreement with Normal Button Options

Array Maintenance 17-7

Page 384: Sct4 System Tailoring Vol.1

• 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 System Tailoring, Vol. 1

Page 385: Sct4 System Tailoring Vol.1

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.

Array Maintenance 17-9

Page 386: Sct4 System Tailoring Vol.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 System Tailoring, Vol. 1

Page 387: Sct4 System Tailoring Vol.1

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

Page 388: Sct4 System Tailoring Vol.1

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

Error Message for each subroutine call above:

Could not execute.

Option # Condition Desc Application Reset on Return

Names Values

1 true Copy as.copy true file

index

$file

val("18", 1)

2 true Delete as.delete true file

index

$file

val("18", 1)

4 true Insert as.insert true file

index

$file

val("18", 1)

5 true Move as.move true file

index

$file

val("18", 1)

17-12 System Tailoring, Vol. 1

Page 389: Sct4 System Tailoring Vol.1

8. The record appears as follows:

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.

Figure 17-4. Format Control Record for service Form

Array Maintenance 17-13

Page 390: Sct4 System Tailoring Vol.1

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.

Figure 17-5. Service Agreement with Normal Button Options

17-14 System Tailoring, Vol. 1

Page 391: Sct4 System Tailoring Vol.1

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

Array Maintenance 17-15

Page 392: Sct4 System Tailoring Vol.1

You can also specify an ascending or descending sort order. You must call this application from Format Control or RAD on an as–needed 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 System Tailoring, Vol. 1

Page 393: Sct4 System Tailoring Vol.1

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

Page 394: Sct4 System Tailoring Vol.1

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.

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.

Figure 17-6. Initialization Expression for as.sort Application

17-18 System Tailoring, Vol. 1

Page 395: Sct4 System Tailoring Vol.1

O

1

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

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 form—the 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:

ption # Condition Command Application Reset on Return Names Values

true Sort as.sort true file

numbers

name

condition

$file

$numbers

devices.covered

$array

Array Maintenance 17-19

Page 396: Sct4 System Tailoring Vol.1

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.

Figure 17-7. Format Control Record for as.sort Application

17-20 System Tailoring, Vol. 1

Page 397: Sct4 System Tailoring Vol.1

Figure 17-8. Service Agreement with Normal Button Options

Array Maintenance 17-21

Page 398: Sct4 System Tailoring Vol.1

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.

Figure 17-9. Service Agreement with Normal Button Options

17-22 System Tailoring, Vol. 1

Page 399: Sct4 System Tailoring Vol.1

Sorting Simple ArraysThe 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 Input Value

Name nameNumbers numberCharacters characterDates date

Array Maintenance 17-23

Page 400: Sct4 System Tailoring Vol.1

Your form should resemble the following:

Create a Format Control Record

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:

Figure 17-10. Demonstration Form for sort.array Utility

Application Name Add Update Before Error Message

sort.array true true true Could not sort the array.

17-24 System Tailoring, Vol. 1

Page 401: Sct4 System Tailoring Vol.1

Parameter values:

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

Names Definition Values

file When calling sort.array from Format Control, always pass $file to this parameter.

$file

name The name of the input field (array) in $file you wish to sort.

number

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

val ("false", 4) *

Array Maintenance 17-25

Page 402: Sct4 System Tailoring Vol.1

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

Figure 17-11. Long Version of the Subroutine Form

17-26 System Tailoring, Vol. 1

Page 403: Sct4 System Tailoring Vol.1

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.

Figure 17-12. Test Data Record

Array Maintenance 17-27

Page 404: Sct4 System Tailoring Vol.1

The Numbers array is sorted in descending order.

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.

Figure 17-13. Sorted Numbers Array

17-28 System Tailoring, Vol. 1

Page 405: Sct4 System Tailoring Vol.1

Chapter 18Sequential Numbering forFormat 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

Page 406: Sct4 System Tailoring Vol.1

Data TypesThere 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 System Tailoring, Vol. 1

Page 407: Sct4 System Tailoring Vol.1

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

Sequential Numbering for Format Control 18-3

Page 408: Sct4 System Tailoring Vol.1

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 System Tailoring, Vol. 1

Page 409: Sct4 System Tailoring Vol.1

Simple Sequential NumbersThis 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

Sequential Numbering for Format Control 18-5

Page 410: Sct4 System Tailoring Vol.1

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 drop–down 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 System Tailoring, Vol. 1

Page 411: Sct4 System Tailoring Vol.1

5. The edited file appears as follows:

Create a Format Control Record

1. Click the Tools button in the Utilities tab in the administrator’s 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.

Figure 18-3. Create a File

Sequential Numbering for Format Control 18-7

Page 412: Sct4 System Tailoring Vol.1

6. Use the following values to complete the Subroutines process: (Refer to “Subroutines” on page 16-41, for information on Subroutines.)

Application Name Add Before Error Message

getnumb.fc true true Sequential number did not process correctly!

Names Definition Values

record The record in which the number will be placed. In this example, the employees datafile.

$file

name The name to appear in the Class field of the Number file generated by the Format Control record.

employees

prompt The field within the record receiving the sequential number. employee.id

18-8 System Tailoring, Vol. 1

Page 413: Sct4 System Tailoring Vol.1

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.

Figure 18-4. The Long Version of the Subroutine Form

Sequential Numbering for Format Control 18-9

Page 414: Sct4 System Tailoring Vol.1

6. Click on the Add button. The sequential number is added to the Employee ID field before the record is added to the database.

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.

Figure 18-5. Sequentially Numbered Data Record

18-10 System Tailoring, Vol. 1

Page 415: Sct4 System Tailoring Vol.1

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.

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.

Figure 18-6. Number File for employees Datafile

Sequential Numbering for Format Control 18-11

Page 416: Sct4 System Tailoring Vol.1

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 System Tailoring, Vol. 1

Page 417: Sct4 System Tailoring Vol.1

Prefixes and SuffixesPrefixes 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.

Create a Format Control Record

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 Add Before Error Message

getnumb.fc true true Sequential number did not process correctly!

Names Definition Values

record The record in which the number will be placed. In this example, the device.workstation record.

$file

name The sequential number class to be used. devices

Sequential Numbering for Format Control 18-13

Page 418: Sct4 System Tailoring Vol.1

The Format Control record appears as follows:

.

prompt The field within the record receiving the sequential number.

logical.name

string1 The string (prefix) to be added to the front of the sequential number when creating a new number.

DEV

query The string (suffix) to be added to the end of the sequential number when creating a new record.

/WS

text Defines the sequential number type (number or string). Since characters occur in the number, this must be string.

string

number1 Determines the length of the sequential number. val(“4”, 1)

Names Definition Values

Figure 18-7. Completed Subroutine Form

18-14 System Tailoring, Vol. 1

Page 419: Sct4 System Tailoring Vol.1

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

Sequential Numbering for Format Control 18-15

Page 420: Sct4 System Tailoring Vol.1

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 System Tailoring, Vol. 1

Page 421: Sct4 System Tailoring Vol.1

Chapter 19Posting

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

Page 422: Sct4 System Tailoring Vol.1

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

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.

Figure 19-1. Link Record

19-2 System Tailoring, Vol. 1

Page 423: Sct4 System Tailoring Vol.1

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

Page 424: Sct4 System Tailoring Vol.1

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 System Tailoring, Vol. 1

Page 425: Sct4 System Tailoring Vol.1

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

Figure 19-2. Linking Individual Fields for Posting

Posting 19-5

Page 426: Sct4 System Tailoring Vol.1

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 System Tailoring, Vol. 1

Page 427: Sct4 System Tailoring Vol.1

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

Page 428: Sct4 System Tailoring Vol.1

Source File

User Action

Add a New Record

Update an Existing Record

Posting Process Flow – Automatic

Format Control Record

LinkRecord

Confirm? Confirm?Yes YesNo

Data Posted to Target File

Record Added to Database

Target File Displayed

Post Add

Target File Displayed

Post Update

Data Posted to Target File

Record Updated in Database

Subroutines

Record Added to Database

Record Updated in Database

No

19-8 System Tailoring, Vol. 1

Page 429: Sct4 System Tailoring Vol.1

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.

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.

Figure 19-3. Setting up Manual Posting in Format Control

Posting 19-9

Page 430: Sct4 System Tailoring Vol.1

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 System Tailoring, Vol. 1

Page 431: Sct4 System Tailoring Vol.1

ExamplesThere 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 field—the 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

Page 432: Sct4 System Tailoring Vol.1

3. Note the input values of the fields you wish to name in the Posting routine.

Field Value

Contact Name contact.nameCorp Structure corp.structureCompany companyWork Phone contact.phone

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.

Figure 19-4. Displaying Field Input Values in the Target File

19-12 System Tailoring, Vol. 1

Page 433: Sct4 System Tailoring Vol.1

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 administrator’s home menu.

The Tools menu is displayed.

2. Click on the Links button.

Posting 19-13

Page 434: Sct4 System Tailoring Vol.1

3. Enter the name of the Link record you wish to create in the Form field of the Link Manager dialogue box—in 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 ValueField Name (SOURCE) requested.byFormat Name (TARGET) contactsField Name (TARGET) contact.nameComment 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 System Tailoring, Vol. 1

Page 435: Sct4 System Tailoring Vol.1

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 Target Field

requested.by contact.namerequest.phone contact.phone

Figure 19-5. Source File Link Record

Posting 19-15

Page 436: Sct4 System Tailoring Vol.1

request.dept corp.structure

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.

Figure 19-6. Link Line Definition Form

19-16 System Tailoring, Vol. 1

Page 437: Sct4 System Tailoring Vol.1

6. The Format Control record for cm3r.hardware is displayed.

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 Value

Application Name post.fcComments POSTAdd trueUpdate trueBefore true

Figure 19-7. Format Control Initializations Form

Posting 19-17

Page 438: Sct4 System Tailoring Vol.1

Names Values

file $filename cm3r.hardware.postprompt requested.by

Error Message

Could not post to contacts file.

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.

Figure 19-8. Format Control Subroutines Setup to Call Posting

19-18 System Tailoring, Vol. 1

Page 439: Sct4 System Tailoring Vol.1

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

Page 440: Sct4 System Tailoring Vol.1

Figure 19-9. Hardware Change Request Form

19-20 System Tailoring, Vol. 1

Page 441: Sct4 System Tailoring Vol.1

5. Select a name from the QBE list of contacts. (The contact information displayed in the QBE list comes from the contacts file.)

6. The system populates the Change Initiator structure with information from the contacts file.

Figure 19-10. Contact Name QBE List

Figure 19-11. Contact Information from a Change Request

Posting 19-21

Page 442: Sct4 System Tailoring Vol.1

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

11. If there are problems, click on the Message button to view posting messages.

Figure 19-12. Updated Contact Phone Information

19-22 System Tailoring, Vol. 1

Page 443: Sct4 System Tailoring Vol.1

12. Open a new change request and change all the contact information including the contact name. See Figure 19-13 for an example.

13. Click on the Save button to save the new request and evoke the Posting process.

Figure 19-13. Establishing a New Contact

Posting 19-23

Page 444: Sct4 System Tailoring Vol.1

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.

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;

Figure 19-14. Contact Record Created from Posting Routine

19-24 System Tailoring, Vol. 1

Page 445: Sct4 System Tailoring Vol.1

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

Page 446: Sct4 System Tailoring Vol.1

Source File

User Action

Format Control Record

LinkRecord

Yes YesNo No

User Options

Target File Displayed

Post Data to Target File

Post Add

Update an Existing Record

Add a New Record

Confirm?Confirm?

Record Added to Database

User Options

Target File Displayed

Post Data to Target File

Post Update

User Options

Post Data to Target File

Record Added to Database

Record Updated in Database

User Options

Post Data to Target File

Record Updated in Database

Additional Options

Figure 19-15. Manual Posting Process Flow

19-26 System Tailoring, Vol. 1

Page 447: Sct4 System Tailoring Vol.1

Source File

User Action

Format Control Record

LinkRecord

Yes YesNo No

User Options

Target File Displayed

Post Data to Target File

Post Add

Update an Existing Record

Add a New Record

Confirm?Confirm?

Record Added to Database

User Options

Target File Displayed

Post Data to Target File

Post Update

User Options

Post Data to Target File

Record Added to Database

Record Updated in Database

User Options

Post Data to Target File

Record Updated in Database

Additional Options

Figure 19-16. Manual Posting Process Flow

Posting 19-27

Page 448: Sct4 System Tailoring Vol.1

4. if the Format Control record does not already exist, click on the New button to create a 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 Value

Option 1Condition for Option trueCommand Post to ContactsDescription Post to ContactsComments POST

Figure 19-17. New Format Control Record

19-28 System Tailoring, Vol. 1

Page 449: Sct4 System Tailoring Vol.1

Application post.fcError Message Could not post to contacts file.Reset on Return true

Names Values

file $filename cm3r.hardware.postprompt 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.

8. Click on the OK button to save your changes.

Figure 19-18. Defining Additional Options for the Source File

Posting 19-29

Page 450: Sct4 System Tailoring Vol.1

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 System Tailoring, Vol. 1

Page 451: Sct4 System Tailoring Vol.1

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.

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.

Figure 19-19. Retrieving an Existing Change Request

Posting 19-31

Page 452: Sct4 System Tailoring Vol.1

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 System Tailoring, Vol. 1

Page 453: Sct4 System Tailoring Vol.1

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.

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.

Figure 19-20. Updated Contact Record

Posting 19-33

Page 454: Sct4 System Tailoring Vol.1

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.

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.

Figure 19-21. Posting Link Record

19-34 System Tailoring, Vol. 1

Page 455: Sct4 System Tailoring Vol.1

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.

Figure 19-22. Posting Link Line with posting confirmation

Posting 19-35

Page 456: Sct4 System Tailoring Vol.1

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 System Tailoring, Vol. 1

Page 457: Sct4 System Tailoring Vol.1

9. The Contact record (target file) for the contact specified in the change request form is displayed, with a 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.

Figure 19-23. Target File with Confirmation Request

Posting 19-37

Page 458: Sct4 System Tailoring Vol.1

19-38 System Tailoring, Vol. 1

Page 459: Sct4 System Tailoring Vol.1

Chapter 20Error 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

Page 460: Sct4 System Tailoring Vol.1

20-2 System Tailoring, Vol. 1

Page 461: Sct4 System Tailoring Vol.1

Chapter 21Special Processing Considerations

Incident ManagementIn 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

Page 462: Sct4 System Tailoring Vol.1

Change ManagementChange 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 System Tailoring, Vol. 1

Page 463: Sct4 System Tailoring Vol.1

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.

Special Processing Considerations 21-3

Page 464: Sct4 System Tailoring Vol.1

Eventout RecordsWhen 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 System Tailoring, Vol. 1

Page 465: Sct4 System Tailoring Vol.1

The Subroutine form for the problem.equipment.open form looks like this:

Figure 21-1. Subroutine for Incident Management

Special Processing Considerations 21-5

Page 466: Sct4 System Tailoring Vol.1

Page MessagesSCAuto 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 Value

name contact.name in contacts file or name in operator file (SP4 or >)

prompt numeric messagetext alphanumeric messagestring1 separation characterquery user sequence numbervalues list of contact.name or name values (SP4 or >)names, 1 a pager phone number (ignored if value is passed in name or

values (SP4 or >)names, 2 pager PIN number (SP4 or >)names, 3 the name of a record in the distgroup file that contains a list of

names or contact.names (optional–SP4 or >)

21-6 System Tailoring, Vol. 1

Page 467: Sct4 System Tailoring Vol.1

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.

Special Processing Considerations 21-7

Page 468: Sct4 System Tailoring Vol.1

21-8 System Tailoring, Vol. 1

Page 469: Sct4 System Tailoring Vol.1

Chapter 22Common 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

Page 470: Sct4 System Tailoring Vol.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 System Tailoring, Vol. 1

Page 471: Sct4 System Tailoring Vol.1

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.

Common Applications Called from Format Control 22-3

Page 472: Sct4 System Tailoring Vol.1

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 System Tailoring, Vol. 1

Page 473: Sct4 System Tailoring Vol.1

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 ID’s defined in the operator table. For email, the names can either be operator ID’s 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

Page 474: Sct4 System Tailoring Vol.1

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 Name Value

all fields second.file $filea specific field second.file $file

name <field name>a range of fields second.file $file

names $array (defined in Initializations

22-6 System Tailoring, Vol. 1

Page 475: Sct4 System Tailoring Vol.1

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

Common Applications Called from Format Control 22-7

Page 476: Sct4 System Tailoring Vol.1

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 System Tailoring, Vol. 1

Page 477: Sct4 System Tailoring Vol.1

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

Common Applications Called from Format Control 22-9

Page 478: Sct4 System Tailoring Vol.1

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 recipient’s login ID.

prompt

This parameter defines the recipient’s 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 System Tailoring, Vol. 1

Page 479: Sct4 System Tailoring Vol.1

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.

Common Applications Called from Format Control 22-11

Page 480: Sct4 System Tailoring Vol.1

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 System Tailoring, Vol. 1

Page 481: Sct4 System Tailoring Vol.1

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

Common Applications Called from Format Control 22-13

Page 482: Sct4 System Tailoring Vol.1

The parameter Name appears in the Input field of the form and the function appears in the Label field.

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.

Parameter Name

Parameter Description

22-14 System Tailoring, Vol. 1

Page 483: Sct4 System Tailoring Vol.1

Chapter 23Introduction 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 Designer—Provides a brief description of the follow-on chapters and describes the knowledge requirements for users.

• Chapter 24, Dynamic View Dependencies—Introduces 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 Elements—Introduces you to the basic elements of Forms Designer.

• Chapter 26, The Forms Design Process—Outlines the steps required to access Forms Designer and provides a preview of the forms design process.

• Chapter 27, The Properties Window—Describes the types of properties that appear in the Properties Window and how to set property values.

• Chapter 28, The Tools Palette—Provides detailed descriptions of the 18 tools available in the Tools Palette and the design objects you can create with them.

• Chapter 29, The Form Wizard—Describes how to use the Form Wizard to create a new form.

• Chapter 30, Tutorial: Creating a New Form—Leads 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 Tips—Provides tips for designing forms that meet your specific needs.

Introduction to Forms Designer 23-1

Page 484: Sct4 System Tailoring Vol.1

Knowledge RequirementsThe instructions in this manual assume a working knowledge of ServiceCenter. Additional reference information can be found in the ServiceCenter User’s Guide and the ServiceCenter System Administrator’s Guide. To access Forms Designer, you must be logged in as an administrator (for example, FALCON).

23-2 System Tailoring, Vol. 1

Page 485: Sct4 System Tailoring Vol.1

Chapter 24Dynamic 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

Page 486: Sct4 System Tailoring Vol.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.

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.

Associated properties

Figure 24-1. Properties Window

24-2 System Tailoring, Vol. 1

Page 487: Sct4 System Tailoring Vol.1

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)

Dynamic View Dependencies 24-3

Page 488: Sct4 System Tailoring Vol.1

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 System Tailoring, Vol. 1

Page 489: Sct4 System Tailoring Vol.1

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

Dynamic View Dependencies 24-5

Page 490: Sct4 System Tailoring Vol.1
Page 491: Sct4 System Tailoring Vol.1

Chapter 25Forms 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

Page 492: Sct4 System Tailoring Vol.1

The Drawing CanvasWhen 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.

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.

Figure 25-1. The Drawing Canvas

25-2 System Tailoring, Vol. 1

Page 493: Sct4 System Tailoring Vol.1

Structure of the canvas

The canvas contains an invisible grid to which all design objects are referenced. Figure 25-2 illustrates this 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 form’s ultimate size. Ideally, you will want to create a form that is completely visible on the user’s screen so that the user does not have to scroll to view any area of the form.

X coordinates

Y coordinates

0 30 60 90 120 150 180

0

10

20

30

40

Figure 25-2. The Invisible Grid

Forms Designer Elements 25-3

Page 494: Sct4 System Tailoring Vol.1

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 user’s 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 System Tailoring, Vol. 1

Page 495: Sct4 System Tailoring Vol.1

The Tools PaletteThe 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.

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.

Pointer Label Text Box

Button Bevel Frame

Multi- Line Text

Fill Box Picture

CheckBox

Radio Button

Combo Box

MarqueeSub-format Chart

Figure 25-3. The Tools Palette

Table Tab

OLE Container

Wrapping Label

Forms Designer Elements 25-5

Page 496: Sct4 System Tailoring Vol.1

The Properties WindowWhen 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.

For more information about the Properties Window and how to set properties, refer to Chapter 27, The Properties Window.

Figure 25-4. Properties Window for a Label

Edit Area

25-6 System Tailoring, Vol. 1

Page 497: Sct4 System Tailoring Vol.1

The Form WizardThe 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.

Refer to Chapter 29, The Form Wizard for a complete description of how to access and use the Form Wizard to create new forms.

Figure 25-5. Accessing the Form Wizard

Forms Designer Elements 25-7

Page 498: Sct4 System Tailoring Vol.1

25-8 System Tailoring, Vol. 1

Page 499: Sct4 System Tailoring Vol.1

Chapter 26The Forms Design Process

Accessing Forms DesignerTo 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

Page 500: Sct4 System Tailoring Vol.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 form’s 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 System Tailoring, Vol. 1

Page 501: Sct4 System Tailoring Vol.1

5. A Drawing Canvas, Properties Window, and Tools Palette are displayed.

With the Drawing Canvas, Tools Palette, and Properties Window you can begin to design and create ServiceCenter forms.

Tools PaletteDrawing CanvasProperties Window

Figure 26-2. Tools Used to Create a ServiceCenter Form

The Forms Design Process 26-3

Page 502: Sct4 System Tailoring Vol.1

Preview of the Forms Design ProcessTo 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.

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.

Edit Area

26-4 System Tailoring, Vol. 1

Page 503: Sct4 System Tailoring Vol.1

The New Label caption is displayed on the Drawing Canvas and in the Properties Window. To modify your label’s 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.

The Forms Design Process 26-5

Page 504: Sct4 System Tailoring Vol.1

26-6 System Tailoring, Vol. 1

Page 505: Sct4 System Tailoring Vol.1

Chapter 27The 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

The Properties Window 27-1

Page 506: Sct4 System Tailoring Vol.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 System Tailoring, Vol. 1

Page 507: Sct4 System Tailoring Vol.1

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.

The Properties Window 27-3

Page 508: Sct4 System Tailoring Vol.1

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.

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

Caption Condition

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.

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

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

Height The Height property refers to the height of the object in

27-4 System Tailoring, Vol. 1

Page 509: Sct4 System Tailoring Vol.1

alignment grid units.

Width The Width property refers to the width of the object in alignment grid units.

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

Visible Condition

Can be used to establish a condition under which a field may or may not be visible.

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 You can select one of seven fonts available from the drop-down list. The default font is Helvetica.

ForeColor Text color. You can select one of 17 colors available from the drop-down list. The default color is Blue.

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

Bold Applies bold to the text.

Italic Applies italics to the text.

Justification Justifies the text to the Left, Right, or Center. Select from the drop-down list.

Opaque Enables the BackColor property.

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

OutputConv 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

The Properties Window 27-5

Page 510: Sct4 System Tailoring Vol.1

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 Only allows the user to view the field.

Password Makes the user’s password entry invisible on the screen.

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

Parse If Parse is set to Yes, the text entered in a field is parsed to

27-6 System Tailoring, Vol. 1

Page 511: Sct4 System Tailoring Vol.1

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.

The Properties Window 27-7

Page 512: Sct4 System Tailoring Vol.1

27-8 System Tailoring, Vol. 1

Page 513: Sct4 System Tailoring Vol.1

Chapter 28The 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.

Figure 28-1. The Tools Palette

Pointer Label Text Box

Button Bevel Frame

Multi- Line Text Box

Fill Box Picture

CheckBox

Radio Button

Combo Box

Marquee Sub-format Chart

Table Tab

OLE Container

Wrapping Label

The Tools Palette 28-1

Page 514: Sct4 System Tailoring Vol.1

PointerThe 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 System Tailoring, Vol. 1

Page 515: Sct4 System Tailoring Vol.1

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

Page 516: Sct4 System Tailoring Vol.1

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

Caption Enter the text for your label in this property.

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

Input No Input is required for a label, unless you are creating a QBE field (see More About Labels on page 28-7).

X Horizontal position based on the left edge of the component.

Y Vertical position based on the top edge of the component.

Height Height of the component in alignment grid units.

28-4 System Tailoring, Vol. 1

Page 517: Sct4 System Tailoring Vol.1

Width Width of the component in alignment grid units.

Visible If Visible is set to false, the component is hidden from view when the form is displayed.

Visible Condition 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 Determines the width and height of an object in relation to its parent window.

This property can have one of four values:

• None—the default. If the parent window is resized, the object will not resize with it.

• Horizontal—automatically adjusts the width of the object in proportion to the width of the parent window.

• Vertical—automatically adjusts the height of the object in proportion to the height of the parent window.

Both—automatically 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.

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.

Font Select a font for your label from the drop-down list.

Property Value

The Tools Palette 28-5

Page 518: Sct4 System Tailoring Vol.1

ForeColor Text color. Select from 17 available colors.

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.

BackColor Background color. The Opaque property must be set to Yes in order for the BackColor to have effect.

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

Bold When set to Yes, applies bold to your label.

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

Italic When set to Yes, applies italics to your label.

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

Justification You can justify your label to the Left, Right, or Center.

Opaque Enables the BackColor property.

FontIncrease Allows you to increase or decrease the standard font size.

Property Value

28-6 System Tailoring, Vol. 1

Page 519: Sct4 System Tailoring Vol.1

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.

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.

OutputConv This property does not apply to labels.

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

Property Value

The Tools Palette 28-7

Page 520: Sct4 System Tailoring Vol.1

Text BoxDescription: 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.

Caption This property does not apply to text boxes.

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

Input Enter the name of the appropriate database field or variable.

X Horizontal position based on the left edge of the component.

Y Vertical position based on the top edge of the component.

Height Height of the component in alignment grid units.

Width Width of the component in alignment grid units.

Visible If Visible is set to false, the component is hidden from view when the form is displayed.

Visible Condition 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 System Tailoring, Vol. 1

Page 521: Sct4 System Tailoring Vol.1

Elastic Determines the width and height of an object in relation to its parent window.

This property can have one of four values:

• None—the default. If the parent window is resized, the object will not resize with it.

• Horizontal—automatically adjusts the width of the object in proportion to the width of the parent window.

• Vertical—automatically adjusts the height of the object in proportion to the height of the parent window.

Both—automatically 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.

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.

TabStop You will almost always use the default of 0 for TabStop. See “Box Properties” on page 27-6 for more information on tabstops.

ReadOnly Prohibits the user from changing the contents of the field.

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.

Property Value

The Tools Palette 28-9

Page 522: Sct4 System Tailoring Vol.1

Password Makes the user’s password entry invisible on the screen.

MaxChars Specifies the number of characters the user can enter in the field. The default is 0 (unlimited).

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

CaseConversion Changes the case of text entered in the field.

Decimals Modifies numbers entered in the field to a number of decimal points you specify.

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

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.

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

Property Value

28-10 System Tailoring, Vol. 1

Page 523: Sct4 System Tailoring Vol.1

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

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.

Property Value

The Tools Palette 28-11

Page 524: Sct4 System Tailoring Vol.1

ButtonDescription: A Button activates a Control ID when clicked. You can use

text or graphics, or both, to customize buttons.

Examples:

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.

Caption If you want a caption on the button, enter it in this property.

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

Input Enter the name of the appropriate database field or variable.

X Horizontal position based on the left edge of the component.

Y Vertical position based on the top edge of the component

Height Height of the component in alignment grid units.

Width Width of the component in alignment grid units.

Visible If Visible is set to false, the component is hidden from view when the form is displayed.

28-12 System Tailoring, Vol. 1

Page 525: Sct4 System Tailoring Vol.1

Visible Condition 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 Determines the width and height of an object in relation to its parent window.

This property can have one of four values:

• None—the default. If the parent window is resized, the object will not resize with it.

• Horizontal—automatically adjusts the width of the object in proportion to the width of the parent window.

• Vertical—automatically adjusts the height of the object in proportion to the height of the parent window.

Both—automatically 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.

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.

TabStop You will almost always use the default of 0 for TabStop. See “Box Properties” on page 27-6 for more information on tabstops.

Property Value

The Tools Palette 28-13

Page 526: Sct4 System Tailoring Vol.1

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

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

Justification You can justify your label to the Left, Right, or Center.

Animated Enables the looping display of two or more images specified by the Bitmaps property.

Bitmaps The name(s) of one or more Microsoft Windows bit mapped image files (.BMP file format) to display on the button.

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

Property Value

28-14 System Tailoring, Vol. 1

Page 527: Sct4 System Tailoring Vol.1

Speed Integer. Delay in milliseconds between animation frames. Small values speed up animations. The Microsoft Windows minimum cycle time is 55.

BalloonHelp A popup help description that ServiceCenter displays while the cursor is over a button.

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.

Property Value

The Tools Palette 28-15

Page 528: Sct4 System Tailoring Vol.1

BevelDescription: A Bevel is a cosmetic rectangular border. Use bevels to make

your forms more attractive or easier to understand.

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.

Caption If you want a caption on the button, enter it in this property.

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

Input Enter the name of the appropriate database field or variable.

X Horizontal position based on the left edge of the component.

Y Vertical position based on the top edge of the component

28-16 System Tailoring, Vol. 1

Page 529: Sct4 System Tailoring Vol.1

Height Height of the component in alignment grid units.

Width Width of the component in alignment grid units.

Visible If Visible is set to false, the component is hidden from view when the form is displayed.

Elastic Determines the width and height of an object in relation to its parent window.

This property can have one of four values:

• None—the default. If the parent window is resized, the object will not resize with it.

• Horizontal—automatically adjusts the width of the object in proportion to the width of the parent window.

• Vertical—automatically adjusts the height of the object in proportion to the height of the parent window.

Both—automatically 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.

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.

Opaque Yes or No. Yes forms an opaque rectangle within the bevel boundaries—if 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.

Property Value

The Tools Palette 28-17

Page 530: Sct4 System Tailoring Vol.1

OuterBevelWidth Integer. Width of the outer bevel. Default is 2.

InnerBevelWidth Integer. Width of the inner bevel. Default is 2.

BackColor Background color. The Opaque property must be set to Yes in order for the BackColor to have effect.

Property Value

28-18 System Tailoring, Vol. 1

Page 531: Sct4 System Tailoring Vol.1

FrameDescription: A Frame is a rectangular border that is used to group

logically associated items.

Example:

This example shows a frame with the caption Coordinator. The frame has been added to group fields which give information about the coordinator.

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.

Caption If you want a caption on the button, enter it in this property.

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

Input Enter the name of the appropriate database field or variable.

X Horizontal position based on the left edge of the component.

Y Vertical position based on the top edge of the component

Height Height of the component in alignment grid units.

Width Width of the component in alignment grid units.

Visible If Visible is set to false, the component is hidden from view when the form is displayed.

The Tools Palette 28-19

Page 532: Sct4 System Tailoring Vol.1

Visible Condition 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 Determines the width and height of an object in relation to its parent window.

This property can have one of four values:

• None—the default. If the parent window is resized, the object will not resize with it.

• Horizontal—automatically adjusts the width of the object in proportion to the width of the parent window.

• Vertical—automatically adjusts the height of the object in proportion to the height of the parent window.

Both—automatically 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.

Font Select a font for the frame caption from the drop-down list.

ForeColor Text color. Choose one of 17 colors available from the drop-down list.

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

BackColor Background color. The Opaque property must be set to Yes in order for the BackColor to have effect.

Property Value

28-20 System Tailoring, Vol. 1

Page 533: Sct4 System Tailoring Vol.1

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

Bold When set to Yes, applies bold to your frame caption.

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

Italic When set to Yes, applies italics to your frame caption.

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

Justification You can justify your frame caption to the Left, Right, or Center.

Opaque Enables the BackColor property.

FontIncrease Allows you to increase or decrease the standard font size.

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.

Property Value

The Tools Palette 28-21

Page 534: Sct4 System Tailoring Vol.1

OutputConv This property does not apply to frames.

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

ShadowStyle Changes the appearance of the border. You can select Inset or Raised—two variations of a shaded border. The example shown on the previous page has a ShadowStyle of Inset.

Property Value

28-22 System Tailoring, Vol. 1

Page 535: Sct4 System Tailoring Vol.1

Multi-Line Text BoxDescription: 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:

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.

Caption If you want a caption on the button, enter it in this property.

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

Input Enter the name of the appropriate database field or variable.

X Horizontal position based on the left edge of the component.

Y Vertical position based on the top edge of the component

Height Height of the component in alignment grid units.

Width Width of the component in alignment grid units.

This is a multi-line text box. The user can input several lines of data.

The Tools Palette 28-23

Page 536: Sct4 System Tailoring Vol.1

Visible If Visible is set to false, the component is hidden from view when the form is displayed.

Visible Condition 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 Determines the width and height of an object in relation to its parent window.

This property can have one of four values:

• None—the default. If the parent window is resized, the object will not resize with it.

• Horizontal—automatically adjusts the width of the object in proportion to the width of the parent window.

• Vertical—automatically adjusts the height of the object in proportion to the height of the parent window.

Both—automatically 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.

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.

TabStop You will almost always use the default of 0 for TabStop. See “Box Properties” on page 27-6 for more information on tabstops.

Property Value

28-24 System Tailoring, Vol. 1

Page 537: Sct4 System Tailoring Vol.1

ReadOnly Prohibits the user from changing the contents of the field.

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.

Password This property does not apply to multi-line text boxes.

MaxChars This property does not apply to multi-line text boxes.

MaxCharsBeep This property does not apply to multi-line text boxes.

CaseConversion Changes the case of text entered in the field.

Decimals This property does not apply to multi-line text boxes.

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

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.

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

Property Value

The Tools Palette 28-25

Page 538: Sct4 System Tailoring Vol.1

Fill BoxDescription: 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 user’s current screen.

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.

Caption If you want a caption on the button, enter it in this property.

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

Input Enter the name of the appropriate database field or variable.

X Horizontal position based on the left edge of the component.

Y Vertical position based on the top edge of the component

Height Height of the component in alignment grid units.

Width Width of the component in alignment grid units.

Visible If Visible is set to false, the component is hidden from view when the form is displayed.

28-26 System Tailoring, Vol. 1

Page 539: Sct4 System Tailoring Vol.1

Visible Condition 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 Determines the width and height of an object in relation to its parent window.

This property can have one of four values:

• None—the default. If the parent window is resized, the object will not resize with it.

• Horizontal—automatically adjusts the width of the object in proportion to the width of the parent window.

• Vertical—automatically adjusts the height of the object in proportion to the height of the parent window.

Both—automatically 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.

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.

TabStop You will almost always use the default of 0 for TabStop. See “Box Properties” on page 27-6 for more information on tabstops.

ReadOnly Prohibits the user from changing the contents of the field.

Property Value

The Tools Palette 28-27

Page 540: Sct4 System Tailoring Vol.1

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.

Password This property does not apply to fill boxes.

MaxChars Specifies the number of characters the user can enter in the field. The default is 0 (unlimited).

MaxCharsBeep If set to Yes, the system notifies the user (by sounding a beep) that the maximum number of characters has been reached.

CaseConversion Changes the case of text entered in the field.

Decimals Modifies numbers entered in the field to a number of decimal points you specify.

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

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.

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

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

Property Value

28-28 System Tailoring, Vol. 1

Page 541: Sct4 System Tailoring Vol.1

ButtonBitmap Select one of 16 possible button and color combinations:

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

Property Value

The Tools Palette 28-29

Page 542: Sct4 System Tailoring Vol.1

PictureDescription: A Picture displays a cosmetic image from a Microsoft

Windows BMP file

.

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.

Caption If you want a caption on the button, enter it in this property.

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

Input Enter the name of the appropriate database field or variable.

X Horizontal position based on the left edge of the component.

Y Vertical position based on the top edge of the component

Height Height of the component in alignment grid units.

Width Width of the component in alignment grid units.

28-30 System Tailoring, Vol. 1

Page 543: Sct4 System Tailoring Vol.1

Visible If Visible is set to false, the component is hidden from view when the form is displayed.

Visible Condition 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 Determines the width and height of an object in relation to its parent window.

This property can have one of four values:

• None—the default. If the parent window is resized, the object will not resize with it.

• Horizontal—automatically adjusts the width of the object in proportion to the width of the parent window.

• Vertical—automatically adjusts the height of the object in proportion to the height of the parent window.

Both—automatically 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.

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.

Property Value

The Tools Palette 28-31

Page 544: Sct4 System Tailoring Vol.1

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

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

Frame Yes or No. Yes displays a beveled frame around the image.

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

ReadOnly Prohibits the user from changing the contents of the field.

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.

Property Value

28-32 System Tailoring, Vol. 1

Page 545: Sct4 System Tailoring Vol.1

Check BoxDescription: 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 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.

Caption If you want a caption on the button, enter it in this property.

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

Input Enter the name of the appropriate database field or variable.

X Horizontal position based on the left edge of the component.

Y Vertical position based on the top edge of the component

Height Height of the component in alignment grid units.

Width Width of the component in alignment grid units.

Visible If Visible is set to false, the component is hidden from view when the form is displayed.

The Tools Palette 28-33

Page 546: Sct4 System Tailoring Vol.1

Visible Condition 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 Determines the width and height of an object in relation to its parent window.

This property can have one of four values:

• None—the default. If the parent window is resized, the object will not resize with it.

• Horizontal—automatically adjusts the width of the object in proportion to the width of the parent window.

• Vertical—automatically adjusts the height of the object in proportion to the height of the parent window.

Both—automatically 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.

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.

TabStop You will almost always use the default of 0 for TabStop. See “Box Properties” on page 27-6 for more information on tabstops.

ReadOnly Prohibits the user from changing the contents of the field.

Property Value

28-34 System Tailoring, Vol. 1

Page 547: Sct4 System Tailoring Vol.1

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.

TextLocation Left or Right. Specifies the position of the caption with respect to the check box.

State Integer. Reserved for future use.

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

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

Property Value

The Tools Palette 28-35

Page 548: Sct4 System Tailoring Vol.1

ForeColor Text color. Choose one of 17 colors available from the drop-down list.

Data Changed Event

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.

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

Property Value

28-36 System Tailoring, Vol. 1

Page 549: Sct4 System Tailoring Vol.1

Radio ButtonDescription: 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

Page 550: Sct4 System Tailoring Vol.1

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.

Caption If you want a caption on the button, enter it in this property.

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

Input Enter the name of the appropriate database field or variable.

X Horizontal position based on the left edge of the component.

Y Vertical position based on the top edge of the component

Height Height of the component in alignment grid units.

Width Width of the component in alignment grid units.

Visible If Visible is set to false, the component is hidden from view when the form is displayed.

Visible Condition 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-38 System Tailoring, Vol. 1

Page 551: Sct4 System Tailoring Vol.1

Elastic Determines the width and height of an object in relation to its parent window.

This property can have one of four values:

• None—the default. If the parent window is resized, the object will not resize with it.

• Horizontal—automatically adjusts the width of the object in proportion to the width of the parent window.

• Vertical—automatically adjusts the height of the object in proportion to the height of the parent window.

Both—automatically 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.

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.

TabStop You will almost always use the default of 0 for TabStop. See “Box Properties” on page 27-6 for more information on tabstops.

ReadOnly Prohibits the user from changing the contents of the field.

Property Value

The Tools Palette 28-39

Page 552: Sct4 System Tailoring Vol.1

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.

TextLocation Left or Right. Specifies the position of the caption with respect to the Radio Button.

State Integer. Reserved for future use.

Value Value to assign to the field or variable specified in the Input property when this Radio Button is selected.

ForeColor Text color. Choose one of 17 colors available from the drop-down list.

Data Changed Event

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.

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

Property Value

28-40 System Tailoring, Vol. 1

Page 553: Sct4 System Tailoring Vol.1

Combo BoxDescription: 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 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 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.

Caption If you want a caption on the button, enter it in this property.

Caption Condition 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 combo box as displayed in Forms

Designer

the combo box as seen by the

user

The Tools Palette 28-41

Page 554: Sct4 System Tailoring Vol.1

Input Enter the name of the appropriate database field or variable.

X Horizontal position based on the left edge of the component.

Y Vertical position based on the top edge of the component

Height Height of the component in alignment grid units.

Width Width of the component in alignment grid units.

Visible If Visible is set to false, the component is hidden from view when the form is displayed.

Visible Condition 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 Determines the width and height of an object in relation to its parent window.

This property can have one of four values:

• None—the default. If the parent window is resized, the object will not resize with it.

• Horizontal—automatically adjusts the width of the object in proportion to the width of the parent window.

• Vertical—automatically adjusts the height of the object in proportion to the height of the parent window.

Both—automatically 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.

Property Value

28-42 System Tailoring, Vol. 1

Page 555: Sct4 System Tailoring Vol.1

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.

TabStop You will almost always use the default of 0 for TabStop. See “Box Properties” on page 27-6 for more information on tabstops.

ReadOnly Prohibits the user from changing the contents of the field.

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.

Caption If you want a caption on the button, enter it in this property.

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

Input Enter the name of the appropriate database field or variable.

Password This property does not apply to combo boxes.

MaxChars Specifies the number of characters the user can enter in the field. The default is 0 (unlimited).

MaxCharsBeep If set to Yes, notifies the user (by sounding a beep) that the maximum number of characters has been reached.

CaseConversion Changes the case of text entered in the field.

Decimals Modifies numbers entered in the field to a number of decimal points you specify.

Property Value

The Tools Palette 28-43

Page 556: Sct4 System Tailoring Vol.1

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

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.

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

Property Value

28-44 System Tailoring, Vol. 1

Page 557: Sct4 System Tailoring Vol.1

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

• number

• character

• date/time

• logical

The DisplayList for this drop-down list is a semicolon- delimited 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 drop-down 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.

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

Property Value

The Tools Palette 28-45

Page 558: Sct4 System Tailoring Vol.1

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.

BoxLines Integer. Window size of the drop-down list.

SelectOnly Yes or No.

Yes requires the user to select from the combo box drop-down 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 drop-down 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.

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

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.

Property Value

28-46 System Tailoring, Vol. 1

Page 559: Sct4 System Tailoring Vol.1

MarqueeDescription: A Marquee is an attention-getting text message that scrolls

continuously across the screen from right to left.

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.

Caption If you want a caption on the button, enter it in this property.

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

Input Enter the name of the appropriate database field or variable.

X Horizontal position based on the left edge of the component.

Y Vertical position based on the top edge of the component

Height Height of the component in alignment grid units.

Width Width of the component in alignment grid units.

Visible If Visible is set to false, the component is hidden from view when the form is displayed.

The Tools Palette 28-47

Page 560: Sct4 System Tailoring Vol.1

Visible Condition 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 Determines the width and height of an object in relation to its parent window.

This property can have one of four values:

• None—the default. If the parent window is resized, the object will not resize with it.

• Horizontal—automatically adjusts the width of the object in proportion to the width of the parent window.

• Vertical—automatically adjusts the height of the object in proportion to the height of the parent window.

Both—automatically 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.

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.

ForeColor Text color. One of 17 colors available from the drop-down list.

BackColor Background color. The Background color for a marquee is Black.

Property Value

28-48 System Tailoring, Vol. 1

Page 561: Sct4 System Tailoring Vol.1

FontIncrease Allows you to increase or decrease the standard font size.

Font Select a font for your marquee caption from the drop-down list.

Bold Applies bold to your marquee caption.

Italic Applies italics to your marquee caption.

Property Value

The Tools Palette 28-49

Page 562: Sct4 System Tailoring Vol.1

SubformatDescription: A Subformat is a grouping of information (structure) that is

imported into a larger form. Subformats generally contain information that is used in multiple forms—a 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 subformats—one 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 System Tailoring, Vol. 1

Page 563: Sct4 System Tailoring Vol.1

Example #2:

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 important—a 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.

cc.contact.vj

Subformats

cc.device.vj

The Tools Palette 28-51

Page 564: Sct4 System Tailoring Vol.1

Property Values

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.

Caption If you want a caption on the button, enter it in this property.

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

Input Enter the name of the appropriate database field or variable.

X Horizontal position based on the left edge of the component.

Y Vertical position based on the top edge of the component

Height Height of the component in alignment grid units.

Width Width of the component in alignment grid units.

Visible If Visible is set to false, the component is hidden from view when the form is displayed.

Visible Condition 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-52 System Tailoring, Vol. 1

Page 565: Sct4 System Tailoring Vol.1

Elastic Determines the width and height of an object in relation to its parent window.

This property can have one of four values:

• None—the default. If the parent window is resized, the object will not resize with it.

• Horizontal—automatically adjusts the width of the object in proportion to the width of the parent window.

• Vertical—automatically adjusts the height of the object in proportion to the height of the parent window.

Both—automatically 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.

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.

Property Values

The Tools Palette 28-53

Page 566: Sct4 System Tailoring Vol.1

Format Format used to display the structure.

VirtualJoin 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 User’s Guide.

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

Property Values

28-54 System Tailoring, Vol. 1

Page 567: Sct4 System Tailoring Vol.1

ChartDescription: A Chart displays the contents of a numeric array as a two-

dimensional, color-coded bar chart with (optional) definable buttons.

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.

Caption If you want a caption on the button, enter it in this property.

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

Input Enter the name of the appropriate database field or variable.

X Horizontal position based on the left edge of the component.

Y Vertical position based on the top edge of the component

Height Height of the component in alignment grid units.

The Tools Palette 28-55

Page 568: Sct4 System Tailoring Vol.1

Width Width of the component in alignment grid units.

Visible If Visible is set to false, the component is hidden from view when the form is displayed.

Visible Condition 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 Determines the width and height of an object in relation to its parent window.

This property can have one of four values:

• None—the default. If the parent window is resized, the object will not resize with it.

• Horizontal—automatically adjusts the width of the object in proportion to the width of the parent window.

• Vertical—automatically adjusts the height of the object in proportion to the height of the parent window.

Both—automatically 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.

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.

BarWidth Integer. Width of bars in alignment grid units.

Property Value

28-56 System Tailoring, Vol. 1

Page 569: Sct4 System Tailoring Vol.1

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

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

ButtonBase Yes or No. Yes enables a row of buttons across the base of the chart, one button per column.

BaseButtonID 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 left-most 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

ColorScale Specifies a list of semicolon delimited numeric values that determine the color of a column.

ColorPercent Yes or No. Yes indicates that ColorScale as a list of percentages from 1 to 100.

ForeColor Text color. Select from seventeen colors available from the drop-down list.

BalloonHelp A one-line help description that ServiceCenter displays while the user’s cursor is over the button.

Property Value

The Tools Palette 28-57

Page 570: Sct4 System Tailoring Vol.1

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 colors—to 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 value—to 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 use 1st ColorList (Green)30 < column value <= 45 use 2nd ColorList (Yellow)column value > 45 use 3rd ColorList (Red)

• Color based on relative column value—to 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 System Tailoring, Vol. 1

Page 571: Sct4 System Tailoring Vol.1

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

Caption If you want a caption on the button, enter it in this property.

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

Input Enter the name of the appropriate database field or variable.

The Tools Palette 28-59

Page 572: Sct4 System Tailoring Vol.1

X Horizontal position based on the left edge of the component.

Y Vertical position based on the top edge of the component

Height Height of the component in alignment grid units.

Width Width of the component in alignment grid units.

Visible If Visible is set to false, the component is hidden from view when the form is displayed.

Visible Condition 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 Determines the width and height of an object in relation to its parent window.

This property can have one of four values:

• None—the default. If the parent window is resized, the object will not resize with it.

• Horizontal—automatically adjusts the width of the object in proportion to the width of the parent window.

• Vertical—automatically adjusts the height of the object in proportion to the height of the parent window.

Both—automatically 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.

Property Value

28-60 System Tailoring, Vol. 1

Page 573: Sct4 System Tailoring Vol.1

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.

TabStop You will almost always use the default of 0 for TabStop. See “Box Properties” on page 27-6 for more information on tabstops.

Columns List of columns in the table.

ColumnHeadings If Yes, headings are displayed above the columns.

MultipleSelections If Yes, the user can highlight several rows.

ReadOnly If Yes, the cells in the table cannot be edited.

AllowRowDelete If Yes, the user can delete rows by pressing the Delete key. If Yes/Prompted, the user is first prompted before deletion is done.

BackColor The color of the table background.

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

ForeColor Color used for the table contents (text).

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

SelectedBackColor Background color of a selected row.

SelectedForeColor Foreground color of selected text.

HeadingBackColor Background color of the top row used to display column headings.

SeparatorColor Color used to draw the column and row separators.

Property Value

The Tools Palette 28-61

Page 574: Sct4 System Tailoring Vol.1

Column Properties (editable by clicking on the column heading after you have created it):

InvertReadOnlyColors

If Yes, the table is drawn in inverted colors (background and separator colors are swapped, normally resulting in a grayed-out table).

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

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

DoubleClick ButtonID

The ID generated when a selected row is double clicked. See the definition for the DoubleClick ButtonID property in the Column Properties definitions.

Refresh Rate Specify the refresh rate (how often the client queries the server for an update) for the table, in seconds.

Font Select a font for your table from the drop-down list.

FontIncrease Allows you to increase or decrease the standard font size.

Bold When set to Yes, applies bold to the default font.

Italic When set to Yes, applies italics to the default font.

Property Value

28-62 System Tailoring, Vol. 1

Page 575: Sct4 System Tailoring Vol.1

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.

Caption Enter the text for your table heading in this property.

Input Enter the array variable used as Input for the column.

X Horizontal position based on the component’s left edge.

Y Vertical position based on the component’s top edge.

Height Height of the component in alignment grid units.

Width Width of the component in alignment grid units.

Visible If Visible is set to false, the component is hidden from view when the form is displayed.

Visible Condition 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 Determines the width and height of an object in relation to its parent window.

This property can have one of four values:

• None—the default. If the parent window is resized, the object will not resize with it.

• Horizontal—automatically adjusts the width of the object in proportion to the width of the parent window.

• Vertical—automatically adjusts the height of the object in proportion to the height of the parent window.

• Both—automatically adjusts both the width and the height in proportion to the parent window.

The Tools Palette 28-63

Page 576: Sct4 System Tailoring Vol.1

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.

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.

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

Column Width% Size of the column as a percentage of the table’s visible width.

Sizeable If Yes, the user can resize the column using the mouse.

Clickable Title If Yes, the column’s heading acts as a clickable button.

ButtonID The ID generated when a clickable title button is pressed. Behaves just like other components with a ButtonID property.

ShowTitle If Yes, the heading for the column is visible.

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

Property Value

28-64 System Tailoring, Vol. 1

Page 577: Sct4 System Tailoring Vol.1

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.

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

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

ReadOnly If Yes, cells in the column cannot be edited.

MaxChars Specifies the number of characters the user can enter in the field. The default is 0 (unlimited).

MaxCharsBeep If set to Yes, the system notifies the user (by sounding a beep) that the maximum number of characters has been reached.

CaseConversion Changes the case of text entered in the column cells.

Decimals Modifies numbers entered in the column cells to a number of decimal points you specify.

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

Justification Allows you to align column contents to the Left, Center, or Right.

Property Value

The Tools Palette 28-65

Page 578: Sct4 System Tailoring Vol.1

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 System Tailoring, Vol. 1

Page 579: Sct4 System Tailoring Vol.1

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

Caption Enter the text for your tab heading in this property.

Input Enter the array variable used as Input for the column.

X Horizontal position based on the component’s left edge.

Y Vertical position based on the component’s top edge.

The Tools Palette 28-67

Page 580: Sct4 System Tailoring Vol.1

Height Height of the component in alignment grid units.

Width Width of the component in alignment grid units.

Visible If Visible is set to false, the component is hidden from view when the form is displayed.

Visible Condition 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 Determines the width and height of an object in relation to its parent window.

This property can have one of four values:

• None—the default. If the parent window is resized, the object will not resize with it.

• Horizontal—automatically adjusts the width of the object in proportion to the width of the parent window.

• Vertical—automatically adjusts the height of the object in proportion to the height of the parent window.

• Both—automatically 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.

Property Value

28-68 System Tailoring, Vol. 1

Page 581: Sct4 System Tailoring Vol.1

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.

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.

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

Pages A semicolon-delimited list of the tab headings.

Property Value

The Tools Palette 28-69

Page 582: Sct4 System Tailoring Vol.1

Wrapping LabelDescription: 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.

Caption Enter the text for your wrapping label in this property.

Input Enter the array variable used as Input for the column.

X Horizontal position based on the component’s left edge.

Y Vertical position based on the component’s top edge.

Height Height of the component in alignment grid units.

Width Width of the component in alignment grid units.

Visible If Visible is set to false, the component is hidden from view when the form is displayed.

28-70 System Tailoring, Vol. 1

Page 583: Sct4 System Tailoring Vol.1

Visible Condition 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 Determines the width and height of an object in relation to its parent window.

This property can have one of four values:

• None—the default. If the parent window is resized, the object will not resize with it.

• Horizontal—automatically adjusts the width of the object in proportion to the width of the parent window.

• Vertical—automatically adjusts the height of the object in proportion to the height of the parent window.

• Both—automatically 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.

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.

Font Select a font for your label from the drop-down list.

ForeColor Text color. Select from 17 available colors.

Property Value

The Tools Palette 28-71

Page 584: Sct4 System Tailoring Vol.1

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.

BackColor Background color. The Opaque property must be set to Yes in order for the BackColor to have effect.

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

Bold When set to Yes, applies bold to your label.

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

Italic When set to Yes, applies italics to your label.

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

Opaque Enables the BackColor property.

FontIncrease Allows you to increase or decrease the standard font size.

Property Value

28-72 System Tailoring, Vol. 1

Page 585: Sct4 System Tailoring Vol.1

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.

OutputConv This property does not apply to labels.

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

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.

Property Value

The Tools Palette 28-73

Page 586: Sct4 System Tailoring Vol.1

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 System Tailoring, Vol. 1

Page 587: Sct4 System Tailoring Vol.1

OLE ContainerDescription: The OLE Container tool allows the user to attach a non-

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

Caption Enter the text for your Ole tab in this field.

Caption Condition 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

Page 588: Sct4 System Tailoring Vol.1

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

X Horizontal position based on the left edge of the component.

Y Vertical position based on the top edge of the component.

Height Height of the component in alignment grid units.

Width Width of the component in alignment grid units.

Visible If Visible is set to false, the component is hidden from view when the form is displayed.

Visible Condition 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 Determines the width and height of an object in relation to its parent window. his property can have one of four values:

• None—the default. If the parent window is resized, the object will not resize with it.

• Horizontal—automatically adjusts the width of the object in proportion to the width of the parent window.

• Vertical—automatically adjusts the height of the object in proportion to the height of the parent window.

Both—automatically adjusts both the width and the height in proportion to the parent window.

Property Value

28-76 System Tailoring, Vol. 1

Page 589: Sct4 System Tailoring Vol.1

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.

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.

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

ReadOnly Disables editing capabilities, providing only viewing access.

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.

MaxAttachSize A straight number field that sets the absolute size of an attachment for the form being modified.

MaxAttachSize Condition

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

Property Value

The Tools Palette 28-77

Page 590: Sct4 System Tailoring Vol.1

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 System Tailoring, Vol. 1

Page 591: Sct4 System Tailoring Vol.1

Chapter 29The 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 single-record 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

Page 592: Sct4 System Tailoring Vol.1

Accessing the Form WizardTo 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 System Tailoring, Vol. 1

Page 593: Sct4 System Tailoring Vol.1

The fd.wizard.show.g form is displayed (figure 29-1).

Figure 29-1. Fd.wizard.show.g Form

The Form Wizard 29-3

Page 594: Sct4 System Tailoring Vol.1

Creating a Form Using the Form WizardThe 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.

2. Change the true statement to false if you do not want a particular field included on the completed form.

Figure 29-2. Fd.wizard.show.g Form

29-4 System Tailoring, Vol. 1

Page 595: Sct4 System Tailoring Vol.1

3. Click Proceed. The form is displayed in Forms Designer.

4. Click OK to view the completed form.

5. Click OK again to save the form.

Figure 29-3. New Form

The Form Wizard 29-5

Page 596: Sct4 System Tailoring Vol.1

29-6 System Tailoring, Vol. 1

Page 597: Sct4 System Tailoring Vol.1

Chapter 30Tutorial: 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

Page 598: Sct4 System Tailoring Vol.1

The Practice FormFigure 30-1 shows the practice form department as it will appear when completed. Refer to this illustration as your guide while creating the 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.

Figure 30-1. The Completed Practice Form

30-2 System Tailoring, Vol. 1

Page 599: Sct4 System Tailoring Vol.1

Creating the FormThe 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 Value

X 49

Y 5

Height 4

Width 46

Bitmap sc

AutoResize no

Frame no

2. Add a Label.

Property Value

Caption Department Information

X 45

Y 10

Height 3

Width 62

Bold Yes

Justification Center

FontIncrease 8

Tutorial: Creating a New Form 30-3

Page 600: Sct4 System Tailoring Vol.1

3. Add a Bevel (around the Picture and Label).

Property Value

X 11

Y 3

Height 12

Width 117

4. Add a Label.

Property Value

Caption Dept Code

X 15

Y 18

Height 2

Width 19

Justification Left

5. Add a Text Box (next to Dept Code).

Property Value

Input dept.code

X 30

Y 18

Height 2

Width 27

30-4 System Tailoring, Vol. 1

Page 601: Sct4 System Tailoring Vol.1

6. Add a Label.

Property Value

Caption Manager

X 15

Y 22

Height 2

Width 12

Justification Left

7. Add a Fill Box (next to Manager)

Property Value

Input manager

X 30

Y 22

Height 2

Width 27

ButtonID 9

ButtonBitmap 1

8. Add a Label.

Property Value

Caption Office Hours

X 94

Y 17

Height 2

Width 25

Justification Center

Tutorial: Creating a New Form 30-5

Page 602: Sct4 System Tailoring Vol.1

9. Add a Text Box (under Office Hours).

Property Value

Input start.time

X 94

Y 19

Height 2

Width 12

10. Add a Text Box (under Office Hours).

Property Value

Input end.time

X 108

Y 19

Height 2

Width 12

11. Add a Radio Button.

Property Value

Caption Main Office

Input office

X 18

Y 27

Height 2

Width 25

TextLocation Right

Value main

30-6 System Tailoring, Vol. 1

Page 603: Sct4 System Tailoring Vol.1

12. Add a Radio Button.

Property Value

Caption Annex A

Input office

X 18

Y 30

Height 2

Width 22

TextLocation Right

Value annexa

13. Add a Frame (around the two Radio Buttons).

Property Value

Caption Location

X 15

Y 25

Height 8

Width 29

Bold Yes

Justification Left

14. Add a Check Box.

Tutorial: Creating a New Form 30-7

Page 604: Sct4 System Tailoring Vol.1

Property Value

Caption Special

Input special

X 18

Y 34

Height 2

Width 21

TextLocation Right

15. Add a Button.

Property Value

Caption List

X 70

Y 18

Height 2

Width 14

ButtonID 0

Justification Center

16. Add a Label.

Property Value

Caption Description

X 83

Y 23

Height 2

Width 30

Justification Center

30-8 System Tailoring, Vol. 1

Page 605: Sct4 System Tailoring Vol.1

17. Add a Multi Line Text Box.

Property Value

Input description

X 70

Y 26

Height 10

Width 42

ReadOnly No

18. Add a Frame (around all the objects from steps 4 - 17).

Property Value

Caption (leave blank)

X 11

Y 16

Height 22

Width 117

Tutorial: Creating a New Form 30-9

Page 606: Sct4 System Tailoring Vol.1

Saving the Form and Creating a FileOnce 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 System Tailoring, Vol. 1

Page 607: Sct4 System Tailoring Vol.1

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.

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 form’s name (department).

3. Click OK to use the default filename of department.

Figure 30-2. Initial Forms Designer Screen

Tutorial: Creating a New Form 30-11

Page 608: Sct4 System Tailoring Vol.1

The system advances you to the file that has been created for department (figure 30-3).

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.

Figure 30-3. The File for the Department Form

30-12 System Tailoring, Vol. 1

Page 609: Sct4 System Tailoring Vol.1

Modifying an Existing FormTo 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.

Figure 30-4. Initial Forms Designer Screen

Search

Tutorial: Creating a New Form 30-13

Page 610: Sct4 System Tailoring Vol.1

The department form (figure 30-5) is displayed.

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.

Figure 30-5. The Department Form

30-14 System Tailoring, Vol. 1

Page 611: Sct4 System Tailoring Vol.1

Using the Options menu

The Options menu (figure 30-6) allows you to perform several functions with your form.

Below is a description of each item in the Options menu:

Option Description_____________________________________________________________

Copy/Rename Copy or rename the form and (optionally) its associated link record or format control record.

Help Topic Reserved for future use.

Filename Set or change the file name associated with the form.

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

Figure 30-6. The Options Menu

Tutorial: Creating a New Form 30-15

Page 612: Sct4 System Tailoring Vol.1

(Options Menu Continued)

Option Description_____________________________________________________________

dbdict Runs the Database Dictionary Maintenance utility for the file name associated with the form.

Database Manager

Runs the Database Manager using the form and its associated database dictionary.

Format Control Runs the Format Control Maintenance utility.

Link Runs the Link Maintenance utility.

Format Detail Displays text-based format detail information.

Format Control Wizard

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.

30-16 System Tailoring, Vol. 1

Page 613: Sct4 System Tailoring Vol.1

Chapter 31Designer 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

Page 614: Sct4 System Tailoring Vol.1

Form Style GuidelinesThis 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 system’s 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 screen’s 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 non-deterministic. 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 System Tailoring, Vol. 1

Page 615: Sct4 System Tailoring Vol.1

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 label’s 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

Page 616: Sct4 System Tailoring Vol.1

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

31-4 System Tailoring, Vol. 1

Page 617: Sct4 System Tailoring Vol.1

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

Page 618: Sct4 System Tailoring Vol.1

ServiceCenter and BitmapsServiceCenter 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 Description.

Application The table with which this bitmap is associated.

Topic The key value from the table with which this bitmap is associated.

Type The type of data stored here. Bitmaps are type 3.

Segment The segment counter for this section of the bitmap.

Data 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 System Tailoring, Vol. 1

Page 619: Sct4 System Tailoring Vol.1

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

Page 620: Sct4 System Tailoring Vol.1

Graphics and AnimationYou 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 higher-color 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 System Tailoring, Vol. 1

Page 621: Sct4 System Tailoring Vol.1

Index

Aaccessing Forms Designer, 26-1Accessing the Document Engine, 1-2adding

records, 5-2, 15-3mass adding using literal value, 5-2

single record, 4-1structures to the Database Dictionary, 10-9

additional file queries process (Format Control), 14-3, 16-33

examples, 16-32fields, 16-29

additional options, 14-4, 16-53, 17-1, 17-4, 17-12, 17-19

example, 16-58fields, 16-55

Administration Mode, 2-2animation, 31-8applications

called from Format Controlaxces.fax, 22-10axces.page, 22-8axces.write, 22-9database, 22-7determining parameters, 22-13fill.fc, 22-2fingerprint, 22-11getnumb.fc, 22-3message.fc, 22-4post.fc, 22-2query.stored, 22-7sort.array, 22-11validate.fields, 22-6

arrayed structures, 16-24as.copy, 17-8

parameters, 17-8as.delete, 17-9

parameters, 17-9as.get.name, 17-15as.insert, 17-10

parameters, 17-10as.move, 17-11

example, 17-12

parameters, 17-11as.options, 17-2, 17-3

example, 17-4parameters, 17-3

as.sort, 17-15parameters, 17-16

subformats, 17-2, 17-9user options

copy, 17-7, 17-14delete, 17-7, 17-14insert, 17-7, 17-14move, 17-7, 17-15replace, 17-8, 17-15

arrays, 10-5arrayed structure maintenance utility, 10-20arrayed structures, 10-14denulling, 16-26editing, 16-1, 19-6editor, 17-1expanding, 4-7fields, 9-2sorting, 17-23 to 17-28

auditingaudit log, 6-21

accessing, 6-6audit.g, 6-23fields, 6-8

audit specifications entry, 6-9audit specifications file, 6-3audit.compare, 6-17audit.compare application, 6-17auditspecs, 6-5error correction, 6-9triggers

example.audit.trigger.update, 6-17

Bbackups, 11-2basic.employee.info structure, 10-13Bevel tool, 28-16boolean fields, 14-7, 16-31, 16-35box properties, 27-6Button tool, 28-12

Index I-1

Page 622: Sct4 System Tailoring Vol.1

Ccalculations process (Format Control), 14-3, 16-11,

16-21, 16-22, 16-23, 16-33canvas invisible grid, 25-3capability words

logical operators, 3-4Change Management

approvalsFormat Control record, 21-3

changesopening, 19-19, 19-30

detail record, 21-3master record, 21-2processing considerations, 21-2

character fields, 9-5, 10-4character strings

identifying, 3-29 to 3-30specifying length, 3-30

Chart tool, 28-55chart tool

ColorList, 28-58ColorScale, 28-58

Check Box tool, 28-33Clear option, 3-17colors on charts, 28-58Combo Box tool, 28-41command line, 9-5common properties, 27-4conditional statements

dynamic functions, 24-4field comparisons, 24-3field value matching, 24-4

Courier font, 31-3creating

new forms, 26-2creating a file, 30-11creating a new form, 26-2, 30-1Creating an oncall schedule, 12-14Creating Objects, 1-2Creating Processes, 1-11Creating States, 1-9customer support, Preface-2

Ddata

creating fields, 28-7data fields

creating, 28-7, 28-74data fields, creating, 28-74data map, 5-27

unload script utility, 8-4, 8-5, 8-7, 8-8data pools, 11-11

data types, 9-5array, 9-5character, 9-5

changing to number, 10-39date/time, 9-5expression, 9-5logical, 9-5number, 9-5record, 9-5structure, 9-5

databaseloading, 5-58 to 5-64

background, 5-62 to 5-64foreground, 5-58 to 5-62messages, 5-60 to 5-62

regenerating keys, 7-5 to 7-7retrieving records

all, 3-12using array fields, 3-15 to 3-16using multiple fields, 3-13 to 3-14

scheduling regeneration, 7-6 to 7-7unloading records, 5-22

Database Dictionary only, 5-45from multiple databases, 5-38messages, 5-25 to 5-27multiple records from one database

QBE method, 5-29value list method, 5-33

single records, 5-22unloading reports, 5-48

Database Dictionary, 5-45accessing, 9-3

from Forms Designer, 9-3 to 9-5backing up a file, 11-2copying, 11-1data pools, 11-11deleting, 11-7field names

graph.of.unavailibility-array, 10-16index pools, 11-11level, 9-5pools, 11-11 to 11-12record description, 9-2renaming, 11-5resetting records, 11-8

Database Manageraccessing, 2-2administration mode, 2-2character strings

identifying, 3-29 to 3-30specifying length, 3-30

queriesusing functions, 3-27 to 3-31

query expressions, 3-25 to 3-27Database manager

I-2 System Tailoring, Vol. 1

Page 623: Sct4 System Tailoring Vol.1

standard mode, 2-2date/time fields, 9-5, 10-4default fonts in ServiceCenter, 31-2deleting

objects, 28-3deleting an object, 28-3descriptor, 10-3

field, 10-1deselecting objects, 28-2design

guidelines, 31-4process, 26-4tips, 31-1

Document EngineStandard Variables, 1-14

drawing canvasintroduction to, 25-2

dynamic functions, 24-4dynamic view dependencies, 24-1

EEdit Area list, 27-3enduser file

fields, 6-6equal to, 3-3errors

messages, 20-1record/key conflicts, 4-6

example.audit.trigger.update, 6-17expressions

boolean fields, 14-7definitions

primary file, 14-6semicolon, 14-6statements, 14-6variable, 14-6

error messages, 20-1

Ffield comparisons, 24-3field value matching, 24-4fields

adding, 10-1arrays, 9-2, 10-5changing data types, 10-39comparisons, 24-3data types, 10-4

array, 9-5arrays, 10-5character, 9-5, 10-4date/time, 9-5, 10-4expression, 9-5, 10-5

label, 10-5logical, 9-5, 10-5number, 9-5, 10-4record, 9-5, 10-5structure, 9-5, 10-5

Database Dictionarydata types, 9-5descriptor field, 10-1field name, 9-4index, 9-5keys, 9-5

deleting, 10-47modifying, 10-36 to 10-41scalar, 10-2searching for, 11-13unload script utility, 8-3 to 8-4value matching, 24-4

filesarrayed structure maintenance utility, 10-20commonly used in unload script utility, 8-6 to 8-

7creating from Forms Designer, 30-11maintenance

regenerating keys, 7-5 to 7-7reset a database, 7-1

problem, 10-19probsummary, 10-19

Fill Box tool, 28-26font properties, 27-5fonts, 31-2

default in ServiceCenter, 31-2properties in Forms Designer, 27-5

form style guidelines, 31-2Form Wizard, 25-7

accessing, 29-2creating a form, 29-4introduction, 29-1

Format Controlaccessing

from a menu, 15-2from Forms Designer, 15-1

creating records, 17-24, 18-13, 19-16, 19-25editing records, 16-12privileges, 16-35process views, 14-4processes

additional file queries, 14-3, 16-29additional options, 14-4, 16-53calculations, 14-3, 16-11, 16-21, 16-33

examples, 16-23fields, 16-22

initializations, 14-3, 16-3fields, 16-4

security, 14-4, 16-35, 16-36

Index I-3

Page 624: Sct4 System Tailoring Vol.1

selecting a view, 14-4subroutines, 14-4, 16-41validations, 14-3, 16-13views, 16-62

QBE forms, 16-62, 19-6creating, 16-8, 16-64default, 16-7

scripts, 16-9forms

creating, 30-1modifying, 30-13protecting in unload script utility, 8-7 to 8-8saving, 30-10searching for, 26-2style guidelines, 31-2, 31-3, 31-4

Forms Designeraccessing, 26-1accessing Database Dictionary, 9-3 to 9-5bevel tool, 28-16button tool, 28-12case sensitivity, 27-3chart tool, 28-55check box tool, 28-33combo box tool, 28-41creating

files, 30-11new forms, 30-1practice forms, 30-3

deselecting objects, 28-2design process, 26-4design tips, 31-1dialog box, 26-1fill box tool, 28-26Form Wizard

accessing, 29-2creating a form, 29-4introduction, 29-1

frame tool, 28-19graphics and animation, 31-8introduction, 25-1introduction to, 25-1invisible grid, 25-3label tool, 28-4lassoing an object, 28-2modifying a form, 30-13multi line text box, 28-23OLE container tool, 28-75options menu, 30-15picture tool, 28-30pointer tool, 28-2positioning an object, 28-2preview of the design process, 26-4properties, 27-4 to 27-7

box, 27-6

common, 27-4conditional statements, 24-3Edit Area list, 27-3entering a value manually, 27-2fonts, 27-5introduction, 25-6, 27-1sizing the properties window, 27-2window, 27-1 to 27-3

properties windowselecting a property, 27-2

radio button tool, 28-37resizing an object, 28-3saving a form, 30-10selecting objects, 28-2sizing on the drawing canvas, 25-4style guidelines, 31-2, 31-3, 31-4subformat tool, 28-50tab tool, 28-67table tool, 28-59text box tool, 28-8validating formats, 19-11wrapping label tool, 28-70

Frame tool, 28-19functions

add field function, 10-1denull, 14-6index, 14-6lng, 14-7nullsub, 14-7operator, 14-7str, 14-7substr, 14-7tod(), 14-7val, 14-7, 17-3, 17-9

Ggraph.of.unavailability, 10-16graphics and animation, 31-8grid units, 31-2

Iimporting

Import/Export utility, 5-22index

number, 9-5pools, 11-11

initialization expressions, 16-10, 17-17incorrect, 20-1

initializations process (Format Control), 14-3, 16-3fields, 16-4

invisible grid, 25-3IR Expert, 3-17

I-4 System Tailoring, Vol. 1

Page 625: Sct4 System Tailoring Vol.1

Kkeys, 3-1, 9-2, 9-5

adding, 10-26first key, 10-26keys to bottom of key list, 10-32

deleting, 10-50inserting, 10-29modifying, 10-42regenerating, 7-5 to 7-7types, 10-27

knowledge requirements, Preface-2

LLabel tool, 28-4lassoing an object, 28-2link records

creating, 19-13links records

fields, 19-2fields in link line definition file, 19-5link line definition file, 19-4posting, 19-2system tray in link line definition file, 19-6

logical fields, 9-5, 10-5logical operators, 3-2, 3-3

MMarquee tool, 28-47marquees

tool, 28-47menus

accessing Database Dictionary, 9-5messages

database unload, 5-25 to 5-27loading, 5-60 to 5-62

modifying a form, 30-13msglog file, 10-19Multi-Line Text Box tool, 28-23

Nno duplicates, 10-27no nulls, 10-27not equal to, 3-27Notification Definitions, 12-20Notification Messages, 12-9Notification Record

adding new fields, 12-6editing, 12-4

Notifications File, 12-2nulls & duplicates, 10-27number fields, 9-5, 10-4

OObjects

about, 1-2field descriptions, 1-3

OLE Container tool, 28-75OLE container tool, 28-78On Call Scheduling, 12-12oncall schedule

creating, 12-14modifying, 12-15

Oncall Schedule Panelfields, 12-13

operatorslogical, See logical operatorsrelational, See relational operators

operators (symbols)unload script utility, 8-5

Options menu, 30-15

Ppaging, 6-2palette, tools, 25-5parameters

application, 22-13Peregrine Systems, Inc., contacting, Preface-2performance, graphics, 31-8Picture tool, 28-30Pointer tool, 28-2pools

Database Dictionary, 11-11 to 11-12positioning an object, 28-2posting

additional options set up, 19-9additional options setup, 19-9automatic

confirmation function, 19-34example, 19-11

compared with Fill, 19-1confirmation function, 19-33link records, 19-2

fields, 19-2link line definition file, 19-4

post.fc, 19-9subroutines set up, 19-17user options

confirmation function, 19-34example, 19-24

variables, 19-7printing

records, 4-4privileges, 16-35Problem Management

Index I-5

Page 626: Sct4 System Tailoring Vol.1

alert records, 21-7eventout records, 21-4problem file, 10-19probsummary file, 10-19processing considerations, 21-1

Process Panelfield descriptions, 1-12

Processes, 1-11Properties Window, 25-6, 27-1 to 27-7

box properties, 27-6common properties, 27-4Edit Area list, 27-3entering a value manually, 27-2font properties, 27-5selecting a property, 27-2sizing, 27-2using the window, 27-1

property conditions, 24-3purge/archive

accessing, 10-19

QQBE list, 3-1

defined, 3-1forms, 16-62, 19-6

creating, 16-8, 16-64default, 16-7selecting views in Format Control, 14-4

query method, 5-33queries

character string length, 3-30greater than/less than, 3-27 to 3-29query window, 3-1

accessing, 3-18unload script utility, 8-4 to 8-5using functions, 3-27 to 3-31

RRAD

data typeslabel, 10-5record, 10-5

Radio Button tool, 28-37records

adding, 4-1mass adding, 5-2

using a variable, 5-6with literal value, 5-2

multiple records, 5-2Clear option, 3-17counting in QBE list, 5-20Database Dictionary, 9-2deleting, 4-2, 5-18

duplicating, 4-1editing, 16-12key conflicts, 4-6printing, 4-4, 5-19purging, 8-15 to 8-16record level options, 4-7resetting, 11-8, 11-9retrieving

all records, 3-12complex query expression, 3-25 to 3-27logical operators, 3-3query window, 3-1, 3-18query window, using, 3-19relational operators, 3-2 to 3-3

equal to, 3-6 to 3-7greater than, 3-7 to 3-8less than, 3-9like, 3-10not, 3-10starts with, 3-5 to 3-6

simple query expression, 3-20using array fields, 3-15 to 3-16using multiple fields, 3-13 to 3-14within a database, 3-1

unloading, 8-13 to 8-14updating

multiple records, 5-10multiple records with a literal value, 5-10multiple records with a variable, 5-12single record, 4-2

relational operators, 3-2 to 3-3equal to, 3-3, 3-6 to 3-7greater than, 3-3, 3-7 to 3-8, 3-27less than, 3-9, 3-27like, 3-10not, 3-10starts with, 3-5 to 3-6, 3-10, 3-20, 3-21, 3-26

reserved words, 10-2resizing an object, 28-3

Ssaving

forms, 30-10saving a new form, 30-10SCAutomate

page messages, 21-6scheduling

regenerating a database, 7-6 to 7-7reset a database, 7-3

scripts, 16-9unload

creating, 8-2 to 8-8editing, 8-9validating, 8-11 to 8-12

I-6 System Tailoring, Vol. 1

Page 627: Sct4 System Tailoring Vol.1

searching for forms, 26-2security process (Format Control), 14-4, 16-35, 16-

36selecting objects, 28-2sequential numbering

data types, 18-2getnumb.fc, 18-1, 18-3, 18-10number file, 18-10

fields, 18-11parameters, 18-3, 22-3prefixes, 18-2, 18-12, 18-13simple, 18-5suffixes, 18-2, 18-12, 18-13

ServiceCenterloading database, 5-58 to 5-64

background, 5-62 to 5-64foreground, 5-58 to 5-62messages, 5-60 to 5-62

reserved words, 10-2sizing forms, 25-4sizing the Properties Window, 27-2sort.array, 17-23

example, 17-23standard, 2-2Standard mode, 2-2statements

not, 3-27OR/AND, 3-25 to 3-26

States, 1-9field descriptions, 1-10

structures, 10-9adding arrayed structures, 10-9arrayed structures, 10-14basic employee.info, 10-13fields within, 10-11

style guidelines, 31-3Subformat tool, 28-50subformats, 8-1, 8-3, 8-7, 8-8subroutines, 16-41, 18-1, 18-13 to 18-14, 21-5

fields, 16-42parameters, 16-43process in Format Control, 14-4

Ttab pages, 28-69Tab tool, 28-67tab tool, 28-69Table tool, 28-59table tool, 28-66tabs

navigating, 28-69technical support, Preface-2Text Box tool, 28-8

toolspalette

introduction to, 25-5, 25-7, 28-1reference, 28-1

Tools PaletteBevel tool, 28-16Button tool, 28-12Chart tool, 28-55Check Box tool, 28-33Combo Box tool, 28-41Fill Box tool, 28-26Frame tool, 28-19introduction to, 28-1Label tool, 28-4Marquee tool, 28-47Multi-line Text Box tool, 28-23OLE Container tool, 28-75Picture tool, 28-30Pointer tool, 28-2Radio Button tool, 28-37Subformat tool, 28-50Tab tool, 28-67Table tool, 28-59Text Box tool, 28-8Wrapping Label tool, 28-70

tools palette, 25-5trigger.invoke.auditor, 6-17triggers

example.audit.trigger.update, 6-17trigger.invoke.auditor, 6-17

tutorial, creating a new form, 30-1

Uunique, 10-28unload script utility

commonly scripted files, 8-6 to 8-7creating an unload script, 8-2 to 8-8editing records, 8-9fields, 8-3 to 8-4introduction, 8-1protected formats, 8-7 to 8-8purging records, 8-15 to 8-16unloading, 8-13 to 8-14validating scripts, 8-11 to 8-12

updatingrecords, 4-2

Vvalidation

formats, 19-11unload scripts, 8-11 to 8-12

validations process (Format Control), 14-3, 16-13examples, 16-15fields, 16-14

Index I-7

Page 628: Sct4 System Tailoring Vol.1

validity, 16-13value-list method, 5-33views

Format Control processes, 14-4views process (Format Control), 16-62

fields, 16-63

WWrapping Label tool, 28-70

XX coordinates, 25-3

YY coordinates, 25-3

I-8 System Tailoring, Vol. 1

Page 629: Sct4 System Tailoring Vol.1
Page 630: Sct4 System Tailoring Vol.1

.