Envision Runtime Administration

488
Runtime Administration Reissued Manual as of March 10, 2010 This is a new edition of the Runtime Administration manual for Release 4.7/4.8. This edition replaces the previous edition dated November 25, 2009, and is updated for the following software updates: SU48558.63-485 Move Tool Forms to UT SU48809.93-485 Envision 2010 Spring Bundle The Primary Changes Made Section Pages Changes Made Form Reference 303 304 305 306 307 310 312 314 316 318 322 324 326 • 328 331 357 359 367 411 With the release of Colleague Studio, the replacement for Envision Toolkit, Datatel has established the following end-of-life dates for the Envision Toolkit. End of Programming Support: 12/31/2009 End of Full Tech Support: 03/31/2010 End of Limited Tech Support: 06/30/2010 Therefore, the following twenty Envision Toolkit forms were migrated to Envision Runtime (UT). These forms provide administrative, not development, functions and therefore are not replaced by functionality in Colleague Studio. These forms are listed in mnemonic order: Action Checked Out Studio Object (ACSO) Refresh RFSPECS (BTRR) Computed Column Library Dply (CCLD) Computed Columns Not Deployed (CCND) Custom Scanner Report (CCSR) Custom Declaration (CDEC) Custom Packaging Detail (CDED) Custom Declaration Objects (CDOB) Custom Development in Progress (CDPI) Custom Package Import/Export (CPIE) Custom Release Package Build (CPKG) Custom Release Package Build (CPKP) Custom Package Rebuild Detail (CPKR) Custom Code Scanner (CUSC) Migrate Computed Columns (MGCC) Other Technical Documentation (ODOC) Proc Gen to Screen Proc Conv (PTSC) Studio Object Status Inquiry (SOSI)

Transcript of Envision Runtime Administration

Page 1: Envision Runtime Administration

Runtime AdministrationReissued Manual as of March 10, 2010

This is a new edition of the Runtime Administration manual for Release 4.7/4.8. This edition replaces the previous edition dated November 25, 2009, and is updated for the following software updates:

SU48558.63-485 Move Tool Forms to UT

SU48809.93-485 Envision 2010 Spring Bundle

The Primary Changes Made

Section Pages Changes Made

Form Reference 303

• 304

• 305

• 306

• 307

• 310

• 312

• 314

• 316

• 318

• 322

• 324

• 326

• 328

• 331

• 357

• 359

• 367

• 411

With the release of Colleague Studio, the replacement for Envision Toolkit, Datatel has established the following end-of-life dates for the Envision Toolkit.

• End of Programming Support: 12/31/2009

• End of Full Tech Support: 03/31/2010

• End of Limited Tech Support: 06/30/2010

Therefore, the following twenty Envision Toolkit forms were migrated to Envision Runtime (UT). These forms provide administrative, not development, functions and therefore are not replaced by functionality in Colleague Studio. These forms are listed in mnemonic order:

• Action Checked Out Studio Object (ACSO)

• Refresh RFSPECS (BTRR)

• Computed Column Library Dply (CCLD)

• Computed Columns Not Deployed (CCND)

• Custom Scanner Report (CCSR)

• Custom Declaration (CDEC)

• Custom Packaging Detail (CDED)

• Custom Declaration Objects (CDOB)

• Custom Development in Progress (CDPI)

• Custom Package Import/Export (CPIE)

• Custom Release Package Build (CPKG)

• Custom Release Package Build (CPKP)

• Custom Package Rebuild Detail (CPKR)

• Custom Code Scanner (CUSC)

• Migrate Computed Columns (MGCC)

• Other Technical Documentation (ODOC)

• Proc Gen to Screen Proc Conv (PTSC)

• Studio Object Status Inquiry (SOSI)

Page 2: Envision Runtime Administration

Form Reference (cont’d) • 413

• 414

• Studio WorkGroup Definition (SWGD)

• Studio WorkGroup Inquiry (SWGI)

Form Reference 308 Documentation was added for the new form CC Reset for SQL Server (CCRS)

Form Reference – The Mag Tape Option Defaults (MTOD) form was obsoleted.

Section Pages Changes Made

Page 3: Envision Runtime Administration

Runtime AdministrationRelease 4.7/4.8

March 10, 2010

Envision®

For last-minute updates and additional information about this manual, see AnswerNet page 2103.81.

Page 4: Envision Runtime Administration

Runtime Administration

© 2010 Datatel, Inc. All Rights Reserved

The information in this document is confidential and proprietary to and considered a trade secret of Datatel, Inc., and shall not be reproduced in whole or in part without the written authorization of Datatel, Inc. The information in this document is subject to change without notice.

Colleague and ActiveCampus are registered trademarks of Datatel, Inc. ActiveAlumni and ActiveAdmissions are trademarks of Datatel, Inc. Other brand and product names are trademarks or registered trademarks of their respective holders.

Datatel, Inc.4375 Fair Lakes CourtFairfax, VA 22033(703) 968-9000(800) DATATELwww.datatel.com

Page 5: Envision Runtime Administration

Table of Contents

17 Overview

19 About This Manual19 In This Chapter19 Who Should Read This Manual?20 How This Manual is Organized

21 Basic Envision Concepts21 What is Envision?21 Structure of Envision22 Envision Tool Kit22 Envision Runtime23 Envision Forms23 Form Layout23 Header Block24 Data Area24 LookUp Area25 Types of Envision Forms25 Menus26 Process Forms26 Detail Forms27 Envision Fields28 Basic Concepts28 What is a Window?29 Terminology30 Types of Windows30 Vertical Windows30 Horizontal Windows31 Processing Windows32 General Purpose Forms32 Change Peripheral Defaults32 Sort/Break Criteria

33 Runtime Features and Terminology33 Features35 Terminology35 Application35 Application Trees36 Tree Reads36 Module

Runtime Administration, March 10, 2010 5© 2010 Datatel, Inc.

Page 6: Envision Runtime Administration

Table of Contents

37 Process38 Forms38 Batch Programs39 Procedures39 Operator40 Device40 Peripheral41 Security

43 Envision File Overview43 Envision Application Files47 Trans-Application Files48 Shared and Protected Files48 Shared Files50 Protected Files

51 Setup

53 Introduction to Setup

55 Defining System Parameters55 In This Chapter55 Using the Envision Parameters Edit (EPED) Form56 MIO Indexing Mode (Envision 4.7 Only)57 Oracle I/O Off (Envision 4.7 Only)57 Disable Full OCI (Envision 4.7 Only)57 SQL Select Off (Envision 4.7 Only)57 Read Cache Size (Envision 4.7 Only)58 Read Cache Log State (Envision 4.7 Only)58 Clear Cache Off (Envision 4.7 Only)59 Execute Log On59 Numeric Precision59 Subscription Enabled59 Inbound EDX TX Enabled60 Use Passive FTP60 Windows Clients60 Error Stamping61 MIO Level Check Disable61 UT Debug String61 DMI Print Server IP/Port (Envision 4.7 Only)

6 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 7: Envision Runtime Administration

Table of Contents

63 Defining Validation Codes63 In This Chapter63 Code Files64 Code Tables64 Maintaining VAL Codes65 Disabling Valcode Tables

67 Editing UNIX_CONTROL Records67 In This Chapter67 Form Used68 Editing a UNIX_CONTROL Record70 Noteworthy Fields on the UCRE Form73 Procedure for Editing a UNIX_CONTROL Record

75 Printing75 Understanding Levels of Printing75 Operating System75 Database Management System Software75 LPTR76 SETPTR76 Application Software76 Change Peripheral Defaults Form78 Defining Printers to Envision for Windows NT and

Windows 2003/200878 For All Printers Defined On The Same Local Server as

Colleague79 For a Network Print Server

83 Using the Envision Process Handler83 What is the Envision Process Handler?84 Submitting a Task to the Envision Process Handler84 Submitting a Batch Process or Report86 Submitting a VOC Paragraph87 Viewing and Editing Task Schedules87 The System Administrator’s Role88 Setting Up the Process Handler and Managing Queues89 The Process Handler Setup (PHSU) Form91 The Process Queue Management (PRQM) Form94 The Reset Process Queue Handler (RSPH) Form95 Managing Processes95 The Outstanding Processes (OPRM) Form98 The Process Scheduling (PHTS) Form

Runtime Administration, March 10, 2010 7© 2010 Datatel, Inc.

Page 8: Envision Runtime Administration

Table of Contents

100 The Process Scheduling (PRSC) Form102 The My Processes (MYPR) Form104 Working with Process Status File Records105 The Process Status Report (PSTR) Form108 The Process Status File Purge (PSFP) Form110 Using Inquiry Forms

113 Customizing an Application113 Features113 Header Blocks113 Resolution Forms114 To Change a Resolution Form115 Adding/Changing Envision Menus115 Creating a New Menu in the Same Application as the

Model116 Creating a New Menu116 Creating a Menu Based on a Model in a Higher Application118 STANDARD.FORMS (Release 17.0 only)118 Modifying a Program in STANDARD.FORMS

121 Grouping Screens121 Chaining Screens122 Security and Chaining123 Application Hierarchy and Chaining123 Function Keys and Chaining 126 Components of a Screen Chain Definition127 Procedure for Chaining Screens 129 Procedure for Reporting on Chained Screens

131 Security

133 Security Overview133 Introduction133 Logging In134 UNIX134 Windows 2003/2008135 For All Platforms137 Logging Off

139 Operating System Security139 Setting Up Login IDs and Passwords for Users139 Setting Up Users in UNIX

8 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 9: Envision Runtime Administration

Table of Contents

140 Operating System Security in UniData140 Accessing the Database Management System141 Complete Restriction141 Guidelines for Complete Restriction141 Limited Restriction142 Guidelines for Limited Restriction142 Using the Sequential File BROWSE Shell (UTFB) Process143 HOLD File Security143 Public file security (PB)143 Private file security (PR)143 Shared file security (SH)145 Output Security Groups

147 Application Security147 Types of Security148 Security Classes149 Restricting User Access on the Security Class Definition

(SCD) Form150 Restricting User Access for Detail Forms151 Guidelines for Defining Security Classes for an Application152 Procedure for Creating Security Classes153 Operator Definition154 Creating/Deleting Operator Definition Records155 Procedure for Creating an Operator Definition Record155 Procedure for Deleting an Operator Definition Record157 Using the PRCS.CTL Security Inquiry (PCSI) Form158 Process Security Classes158 Field Security Classes159 Using the Process Security Summary (PSCS) Form161 Noteworthy Fields on the PSCS Form162 Procedure for Using the Process Security Summary

Report

165 Record and Field Security165 Security Layers165 Record Security165 User Characteristics166 Evaluation by Envision Runtime166 Guidelines for Specifying Record Security167 Defining Record Security User Characteristics168 Keywords169 Constants169 Function Expressions

Runtime Administration, March 10, 2010 9© 2010 Datatel, Inc.

Page 10: Envision Runtime Administration

Table of Contents

169 Previously Defined Parameter Definitions171 Record Security Definitions175 Field Security175 Defining Field Security177 Updating and Maintaining Security

179 Encrypting Colleague Data179 In This Chapter179 Before You Begin180 Understanding Colleague Encryption180 Encryption Algorithm and Encryption Key181 Key Concepts181 Form Used182 File Used183 Defining Colleague Encryption183 Noteworthy Fields on the UTEP Form184 Procedure for Changing an Encryption Parameter185 Troubleshooting186 Troubleshooting a Failed Encryption Process

187 Maintenance

189 Maintenance Introduction189 Scheduling System Maintenance189 Saves190 Consolidation of Job Histories190 Purges190 Disk Maintenance191 Sample Daily Schedule191 Notes

193 Using File and Index Analysis Utilities193 In This Chapter194 Using WEEKLY.UDT.FILE.ANALYSIS (WUFA)195 Output Items from the WUFA Utility196 Workflow for Using the WUFA Utility197 Running the WUFA Utility200 Excluding Files from Analysis201 Using WEEKLY.UDT.INDEX.ANALYSIS (WUIA)201 Understanding the WUIA Utility203 Examples of Running the WUIA Utility206 Results of Running a Physical Check on Index Files

10 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 11: Envision Runtime Administration

Table of Contents

209 Results of Running a Logical Check on Index Files212 Recommendations When Running the WUIA Utility213 Setting up Paragraphs for the WUIA Utility

215 Envision File Services216 Add/Change Tracking217 Record Link Management219 Record Deletion220 Transaction Logging220 Requesting Transaction Logging221 History Logging222 File Indexing223 Datatel Defined Indexes223 User Defined Indexing226 Converting Files to Database Indexing234 When File Conversion Is Complete

237 Envision Runtime Reports237 Procedure Rules Documentation238 Lookup Resolution Specifications238 Record Security Specifications239 Batch Error Report239 Job Statistics Report240 Audit Trail Report

241 Purging Files241 Data Files242 Background System Files242 Batch Status243 Transaction Logging244 Database Management Files244 Database Management System Files Naming

Conventions245 HOLD245 PH246 SAVEDLISTS

247 Troubleshooting

249 Introduction to Troubleshooting249 Recovery Guidelines250 Troubleshooting Envision-Based Software

Runtime Administration, March 10, 2010 11© 2010 Datatel, Inc.

Page 12: Envision Runtime Administration

Table of Contents

253 Problems in Envision Applications253 System Setup or Security Issues257 Runtime Error Messages

261 Envision Diagnostics261 In This Chapter262 Overview of the GRDS System263 System Integrity Checking264 Envision On-demand Diagnostic Systems264 Advantages of Using the GRDS System264 Auto-generated Logging Services265 Self-Diagnostic Services265 Log Saved to Disk265 Easy to Use, Efficient, and Consistent266 On-demand Diagnostics Using GRDS267 Sample GRDS Log267 Part 1: Runtime Environment Information268 Part 2: Services Requested268 Part 3: Diagnostic Text270 How to Read a GRDS Log279 Automatically Generated Services280 AE, AX & AD (Process Argument Services: Entry, Exit,

Difference)280 PE & PX (Process Entry & Process Exit)281 CC (Call Chain)281 GS (GEN Stamp)281 NK (Next Key)282 NS & KS (Number Selected & Keys Selected)283 HS, HE, & HX (Hook Services: Sequence, Entry, Exit)283 SD (Show Demanded)284 ET (Elapsed Time)285 Programmer-Specified Services286 Accessing GRDS288 On-demand Diagnostics Using the UTDB Form288 Research the Debug String289 Specify UT Process Debug Activation (UTDB) Parameters291 Run the Debugged Form292 GRDS and UTDB: Do They Interact?

12 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 13: Envision Runtime Administration

Table of Contents

293 Appendices

295 System Setup Worksheets295 Worksheet for Device Definition (SDD)296 Worksheet for System Operator Definition (SOD)297 Worksheet for Security Classes298 Worksheet for Function Keys (SKB1)299 Worksheet for Cursor Keys (SKB2)300 Worksheet for Graphic Characters301 Worksheet For Special Purpose Characters

303 Form Reference304 Action Checked Out Studio Object (ACSO)305 Refresh RFSPECS (BTRR)306 Computed Column Library Dply (CCLD)307 Computed Columns Not Deployed (CCND)308 CC Reset for SQL Server (CCRS)310 Custom Scanner Report (CCSR)312 Custom Declaration (CDEC)314 Custom Packaging Detail (CDED)316 Custom Declaration Objects (CDOB)318 Custom Development in Progress (CDPI)319 Chain Usage Report (CHUS)320 Change Peripheral Defaults (CPDE)322 Custom Package Import/Export (CPIE)324 Custom Release Package Build (CPKG)326 Custom Release Package Build (CPKP)328 Custom Package Rebuild Detail (CPKR)330 Create Printer Control Record (CPRC)331 Custom Code Scanner (CUSC)333 Dictionary Date Convert (DDCV)333 Running the Process in Background Mode335 Define Field History (DHST)336 Difference Engine (DIFF)337 Edit Record (EDRC)338 Overview of Security for the EDRC Form339 Technical Details about the

XS.GET.RECORD.ACCESS.RIGHTS Subroutine340 Field History Detail (FHDT)342 GUI Function Button (GUIF)343 International Parameters (INTL)345 Procedure Specification (JDEF)348 Procedure Step Detail (JDET)

Runtime Administration, March 10, 2010 13© 2010 Datatel, Inc.

Page 14: Envision Runtime Administration

Table of Contents

350 Procedure Rules Documentation (JPRT)350 Specifying Output Options350 Running the Process in Background Mode352 Procedure List Specification (JSEL)354 Procedure Sort Specification (JSRT)356 LKUP: Resolution Specs (LPRT)357 Migrate Computed Columns (MGCC)358 Migrate IS-Type Subroutines (MGIS)359 Other Technical Documentation (ODOC)360 PRCS.CTL Security Inquiry (PCSI)362 Peripheral Option Defaults (PDEF)364 PDF Defaults (PDFD)365 PDF Retrieval (PDFR)366 Point to Full Release Copy (PRTF)367 Proc Gen to Screen Proc Conv (PTSC)368 Rebuild Field History (RBFD)369 Rebuild File History (RBFH)370 Record Security: List Specs (RPRT)371 Define Key Functions (RS2)372 Rec Sec User Characteristics (RSUC)374 Security Parameter Values (RSV)375 Record Security: Test Specs (RTST)376 Security Class Definition (SCD)379 Field Security Definition (SCDF)381 Record Security Setup (SCDR)383 Operator Security Report (SCOR)384 Process Security Report (SCPR) 385 Screen Chaining Specification (SCSP)388 Device Definition (SDD)388 Computer Access Strategies389 Assigning Devices on a Switch-based System389 Assigning Devices on a Port-based System389 Combining Features of Switch-Based and Port-Based

Systems389 Device Security392 Define Terminal Keyboard (SKB)392 Defining a Keyboard394 Define Function Keys (SKB1)397 Define Cursor Keys (SKB2)399 Savedlist Creation (SLCR)400 Savedlist Edit Contents (SLED)401 Menu Definition (SMD)401 Defining a New Menu

14 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 15: Envision Runtime Administration

Table of Contents

401 Adding a Process to a Menu402 Removing a Process from a Menu402 Adding a Custom Program to a Menu404 Process Control Maintenance (SMD2)407 Network Definition (SND)409 Operator Definition (SOD)411 Studio Object Status Inquiry (SOSI)412 Speed Entry Text Definition (SPDE)413 Studio WorkGroup Definition (SWGD)414 Studio WorkGroup Inquiry (SWGI)415 User Help Maintenance (UHLP)417 Update Main Remote Accounts (UMRA)419 Report on New/Obsolete Files (UNFP)420 Remote Account New Files (UNFR)422 Overwritten & Deleted Records (UODR)424 Remote Account Report (URRA)425 Batch Error Report (UTBE)426 Multiple File Indexing (UTBA)426 Oracle Clients428 File Indexing (UTBI)430 File Creation Type Defaults (UTCD)432 File Creation (UTCF)433 UT Process Debug Activation (UTDB)435 Edit Comments (UTED)436 BROWSE File Authorization (UTFA)438 Sequential File BROWSE Shell (UTFB)439 Functions439 Commands440 Job Statistics Purge (UTJP)441 Job Statistics Report (UTJR)442 User File Information (UTMF)444 User File Index Specification (UTMI)446 Transaction Log Specification (UTML)448 Record Security Specification (UTMR)449 Remote Account Specifications (UTRA)452 LookUp Resolution Specs (UTRD)453 File Resolution Defaults (UTRE)456 File Resolve Graphic Display (UTRG)458 LookUp Resolution Options (UTRO)460 ReRun a Procedure (UTRR)461 User FileSuite Information (UTSF)463 Set Printer Characteristics (UTSP)464 TXLOG Purge (UTTP)

Runtime Administration, March 10, 2010 15© 2010 Datatel, Inc.

Page 16: Envision Runtime Administration

Table of Contents

465 Modify Appl VOC Files (UTVF)466 Modify Appl VOC Misc. Items (UTVM)468 Modify Appl VOC Programs (UTVP)470 Audit Trail Report (UTXL)471 Update User Remote Accounts (UURA)473 Validation Codes (VAL)476 View Batch Process Status (VBS)478 View Single Batch Job Step (VBSD)

481 Index

16 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 17: Envision Runtime Administration

Runtime Administration

Overview

Page 18: Envision Runtime Administration
Page 19: Envision Runtime Administration

Overview

About This Manual

In This ChapterThis chapter of Runtime Administration provides the background knowledge that you need to fully understand how the software works. Specific Envision terminology is defined and an introduction to the software development tools and documentation is presented. The directory, account and file structure is also explained. An overview of conventions for cataloging programs and definitions of the control files is provided.

Who Should Read This Manual?Runtime Administration provides system administrators with an accurate and up-to-date document to use as a reference tool while installing and operating Datatel application software. The manual is intended to be useful to the new system administrator, as well as to those who have worked with Colleague for longer periods of time. Because the manual contains sensitive information that affects the performance of Colleague modules, the material contained here should not be made available to the average user of those modules.

Runtime Administration, March 10, 2010 19© 2010 Datatel, Inc.

Page 20: Envision Runtime Administration

Overview: About This Manual

How This Manual is OrganizedRuntime Administration is organized to take you through the normal process of operating the software. Below is a list of the parts and a summary of each.

Overview. Contains chapters explaining the Envision Concepts and terminology. In addition, the Overview summarizes the software and the tools used to develop each module. An overview of the account structure and Colleague file structure is provided. The section ends with an explanation of Cataloging and the Colleague Control files.

Setup. Contains chapters on setting up your terminals, system parameters, and defining Validation Codes and Address default sequences. It also explains printer setup and gives guidelines for customizing your system and writing conversion programs.

Security. Contains an overview of operating system, database management system and application software security. In addition, procedures for limiting access to the database management system and application software are provided.

Maintenance. Contains an explanation of Envision file services including tracking records, record link management, record deletion, tracking file activity and indexing. A chapter on runtime reporting is provided. In addition, guidelines for loading releases and maintaining your system are provided. The section ends with a chapter on system utilities.

Troubleshooting. Contains guidelines for troubleshooting MSP- and Envision-based software. A chapter on common Envision problems and solutions is also provided.

Appendices. Contain system setup worksheets and form reference information.

20 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 21: Envision Runtime Administration

Overview

Basic Envision Concepts

What is Envision?Envision is one of a category of computer programs referred to as computer-aided software engineering (CASE) tools. CASE tools are programs that automate the development, design, implementation, installation, and maintenance of computer applications.

Envision consists of a set of tools, each of which performs a specific function or set of functions. The same basic concepts form the foundation for all applications throughout the system. For instance, all applications perform their functions through menus for selecting functions and data forms for entering or retrieving the data required for the functions. This chapter explains the basic concepts underlying all Envision applications. Please read and become familiar with this information before you begin using Envision.

There are many advantages to developing applications with a CASE tool. CASE tool programs are easier to maintain because the generated code is already debugged. They are easier to support because the CASE tool automates the production of prompts, help messages, and documentation. All programs generated by a specific CASE tool have a standard user interface. The fact that menu selection and navigation are standard makes it easier to learn the application. The use of a central data dictionary saves computer resources. In addition, the CASE tool automatically cross-references to data elements and pre-coded routines.

Structure of EnvisionEnvision consists of two components:

Envision Tool Kit (ETK)

Envision Runtime (UT)

Runtime Administration, March 10, 2010 21© 2010 Datatel, Inc.

Page 22: Envision Runtime Administration

Overview: Basic Envision Concepts

Envision Tool Kit

The Envision Tool Kit (ETK) is the software used to create Envision-based applications. The two main components of ETK are the Painter and the Process Generator. The Painter is used to design application forms, and the Process Generator generates the code for the application, based on the parameters specified during its design.

Other ETK processes are listed below:

Painter Support

Batch Process Support

Procedure Generator

Data Element Definition

Applications

Documentation

Envision Runtime

Envision Runtime (UT) is the executable code needed to run an application. In addition to the code generated by the Process Generator, UT contains the System Administration setup forms that establish the operating environment for an application.

Some UT processes include the following:

Validation code table definition

Device and keyboard definition

Operator and security definition

Menu definition

Peripheral option defaults

LookUp resolution specifications

View batch status

Query-by-Example procedure generator

BROWSE shell

Remote account specification

Field and table definition

22 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 23: Envision Runtime Administration

Envision Forms

Envision FormsAll Envision processes are performed by entering data on Envision forms. Each function listed on the main Envision menu has its own corresponding menu, or set of menus, from which you select the processes you want to perform. Similarly, each process has its own form or set of forms for displaying or entering information.

Form Layout

In general, an Envision form contains the following areas:

Header block

Data area

LookUp area

Header Block

The header block is the set of fields at the top of the form. The fields in the header block display information about the application and process with which you are working. Figure 1 on page 24 shows header information for a form in the Envision Tool Kit.

Runtime Administration, March 10, 2010 23© 2010 Datatel, Inc.

Page 24: Envision Runtime Administration

Overview: Basic Envision Concepts

Figure 1: Sample Form with Header Block

Data Area

The data area is the middle part of the form. The contents of the data area differ according to the form with which you are working. Fields in the data area are described in the individual form description chapters.

LookUp Area

Many Envision input or inquiry forms have a LookUp area.

The LookUp area prompts you for a specific piece of information. When you enter the information, Envision extracts associated data from the database and displays it in the header block or the data area.

The LookUp area also contains options, such as Cancel, Finish, and Help.

If you select the online help from any data entry field on the form, the system displays information on the purpose of the field.

24 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 25: Envision Runtime Administration

Envision Forms

Types of Envision Forms

Creating an application with Envision consists, for the most part, of using a collection of forms and menus to specify parameters for the application. Envision uses the following types of forms:

Menus

Process forms

Detail forms

Online help

Envision Menus display a list of Envision processes. When you select a process from the menus, or enter the process mnemonic, Envision displays the form associated with that process.

Some process forms contain fields that are preceded by an asterisk (*). Detailing from one of these fields displays either a detail form or a text editing form. A detail form can be either a form for entering data related to the field or an inquiry form that displays additional information related to the field. Online help provides both process and field help messages.

The following sections describe each of these form types in more detail and explain how to use them in Envision.

Menus

A menu is an organized list of Envision functions. In Envision, each item on a menu is called a process, and each process is associated with one or more forms used to run the process.

There are four different types of processes in Envision. When only one type of process is shown on a menu, the items on that menu are numbered sequentially, beginning with the number 1. When two or more types are available, the items are either stacked in the center of the form or grouped into quadrants and sequentially numbered according to process type. The four process types and their numbering schemes are as follows:

Maintenance. Numbered sequentially from 10 to 19.

Processing. Numbered sequentially from 20 to 29.

Inquiry. Numbered sequentially from 30 to 39.

Reporting. Numbered sequentially from 40 to 49.

Runtime Administration, March 10, 2010 25© 2010 Datatel, Inc.

Page 26: Envision Runtime Administration

Overview: Basic Envision Concepts

Process Forms

You perform an Envision function from an Envision process form. The data area of a process form has spaces of specified length, called fields, where data is displayed or entered. Each major field is labeled to identify the data in that field.

The fields on a process form may or may not be preceded by a number. Usually a numbered field is a field for which you can enter or change data. There is an exception: display-only window fields are numbered to provide viewing access to the data in the window. For more information on windows, see “Basic Concepts” on page 28.

Detail Forms

Some fields on a process form are preceded by an asterisk (*). These fields are detail fields, and the asterisk indicates that you can access another form, called a detail form, from the detail field.

You can use Envision detail forms to view, enter, or modify additional information associated with the field from which you accessed the detail form.

In some detail fields, the system displays a form for the default text editor so that you can enter text or program code to customize an Envision process.

You can find additional information about detail forms and how to use them in the Guide to User Interfaces.

26 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 27: Envision Runtime Administration

Envision Fields

Envision FieldsEnvision uses the following field types:

Standard Field. A standard field is a normal full-process data entry field whose contents can be entered or modified.

Phantom Field. Phantom fields do not appear on any area of the form. These fields are input fields where the program loads variables and data that the process needs. Usually, you do not need to see the data in these input fields. Phantom fields often appear as prompt fields just below the body of the form. Such fields usually prompt for a record ID or other key for the main record that the process needs.

Inquiry Field. An inquiry field, also called a display-only field, is a field containing data that cannot be accessed or changed from the process form on which it appears. Although inquiry fields appear on the form, you position the cursor on an inquiry field to access the field. Inquiry fields display data that can be used to determine other data that you need to enter or change. A data element may appear on one process form as an inquiry field and on another process form as a standard field.

Runtime Administration, March 10, 2010 27© 2010 Datatel, Inc.

Page 28: Envision Runtime Administration

Overview: Basic Envision Concepts

Basic ConceptsMany Envision application forms display information or accept data entry through fields called window fields. Windows can appear on both process and detail forms.

What is a Window?

A window is a field in which you can enter or display more than one instance of a single data element, or a single set of data elements. In Envision, we refer to the data elements as values, and we refer to the fields in a window as multi-valued fields. A window can contain either of the following:

A list of single values. A window with a list of single values is called a single-valued window.

A list of value sets. Each value set consists of a basic value, called a controller, and a group of other values associated with the controller. This kind of window is called a multi-valued window.

An example of a single-valued window is a window that contains a list of names only. An example of a multi-valued window is a window containing a list of names where each name is accompanied by other information, such as an address and phone number.

Windows make it possible to display more information on a single form than is possible with a single-valued field. Consider a field called Schools Attended, which might be used in the Colleague system to display information about an applicant. The applicant may have attended more than one school before applying to a college. If the form shows the Schools Attended field as a single-valued field, you would see information about only one value for a data element – that is, only one of the many schools that the applicant attended.

If the form shows the Schools Attended information as a multi-valued field, then you could view all information about each school on a single line of a window. You could also scroll vertically or horizontally through all entries in the list.

Envision numbers each value or set of related values, and you can retrieve information using special window movement keys and commands.

28 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 29: Envision Runtime Administration

Basic Concepts

Terminology

The following defines some of the terminology surrounding windows:

List. A common data structure in Envision. A list provides storage for and maintenance of many values for a single data element. The list structure is the basis for the following Envision database usage types:• List field. A multi-valued set of data values. The list data structure is open-

ended; that is, there is no theoretical limit to the number of values that can be in a list.

• Associated field. A set of related data values maintained as a group; groups are maintained across lists.

• Q-select field. A list of record keys that point to additional information in another file.

• Block field. A list of data values that cannot be modified and are displayed as a single entity.

Window Controller. The first (left-most) value in a window. This value determines the names used for window variables and subroutines. The window controller is the key field for the window. The values of other window elements are determined by the value entered into the window controller. In windows containing keys to secondary files, the window controller is the field containing those keys.

When a window contains more than a single data element (that is, when the window consists of parallel lists or associated multi-values), the controller is always the first (left-most) data element in the sequence of window elements. The controller characteristics apply to all of the associated fields within the window; however, Envision stores only the controller key, not the associated field values, as part of the window. Based on the controller key, Envision accesses and displays the values for these associated fields whenever you run the process.

Controller-on-the-fly. A feature that lets you define the set of controllers to view in a window. For instance, a professor may want to view the grades for a subset of the students he teaches. The window the professor is paging through shows records for all the students he teaches, but he may only want to look at records for students in a particular course or course section. Using the controller-on-the-fly feature, the professor can define a subset of records that he wants to view. In effect, this feature provides an on-screen query process, which then permits modifications to the records instead of just reporting on them.

Window Group. A numbered set of data items appearing on one line of a window.

Page. The set of groups that are displayed at one time. A window group appears on only one page. If each window page consists of three window groups, page 1 displays groups 1 through 3; page 2 displays groups 4 through 6; and so on. Regardless of how you select a window group, its

Runtime Administration, March 10, 2010 29© 2010 Datatel, Inc.

Page 30: Envision Runtime Administration

Overview: Basic Envision Concepts

position within the page is constant. Each page except the last page has a constant number of groups. The last page may contain fewer groups.

Data Field Group. A single-line window that does not scroll.

Window Element. A distinct data item within a window.

Window Label. A heading that identifies a window.

Field Label. A descriptive title identifying a data element on the form, either for a single field or for a window with multiple elements per line.

Status Line. A line of information displayed at the bottom of the form to help you use windows. When the cursor is in a window, the status line displays either Controller or Element, followed by the field label to indicate the location of the cursor. The total number of entries and the line number of the cursor appear on the right side of the status line:

Value n of m. Where n is the cursor location line and m is the total number of entries in the window.

Types of Windows

Envision has two types of windows: Vertical windows and Horizontal windows.

Vertical Windows

Vertical windows scroll up and down. A vertical window may have one or many values in a group. Envision processes individual fields in the window in sequence, beginning with the controller (the left-most value) and continuing to the last associated value before proceeding to the next set of values.

Horizontal Windows

Horizontal windows scroll left and right. A horizontal window usually has only one value per group. Horizontal windows are less common than vertical windows and are usually used for shorter fields, like code validation fields, when the form design does not permit a vertical window.

30 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 31: Envision Runtime Administration

Basic Concepts

Processing Windows

Each window on an Envision form has a corresponding set of internal subroutines for processing the window. The names of the subroutines indicate their functions with respect to the window controller:

WNDW.INIT.controller. Initializes all variables used to process values in the windows.

WNDW.DEL.controller. Runs when you delete a window group.

WNDW.INS.controller. Runs when you insert a window group.

WNDW.controller.MOVEMENT. Determines the next data element to be processed.

CALC.WNDW.DSPLY.controller. Calculates the current group number and specifies which group appears on the current page.

Envision also uses two variables when processing windows:

WNDW.controller.INDX. Determines the current group number.

WNDW.controller.LNE.COL. Determines the current display line.

For each list in a window, Envision keeps track of two variables:

VL.fieldname. Contains all values defined for the data element.

V.fieldname. Contains the value from the list of the current window iteration (WNDW.controller.INDX).

VS.fieldname. Indicates that the lists within a window have been added to, or taken from, a master list; assigned by Envision.

Runtime Administration, March 10, 2010 31© 2010 Datatel, Inc.

Page 32: Envision Runtime Administration

Overview: Basic Envision Concepts

General Purpose FormsIn addition to the application-specific menus, process forms, and detail forms, Envision also provides some forms that you may use from any application:

Change Peripheral Defaults form

View Reports on the Terminal Using BROWSE form

Additional Selection Criteria form

Sort/Break Criteria form

Process Submission form

Run a Batch Process form

Run a Report form

Change Peripheral Defaults

The Change Peripheral Defaults form displays options for specifying processing parameters and the destination of the report (either printed to hardcopy or displayed on the form). The options on the Change Peripheral Defaults form reflect the specific options that your operating system supports.

Sort/Break Criteria

Use the Change Sort Specification form to change the order in which a list of values is sorted. This form automatically appears during a procedure if you are able to alter the default sort sequence. You cannot access this form directly from a menu.

32 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 33: Envision Runtime Administration

Overview

Runtime Features and Terminology

FeaturesEnvision Runtime (UT) contains the executable code needed to run an application. In addition to the code generated by the Process Generator, UT contains the System Administration setup forms that establish the operating environment for an application. Some of the features include the following:

Direct Access. Envision Runtime allows the designer to establish whether processes are called by a numeric menu selection, by a direct access mnemonic, or by both. Using both allows the novice user to begin with self-explanatory menu selections and proceed to direct access mnemonics with more experience. Of course, selection by mnemonic has implications on system performance because it provides much faster access to the desired data by the terminal user.

Tools. Several tools aid the implementation of software systems. One particularly useful feature is a terminal definition file that allows the user to set up files for any unique terminals being used on the system. The actual programs only deal with a “virtual” terminal. The terminal file is completely external to the application software routines so that the software is completely adaptable to the installed terminal environment.

Security. A complete security system is included in Envision Runtime. The System Administrator may define security at the process, record and field level. This security can define whether the login ID has create, update, or read-only capabilities. One important feature of the security system is that only those processes that the login ID is authorized to perform appear on the form. This greatly simplifies implementation and training procedures.

Recovery. Envision Runtime provides an optional recovery/security feature called transaction logging. A transaction logging process for each file is selectable by the System Administrator. Before and after values of the data elements in a file are logged to a transaction file. In addition to the old and new value, the time, date, and operator ID are captured. If a system failure occurs and database recovery is required, updates can be made to the database by reentering data that is missing. Reports can be generated from the log that displays the information that must be recovered. This capability can also be used as a training tool to ensure that the operators are entering the data correctly.

Runtime Administration, March 10, 2010 33© 2010 Datatel, Inc.

Page 34: Envision Runtime Administration

Overview: Runtime Features and Terminology

Form Processes. The Runtime application is comprised of both interactive form processes and on-demand utility programs. Form processes allow users to enter system parameters and characteristics through user friendly interactive prompts. These standard Envision forms help the user define new terminal types, operator characteristics, customized menus and ad-hoc database queries.

Utilities. Envision Runtime’s utility programs are the core to the execution of an Envision-based application. The utilities centralize the reading from and writing to disk. Each Envision process narrows the range of potential loss of data by grouping disk I/O into a single burst. The transaction commit capability allows a set of updates within a program to be treated as one. Instead of each update being treated individually, the set of updates are treated as a group. Transaction commit mitigates the possibility of an incomplete system update during a computer or disk failure by concentrating all the record updates into a single burst of disk writes. This also sets the stage for more comprehensive recovery procedures.

Samples of the functions provided by these utilities include:

Envision Menu Processor. Controls the listing of options available to a user and the security access a user has to a selected process;

Envision Help Processor. Displays both one-line help messages and windows of help text, providing the user with an on-line reference manual;

Envision Error Processor. Provides the user with specific messages concerning erroneous entries;

Envision Manage Input/Output (MIO) Suite. Set of programs which centrally manage disk I/O and disk files;

Envision Procedure Generator. Takes predefined process steps to define a series of database environment commands to fulfill the desired function.

These utility programs provide a seamless environment in which a user encounters familiar form displays and can navigate within the application using familiar key strokes. Every Envision-based application has the same “look and feel” because the Envision Runtime utility application drives every one of them.

34 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 35: Envision Runtime Administration

Terminology

TerminologyEnvision is a sophisticated and comprehensive application development environment and, as such, has a vocabulary all its own. Some of the terms presented in this section are standard industry terms. Others are terms coined specifically for Envision. The purpose of this section is to present some of the more fundamental concepts key to Envision.

Application

An application is a set of programs which are grouped together to meet the needs of a functional area. These programs allow users to maintain and display information stored in the database associated with the grouping of programs. The programs and the elements in the database share certain characteristics specific to the functional area. For example, Colleague Finance (CF) is an application, and the General Ledger (GL) and Budget Management (BU) are modules that reside in CF.

Functional areas, however, sometimes have fundamental characteristics in common. The modularity of the application structure does not provide for the sharing of these characteristics directly across applications. The characteristics could be defined in more than one application, but such a definition requires redundant storage and maintenance.

Application Trees

Envision uses application trees to provide a hierarchical relationship among applications. At the root of every application tree is the Runtime application, UT. The UT application encompasses the most fundamental characteristics required by every other Envision-based application. Every other Envision-based application is subordinate to, or is farther down the tree than, the UT application.

Any subordinate application can “look up” the tree to use any characteristic defined further up the tree. Two applications that have characteristics in common, therefore, can maintain their modularity and integrity since common characteristics can be defined in an application which appears further up in the tree structure.

Runtime Administration, March 10, 2010 35© 2010 Datatel, Inc.

Page 36: Envision Runtime Administration

Overview: Runtime Features and Terminology

Example: Consider a fund raising, a human resources, and a demographics application. Each application has characteristics specific to its own functional area. Fund raising has programs for maintenance of donation information, while human resources has programs for hiring new employees. Each application contains common characteristics: a person’s name, address, date of birth, social security number and so on. These common characteristics are defined in an application to which both applications are subordinate; the demographics application. Each subordinate application can use the definitions common to each that reside in one place.

Tree Reads

When a requested characteristic does not reside in a given application, Envision performs what are called tree reads. A tree read searches from the subordinate application up the tree through each higher application for the requested characteristic. Each application in the tree is searched until Envision finds the characteristic or until it reaches the base of the tree, the UT application. If the characteristic is not found in any of the higher applications, Envision informs the requesting program, at which time the user may add the new characteristic to the subordinate application, if permitted. If Envision finds the characteristic in a higher application, the subordinate application be able to only use the definition, being unable to modify the definition.

Tree reads provide another benefit: shared characteristics may take on a special meaning in a subordinate application. You may redefine a characteristic in a subordinate application, where permitted, so that when Envision performs a tree read for that characteristic, it finds the customized definition in the subordinate application. While this feature seems to negate the benefit of unique characteristic definitions, Envision provides the flexibility to redefine characteristics as circumstances dictate.

Module

A module in Envision is a subset of programs within an application which are more closely related within the functional area. While all programs share characteristics within the functional area, some programs are more tightly coupled and therefore can be segmented even further.

Datatel considers each module within an application as a separately deliverable part of the application. For each application, there is at least one base module and many optional modules. A base module is a module on

36 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 37: Envision Runtime Administration

Terminology

which the other modules in the application are dependent. A base module can function without an optional module, but the base module must be present in order for an optional module to run. An example of this dependence is the Colleague Finance Budget Management module. The Budget module requires the base General Ledger module to be present; Budget cannot run without General Ledger. General Ledger, however, can run without Budget.

The base module for an application is always included with the delivery of that application.

Process

An Envision process provides a function or service within a functional area. The function may be interactive maintenance of several data elements, printing values stored in the database to a line printer, or modification of data elements run without user interaction. A process is defined through the Envision Tool Kit, resulting in the creation of a program. The compiled version of these programs can be run by the end user through the Envision Menu Processor.

The Envision Menu Processor is itself a process. This utility program from the Runtime application, UT, displays to the user a list of processes from which the user can select. Each process on the menu can be a program which provides a certain function, or another menu, which will present to the user another list of choices. The Menu Processor is run each time an Envision-based application is initialized and remains active until the user leaves the application.

There are three kinds of processes in Envision:

Forms

Batch Programs

Procedures

Runtime Administration, March 10, 2010 37© 2010 Datatel, Inc.

Page 38: Envision Runtime Administration

Overview: Runtime Features and Terminology

Forms

Envision form processes are interactive programs that solicit user input by displaying information on a form and accepting information from a terminal keyboard. As described in the previous chapter, there are four basic kinds of Envision forms:

Menus

Processes

Detail Form

Online Help

Each type of form displays a given amount of information on the user’s form. The user then processes the information presented. Envision forms process single records at a time; there is one primary record, which may have associated secondary records. The current record must be released before the user can process another record.

Batch Programs

Envision Batch Programs are non-interactive looping programs that work from lists of records. The typical batch structure allows the program to perform the same functions on selected records. While some batch programs work on only one record, Envision provides fourth-generation (4GL) programming statements which allow the processing of many records in exactly the same way.

A special case of a batch program is an Envision Report. Envision Reports are defined as read-only batch programs which display the data the user specifies in the way he specifies. Sophisticated front-end forms allow the analyst to control the flexibility and appearance of a report, yet still provide the end user with options and features to customize the report.

Since batch programs usually work on selected groups of records, they usually do not stand alone as executable processes from a menu. Batch programs are usually incorporated into Envision Procedures.

38 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 39: Envision Runtime Administration

Terminology

Procedures

An Envision Procedure is a predefined sequence of steps which provide a specific function. Each step in a procedure must be defined before it can be included as a step. The following are the types of steps valid in an Envision Procedure:

User Forms. Form processes used within a procedure to elicit option and parameter information from an end user.

Jobs. Batch and form processes, programs, and any other procedure step that is not a user form or list step.

List specifications. Create SSELECT or SELECT commands within a procedure to create a list of records based on user input entered from a form.

Features such as conditional branching and database statement inclusion allow the analyst to tailor the execution of the procedure to the options and parameters specified by the user. Procedures allow the analyst to “link” together distinct processes with pre-defined Runtime forms.

Operator

The term operator in Envision is synonymous with user: any person who uses an Envision-based application. Each operator must have a valid operator definition in order to use an application. The definition may reside in the application the operator is using, or may reside in an application higher up the tree. The operator definition controls the access the user has to the processes in the application and other characteristics unique to the operator, such as the operator’s Envision password and initial application menu.

Each operator is identified by his login ID. This ID is also used for identifying when the user adds or changes a record in the database. When a user runs a procedure in background mode, Envision uses his login ID as part of the unique key which records the results of the procedure. Any person attempting to use an application for which he has no operator definition is logged off the system.

Runtime Administration, March 10, 2010 39© 2010 Datatel, Inc.

Page 40: Envision Runtime Administration

Overview: Runtime Features and Terminology

Device

A device in Envision is a terminal. Each unique combination of display characteristics and keyboard mappings has a unique device definition. The display characteristics define how Envision displays graphics characters and video attributes on the user’s terminal form. Keyboard mappings associate the character strings generated by keys on the user’s terminal keyboard with special Envision functions.

The device definitions are shared among all Envision-based applications. These definitions include security restrictions for users of the device and passwords associated with the device.

Peripheral

A peripheral in Envision is a destination for output from procedures. Peripheral definitions include line printers, terminals and magnetic tape drives. Some procedures allow the end user to alter the definition of the peripheral for that execution. Each peripheral definition includes the following characteristics:

Description. A description that is used in LookUp resolutions, procedure specifications, and procedure definition reports.

Width. An integer that controls the end-of-line processing for output to the peripheral.

Length. An output length is the number of lines reserved for printing output from a batch program or a report. The total of the output length, the top margin, and the bottom margin is the number of lines for the printed page.

Top Margin. The number of lines left blank at the top of the output.

Bottom Margin. The number of lines left blank at the bottom of the output.

Mode. The peripheral mode determines the default target output device for the peripheral definition.

Form Name. The spooler system of your host computer may allow form names that prevent the printing of documents unless a special form is loaded in the output device.

Banner. For printed output, this name appears on the banner page. For output target from the HOLD file, this name becomes the record ID for the output.

Location. Some spooler systems allow you to specify a location at which printed output will be processed.

Copies. The number of copies of the output to produce.

40 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 41: Envision Runtime Administration

Terminology

Defer Time. Defining a print time is useful for long reports or batch programs. By deferring execution, you can reduce the load on your host computer at peak usage times and increase the load at low-usage times.

Other Options. Other printer options may be specified to further control the production of the output.

Security

Envision Security allows the system administrator to define and control which processes, records, and fields users may and may not access. Envision Security controls user access using three layers of security definitions:

1. Menu and Process Security are controlled via security classes. Each operator is assigned a security class and each security class defines the menu and process mnemonics available to users in that class. The Envision Runtime Menu Processor controls the user’s access to menus and processes according to his security classes. The Menu Processor does not display mnemonics for which the user has no access. Even if the user knows a mnemonic for which he has no access, the Menu Processor prevents the execution of the menu or mnemonic associated with that mnemonic.

2. Record Security allows the system administrator to restrict the access to certain records in selected files based on selection-like criteria. Each user has a set of predefined characteristics. Envision Runtime compares these characteristics against the security criteria for a requested record or list of records. If the user has access to the requested record or list of records, Envision Runtime allows the user to process the record as defined by the security criteria. If the user fails to pass the security test, access to the record is denied. Record Security is an optional Envision file service provided only for files defined through the Envision Tool Kit. Non-Envision files are not allowed to have record security definitions. Since only files defined in Envision can have record security definitions, all Envision processes honor record security.

Runtime Administration, March 10, 2010 41© 2010 Datatel, Inc.

Page 42: Envision Runtime Administration

Overview: Runtime Features and Terminology

3. Field Security allows the system administrator to selectively control access to the data stored in certain data elements no matter how those elements are used in an Envision process. Field security uses the same security class definitions as do Menu and Process Security. The class restrictions for field security provide several options which tailor the user’s access to data to the needs of both the user and the system administrator. Field Security is an optional Envision file service provided only for files defined through the Envision Tool Kit. Non-Envision files are not allowed to have record security definitions. Since only files defined in Envision can have record security definitions, all Envision processes honor record security.

42 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 43: Envision Runtime Administration

Overview

Envision File Overview

Envision Application FilesEvery Envision-based application requires certain files in order to run the processes of the application. These required files are called Envision files. Each application has its own suite of files called application files. Listed below is a sample of the application files in the suite:

appl.CDD

appl.DOC

appl.ENV*

appl.ERROR*

appl.FILE.SPECS*

appl.HELP*

appl.HELP.LONG*

appl.INSERTS

appl.MENU*

appl.OBJ

appl.OPERS*

appl.PARMS*

appl.PPROCESS*

appl.PRCS.CTL*

appl.PRCS.DEF

appl.PRCS.GEN*

appl.PRINTERS*

appl.SECLASS*

appl.SOURCE

appl.SUBROUTINES

appl.VALCODES*

appl.VOC

Note: Each filename is prefixed by appl, where appl is the mnemonic for the application. This suite of files stores the information pertinent to the application. Each Envision-based application on your system has this suite of files defined.

Runtime Administration, March 10, 2010 43© 2010 Datatel, Inc.

Page 44: Envision Runtime Administration

Overview: Envision File Overview

File names above with an asterisk (*) indicate those files that are subject to tree reads. Tree reads allow Envision Runtime to search through the envision hierarchy for a requested record. Envision Runtime first searches the current application file for a requested record. If the record is not found in the current application file, Envision Runtime searches the next application in the application tree for the requested record. Envision Runtime continues to traverse the application tree until it finds the requested record, or until it reaches the UT application. The application tree is stored in the appl.CTL file.

Following is a description of each of the application files:

appl.CDD. Stores the records of the Central Data Dictionary. Each data element defined for the application has a record in the CDD. The Envision Code Generator in the Envision Tool Kit uses these definitions, along with the definitions from FILE.SPECS and PRCS.DEF to create programs.

appl.DOC. Stores handwritten technical documentation on selected topics for the application.

appl.ENV. Stores the Runtime definition of an Envision form process. These tables control what fields are processed on a form and where the data for the fields appears on the form. Each table is keyed with the process name that uses it. The ENV file is populated each time a form process is generated, and cannot be modified by end users.

appl.ERROR. Stores standard application error messages that are shared among Envision processes. Each standard error message has a unique key which is the concatenation of the module in which the error message was first used and a sequential number. The ERROR file is populated via the Error Message Definition (EMSG) form and may be modified by end users.

appl.FILE.SPECS. Stores the definitions of files created with the Envision Tool Kit. These definitions provide the physical mapping between the Central Data Dictionary and actual storage. The Envision Code Generator uses these definitions, along with those from the CDD and PRCS.DEF files, to create programs.

appl.HELP. Stores the one-line help messages end users see when they access help. There are three kinds of help messages:• process help• general field help• form-specific field help

Process help records are keyed by the process name for which they are used. General field help records are keyed by the data element which they document. Form-specific field help records are keyed by a concatenation of the process name and the data element name. General field help records also contain database information such as the file for the data elements, the data element’s position in the file, and a list of processes that use the data element. The HELP file is populated via the Process/Help Message Definition (HLP) form and may be modified by end users, although modifications of help messages are overwritten when subsequent Envision-

44 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 45: Envision Runtime Administration

Envision Application Files

based applications are loaded.

appl.HELP.LONG. Stores the help text which end users see after pressing the [RETURN] key when viewing the short help message. The HELP.LONG records are keyed in the same way that the HELP records are, and contain the lines of text which make up the long help messages. The HELP.LONG file is populated via the Process/Help Message Definition (HLP) form, and may be modified by end users, although modifications of help messages are overwritten when subsequent Envision-based applications are loaded.

appl.INSERTS. Stores the blocks of code that are shared among the programs in the application. These blocks are called insert modules.

appl.MENU. Stores the menu definition records which control the appearance of menus for the application. In addition to a list of processes and menus which appear when the menu is run, MENU records also contain the menu’s title. The MENU file is populated via the System Menu Definition (SMD) form. Menu records included with the delivery of an application should not be modified, but new menu records may be added by end users.

appl.OBJ. Stores the compiled version of all generated programs. These object code records are what Envision Runtime uses to run the processes of the application.

appl.OPERS. Stores the definition of each user who has access to the application. Operator security, initial application menu, and Envision password are among the parameters stored in each OPERS record. The OPERS file is populated via the System Operator Definition (SOD) form and is defined entirely by your site.

appl.PARMS. Stores application level parameters such as resolution form definitions and Easy Screen definitions.

appl.PPROCESS. Stores the procedural step statistics for the application. Each procedure run has a record in this file.

appl.PRCS.CTL. Stores the control records for each process and file in the application. Process records are keyed by the mnemonic for the process, and are used to determine in which menu quadrant the process is displayed on a menu, to define process security, and to determine the program to run when the process is selected by an end user. File records are keyed by the file’s name and define the fields that Envision Runtime knows about for the file. The PRCS.CTL file is populated via the System Menu Definition (SMD) form. Do not modify process control records included with the delivery of an application. New process control records may be added by end users.

appl.PRCS.DEF. Stores the definition for each process in the application. The Envision Tool Kit records are the real source code for Envision processes. The Envision Code Generator uses these process definitions,

Runtime Administration, March 10, 2010 45© 2010 Datatel, Inc.

Page 46: Envision Runtime Administration

Overview: Envision File Overview

along with definitions from the CDD and FILE.SPECS files, to create programs.

appl.PRCS.GEN. Stores details of either a procedure definition or a list specification. For procedure definitions, the appl.PRCS.GEN record has a list of the steps that make up the procedure, as well as defining other parameters that control the options available to end users when the procedure is run. These records are populated via the Procedure Definition (PGDF in ETK and JDEF in Runtime) forms. Procedure definition records included with the delivery of an application should not be modified, and new records should not be added. To add new procedures, use the Screen Procedure Specs (SPSP) form. For list specifications, the appl.PRCS.GEN record contains specifications such as selection, sort, and break criteria. These records are populated via the Procedure List Specification (PGLS in ETK) form.

appl.PRINTERS. Stores the peripheral definitions for the application. These definitions control the appearance and destination of the output for batch programs and reports. In addition to line printers and other hardcopy devices, the PRINTERS file stores records for magnetic tape output devices. The PRINTERS file is populated via the Peripheral Definition (PDEF) form in the Runtime application (UT). Do not modify peripheral definition records included with the delivery of an application. New peripheral definition records may be added.

appl.SECLASS. Stores the security class definitions for the application. These definitions are lists of processes that the end users are allowed to access. The SECLASS file is populated via the Security Class Definition (SCD) form of the Runtime application. The system administrator controls the security classes defined for each work-flow of users of the application.

appl.SOURCE. Stores the source code for all the generated programs and insert modules for the application. The Envision Code Generator uses the data base compiler to generate the executable object code, which is stored in the appl.OBJ file.

appl.SUBROUTINES. Stores the source and object code for all non-generated programs and subroutines.

appl.VALCODES. Stores the validation and translation tables for coded data elements. Each table contains codes, their descriptions and any special processing associated with each code value. End users can modify some tables, while other tables are restricted from modification. See the documentation for a each application to determine if you can modify a specific VALCODE table.

appl.VOC. Stores the information necessary to update the current account and any associated REMOTE accounts. Written to RFSPECS for use at runtime.

46 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 47: Envision Runtime Administration

Envision Application Files

Trans-Application Files

In addition to the suite of application files, every Envision-based application requires trans-application files. Parameters which affect every Envision-based application are stored in files shared by all applications. The files shared among applications, called trans-application files, are listed below:

APPL.CTL

DEVICES

RFSPECS

STRATEGIES

SYSDEFS

UFSPECS

A description of each follows:

APPL.CTL. Stores information about each application defined on a development account, and how those applications interact. In addition to informational parameters such as the name and purpose of an application, APPL.CTL is where the application tree for each application is stored. An application tree provides the hierarchy of an application structure and how information is shared among the applications in the tree. See page 35 for a more detailed discussion on applications and application structures.

DEVICES. Stores the definitions of terminals. These definitions, in addition to specifying the display and keyboard tables to use for a particular terminal, also specify global security classes which restrict end users using this device definition, a device password which must be specified when an end user attempts to use the device, and date and time stamping information, including the last end user to use the device.

RFSPECS. The Runtime file specifications file stores the parameters which control how Envision processes records when they are written to files. These Datatel-defined parameters include indexing algorithms (see page 222), record link management (see page 217), and record add/change tracking (see page 216). RFSPECS also stores information that the System Administrator specifies for a file, including transaction logging (see page 220) and user-specified indexing.

STRATEGIES. All files have a STRATEGIES record. They are used by Colleague to map each field belonging to a file to the column in SQL Server or Oracle, or the file and DICT in UniData.

SYSDEFS. Stores many different kinds of global parameter records. Among these global parameters are the display and keyboard tables used in device definitions and the network definition for your system.

UFSPECS. The UFSPECS or user file specifications file stores the user-defined parameters which control how Envision processes records when they are written to files. The parameters specified in the UFSPECS file are

Runtime Administration, March 10, 2010 47© 2010 Datatel, Inc.

Page 48: Envision Runtime Administration

Overview: Envision File Overview

encoded and written to the associated RFSPECS record for the file in question. Transaction logging and user-specified indexing are two of the parameters defined in UFSPECS and written to RFSPECS at runtime.

The trans-application files and tree-read application files have the greatest impact on the set-up procedures defined in this chapter. A device definition exists regardless of application. An operator record may exist, not in the current application, but in an application several layers higher in the application tree. A security class may be defined at a higher-level application, but redefined to add further restrictions at a lower-level application.

Shared and Protected Files

An Envision file, whether application or trans-application, falls into two categories: shared and protected.

Shared Files

Shared files are Envision files that Datatel provides some or none of the records and you as the user control the contents of the file. For example, consider the trans-application file SYSDEFS. Datatel provides certain records which should not be changed, such as display tables and default keyboard tables. Other records in SYSDEFS, such as TASKLIST and ENVISION.PARAMETERS, are controlled completely by you, the system administrator. Another example of a shared file is the application file MENU. While Datatel provides default menu records which are refreshed for each release, you can create your own menu records to customize your Envision-based application.

Below is a list of the shared files. Do not change records provided by Datatel in the files marked with an asterisk (*). Though you may add records to these files, do not change existing records.

48 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 49: Envision Runtime Administration

Envision Application Files

Shared Application FilesERROR*

MENU*

OPERS

PARMS*

PPROCESS

PRCS.CTL*

PRCS.GEN*

PRINTERS*

QBEDEF

SECLASS

VALCODES*

VOC*

Shared Trans-application FilesAPPL.CT*

DEVICES*

REMOTES

RFSPECS*

SYSDEFS*

UFSPECS*

Runtime Administration, March 10, 2010 49© 2010 Datatel, Inc.

Page 50: Envision Runtime Administration

Overview: Envision File Overview

Protected Files

Protected file is the final category of Envision files. Protected files contain records that affect the execution and generation of an Envision-based application. Do not change the records in the following protected Envision files:

CDD

DOC

ENV

FILE.SPECS

HELP

HELP.LONG

INSERTS

OBJ

PRCS.DEF

SOURCE

SUBROUTINES

Since these files are stored as a part of an Envision release, the records in each file will be replaced when a new release is loaded and installed.

Note: While you may be able to change the values stored in the records of these files, we strongly recommend you do not change any records in these files without first consulting Datatel.

50 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 51: Envision Runtime Administration

Runtime Administration

Setup

Page 52: Envision Runtime Administration
Page 53: Envision Runtime Administration

Setup

Introduction to Setup

This section defines tasks that must be accomplished before the Colleague software can run at your site. In addition, guidelines for optional custom tasks are provided.

Complete instructions for setting up user interfaces are outlined, which includes defining your type of system to Envision, defining terminal tables for users, setting up terminal parameters, creating custom terminal tables, and setting up the User Interface.

Procedures for printing and directing Colleague print jobs are also outlined, as well as instructions for running a job in background mode.

Finally, conversion guidelines are provided for sites writing their own conversions and sites contracting Datatel to write the conversions.

Worksheets to assist with some of the setup tasks can be found in “System Setup Worksheets” beginning on page 295.

Runtime Administration, March 10, 2010 53© 2010 Datatel, Inc.

Page 54: Envision Runtime Administration

Setup: Introduction to Setup

54 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 55: Envision Runtime Administration

Setup

Defining System Parameters

In This ChapterThis chapter contains detailed information about the Envision Parameters Edit (EPED) process. Discussion of parameter records pertaining to the modules within an application may be found in the application administration guides.

Using the Envision Parameters Edit (EPED) Form

Use the Envision Parameters Edit (EPED) form shown in Figure 2 and Figure 3 on page 56, to control various system-wide options of Envision. These include the type of indexing to use, whether various performance enhancing features are active, and data logging options. Since most of the options can have very wide ranging effects, some undesirable, use extreme caution when making changes from the defaults.

Figure 2: Envision Parameters Edit (EPED) Form (Envision 4.8)

Envision 4.8 only

Runtime Administration, March 10, 2010 55© 2010 Datatel, Inc.

Page 56: Envision Runtime Administration

Setup: Defining System Parameters

Figure 3: Envision Parameters Edit (EPED) Form (Envision 4.7)

MIO Indexing Mode (Envision 4.7 Only)

Control the type of record indexing used by Envision. This value can be a number from 0 to 5; however, options 0, 1 and 2 are obsolete and should never be used. Here is a description of each option:

0 - (OBSOLETE) Original database indexing

1 - (OBSOLETE) Original Envision file based indexing

2 - (OBSOLETE) Enhanced original Envision file based indexing

3 - Current Envision file based indexing

4 - Current database indexing

5 - Either database or Envision file based indexing, determined file-by-file

Note that changing between modes 3 and 4 is only part of the reindexing process. All the indexing specs must be defined in a way that works with the selected option. For example, mode 3 requires a data storage file for each index, and mode 4 requires a storage field for subroutine-based indices. Also, in order to function properly, all indices must be rebuilt, using either UTBI or UTBA, after changing this flag.

Envision 4.7 only

56 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 57: Envision Runtime Administration

In This Chapter

Oracle I/O Off (Envision 4.7 Only)

In an Oracle environment, Envision attempts to satisfy I/O requests via direct SQL statements for those processes that are generated with support for such operations. If you do not want to use this optimization, enter Yes in the Oracle I/O Off field. The default for this field is “No”.

Disable Full OCI (Envision 4.7 Only)

In an Oracle environment, MIO does full record I/O using custom OCI SQL I/O instead of relying on SQLator. If problems occur with full record logic, you can enter Yes here to use SQLator I/O instead of OCI full record I/O. The default for this field is “No”.

SQL Select Off (Envision 4.7 Only)

In an Oracle environment, execution of UniData-type SELECT commands is mapped to equivalent SQL selects. This mapping can dramatically decrease the time required for such operations. If you do not want to use this optimization, enter Yes in the SQL Select Off field. The default for this field is “No”.

Read Cache Size (Envision 4.7 Only)

Enter in the Read Cache Size field the maximum number of records, up to 999, that can be stored in the cache before old entries must be removed. If no read cache size is specified, the value defaults to 100. The larger the value, the

Note: The Oracle I/O Off flag is valid only in Oracle environments

Note: The Disable Full OCI flag is active only in Oracle environments.

Note: The SQL Select Off flag is valid only in Oracle environments.

Runtime Administration, March 10, 2010 57© 2010 Datatel, Inc.

Page 58: Envision Runtime Administration

Setup: Defining System Parameters

better the caching performance. However, larger values take up more resources in each session, and more overhead is required to maintain the cache.

To disable read caching, enter 0 in the Read Cache Size field.

Read Cache Log State (Envision 4.7 Only)

The Read Cache Log State field gives you the option of tracking the performance of the Envision read cache by generating a record in the HOLD file.

Enter Yes or -1 to generate a record of the format userid.READ.CACHE, where userid is the login ID of a specific session.

Enter 1 to generate a record of the format userid.READ.CACHE.instance, where instance is a counter that is advanced each time the cache is cleared. This log contains information on each record read, not including records that are locked for update, along with statistics on the number of times the record was read from cache instead of the number of times it was read from disk. This setting is primarily intended for diagnostic purposes and is not recommended for general use.

Enter No—the default value—if you do not want to log read caching.

Clear Cache Off (Envision 4.7 Only)

The MIO read cache accelerates I/O by storing frequently accessed read-only data in a memory cache. The cache is cleared whenever the MIO process level is zero, for instance, when returning to the primary key prompt on a form, or around major record processing loops in batch processes. Enter Yes in the Clear Cache Off field to obtain additional acceleration by preventing the cache from clearing. The default for this field is “No”.

Note: When the cache is prevented from clearing, a desirable change made in one session may not benefit another session until the user logs out and logs in again. For this reason, we do not recommend using the Clear Cache Off option.

58 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 59: Envision Runtime Administration

In This Chapter

Execute Log On

All executions of shell commands from within Envision programs, such as record SELECTS, are performed through a central MIO routine, S_MIO_EXECUTE. Enter Yes in the Execute Log On field to enable the user to record a log of each unique operation. Records of the form userid.EXECUTE.LOG are maintained in the HOLD file, where userid is the user ID of the person running the process. The default for this field is “No”.

Numeric Precision

Enter in the Numeric Precision field the maximum number of decimal digits (significant digits) to be used in numeric value calculations against variables. For example, if you enter 4, then .9999 is not rounded; however, .99999 is rounded to 1.0.

Subscription Enabled

Enter Yes in the Subscription Enabled field to enable DMI transaction transmission. The default for this field is “No”.

For more information about CampusCruiser, see Using the CampusCruiser Interface.

Inbound EDX TX Enabled

Enter Yes to allow DMI_DISPATCH to accept EDX transactions from DMI. For example, enter Yes to use EDX to import grades into Colleague that were entered in e-learning software.

Note: The system default is 4; however, Envision overrides it with a default of 9 (the maximum supported). Datatel recommends keeping the Envision default of 9.

Note: Datatel recommends modifying this field only if specific application software requires it.

Runtime Administration, March 10, 2010 59© 2010 Datatel, Inc.

Page 60: Envision Runtime Administration

Setup: Defining System Parameters

If you enter “No”, then DMI_DISPATCH does not accept EDX transactions from DMI, and returns an error message.

Use Passive FTP

Enter No or leave this field blank if you do not want to use passive FTP. Not all FTP clients support passive FTP (standard Windows software does not yet support passive FTP).

Set this field to “Yes” if your institution needs passive FTP to successfully run ExpressLoad and other Envision processes that use FTP. Setting this field to Y forces Envision processes that perform FTP (such as ExpressLoad) to include the “passive” keyword in its script. This allows the client to initiate both the data port and command port connections to the server.

Windows Clients

The standard Windows FTP client does not support passive FTP. To make passive FTP fully functional with Windows, you must first install third-party FTP client software on your server.

If you use Windows, set this field to “Yes” only if both of the following are true:

You need passive FTP to run Envision FTP.

You have a Windows FTP client on your server that supports passive FTP.

Error Stamping

Enter Yes in the Error Stamping field if you want each program that references a specific error message to be logged within that error record. This can help track usage patterns for specific error messages. This field is normally set to “No” because the error file is a shared resource at runtime and is likely to be in an area of the system that is intended to be read-only.

Note: This field enables or disables EDX transmittals from all publishers. If you want to enable or disable transmittals from one publisher, use the settings in the publisher software.

60 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 61: Envision Runtime Administration

In This Chapter

MIO Level Check Disable

Error checking logic generated into all processes verifies that the MIO process level is the same coming out of a routine as it is going in. This helps to catch potential data corruption as early as possible.

It is possible, though rare, for a routine to produce a legitimate mismatch. If you have such a routine and want to avoid the forced logout that occurs on a mismatch, enter the names of the routines in the MIO Level Check Disable field.

UT Debug String

If you want to preload a value into the UT Debug String for every session, enter it in the UT Debug String field.

The debug string controls the turning on of debug code in various processes. Normally, no debug string is entered in the UT Debug String field on the EPED form; thus, the debug string is empty at the beginning of each session.

You can use the UT Process Debug Activation (UTDB) form to set the debug string manually for the current session only. If you enter a value in the UT Debug String field on the EPED form, however, it will be loaded in every session in the current account.

DMI Print Server IP/Port (Envision 4.7 Only)

Enter the IP address and port number for the Windows print server on which DMI is installed.

Note: The DMI Print Server IP/Port fields are used in Envision 4.7 only. In Release 18.0,you can set up a DMI listener with a print server role as described in Implementing Stylesheet Printing available on the Datatel Web site.

Runtime Administration, March 10, 2010 61© 2010 Datatel, Inc.

Page 62: Envision Runtime Administration

Setup: Defining System Parameters

62 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 63: Envision Runtime Administration

Setup

Defining Validation Codes

In This ChapterValidation codes are used in Envision to:

Limit the valid responses a user has for data entry

Make standard the values for certain data elements

Provide consistent values and descriptions of those values on forms and in reports

Allow for special processing for certain values of codes

Envision supports two types of validation codes:

Code files

Code tables

Code Files Code files are used when, in addition to the description of the code, you need to store more information. The first field in each record contains the description of the code. The remaining fields in a record can be used to store any information pertinent to the code.

For example, the file DORMS contains records keyed by a code, one code for each dormitory. The first field in each record is the name of the dormitory corresponding to the coded key. Other pertinent information stored in a DORMS record might be total capacity and whether the dorm is co-ed. A code file is specific to an Envision-based application and, therefore, would have a separate form process within the application to maintain the records in the code file.

Runtime Administration, March 10, 2010 63© 2010 Datatel, Inc.

Page 64: Envision Runtime Administration

Setup: Defining Validation Codes

Code TablesCode tables, on the other hand, are stored in the application file appl.VALCODES, where appl is the mnemonic for the application. Validation code tables are maintained, regardless of the application, through the Validation Code Maintenance (VAL) form. Each table can contain any number of codes, which are stored in a multi-valued list. Each code has associated with it four parameters:

The description of the code

The minimum character string needed to identify the code

Two special processing parameters

With each application, Datatel delivers the validation tables required for that application. In some cases, these tables cannot be modified by the user. Usually, the tables, which you should not modify, have special processing codes for certain code values. Processes within the application are dependent on these processing codes and the tables are therefore defined by Datatel. Most validation code tables, however, require custom values specific for each customer. These tables require no special processing or special instructions on how to fill in the special processing fields are included with the load instructions for the application.

Tables defined and maintained by Datatel are restored each time a release is installed. Tables that you define and maintain are not overwritten by the release installation. If a given validation table or valcode table is missing for an application, the release installation process will provide the default table. Valcode tables are stored in the application file VALCODES and are subject to tree reads.

Maintaining VAL Codes

To define validation codes for an application, run the VAL form.

Enter the code in the first field in each window group along with its description and minimum entry string. The minimum entry string is the fewest number of characters the user must enter in order for Envision Runtime to recognize that string as a code. For example, if you have four codes defined in your table (NORTH, SOUTH, EAST and WEST), the minimum entry strings might be N, S, E, and W. Each code can have one minimum entry string, and each minimum entry string must be unique. Unless you have specific instructions telling you how to fill in the special processing fields, leave these two window elements blank.

64 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 65: Envision Runtime Administration

Code Tables

Next enter the maximum code size. This determines how many characters a user can enter when a data element on a form uses this validation code table. The user can enter fewer characters but cannot enter more characters than the maximum.

The zero fill flag determines if numeric codes in this table are front padded with zeroes. The advantage of zero filling is that all numeric codes are the same length, the maximum code length. If you wish to zero fill numeric codes in this table, be sure to specify the zeroes in the maximum code length.

Disabling Valcode Tables

To disable a validation table, enter an asterisk (*) as the first code and delete the rest of the fields and codes from the table. When Envision Runtime encounters a table with just an asterisk, users can enter anything for the value of the data element that uses the table.

Note: The maximum code length must be as long as the longest code defined in the table. For example, if a code in the table is NORTH and the maximum code length is 3, the user will not be able to enter that code since it is 5 characters. The maximum code length is usually used in conjunction with the zero fill numbers flag.

Runtime Administration, March 10, 2010 65© 2010 Datatel, Inc.

Page 66: Envision Runtime Administration

Setup: Defining Validation Codes

66 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 67: Envision Runtime Administration

Setup

Editing UNIX_CONTROL Records

In This ChapterThis chapter describes how to modify your UNIX_CONTROL record in the SYSDEFS file. To do this, use the UNIX_CONTROL Record Editing (UCRE) form. The UCRE form eliminates the need to update the UNIX_CONTROL record from the command line.

Table 1 lists the topics covered in this chapter.

Form UsedTable 2 lists and describes the form used in this chapter.

Table 1: Topics in This Chapter

Topic Page

Form Used 67

Editing a UNIX_CONTROL Record 68

Procedure for Editing a UNIX_CONTROL Record 73

Table 2: Form Used in This Chapter

Form Purpose

UNIX_CONTROL Record Editing (UCRE)

View or update a UNIX_CONTROL record in the SYSDEFS file.

Runtime Administration, March 10, 2010 67© 2010 Datatel, Inc.

Page 68: Envision Runtime Administration

Setup: Editing UNIX_CONTROL Records

Editing a UNIX_CONTROL RecordUse the UNIX_CONTROL Record Editing (UCRE) form to view or update your UNIX_CONTROL record in the SYSDEFS file. The UCRE process detects what operating system you have, and then displays the values from the appropriate template for the UNIX_CONTROL record for your reference.

The available templates are:

UNIX_CONTROL_AIX

UNIX_CONTROL_HP

UNIX_CONTROL_SUN

UNIX_CONTROL_LINUX

Although the UNIX_CONTROL record has 25 fields, only six of those fields may need custom modification. This form gives you access to these six fields.

If you modify the UNIX_CONTROL record, you must log out of Colleague for the changes to take effect.

Note: If you are on a Windows server, you cannot access this form. If your server's operating system is not AIX, HP, SUN, or LINUX, you will see a message that no template was found, and the template values for the UNIX_CONTROL record will be blank.

68 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 69: Envision Runtime Administration

Editing a UNIX_CONTROL Record

Figure 4: UNIX_CONTROL Record Editing (UCRE) Form

Runtime Administration, March 10, 2010 69© 2010 Datatel, Inc.

Page 70: Envision Runtime Administration

Setup: Editing UNIX_CONTROL Records

Noteworthy Fields on the UCRE Form

The fields described in this section are important for viewing or updating a UNIX_CONTROL record.

NOMESSAGE Option

If you want to suppress confirmation messages, this field allows you to enable Envision print routines to add the NOMESSAGE option to SETPTR commands. Enter Yes if you want the system to issue confirmation messages when output is sent to the printer; otherwise, enter No.

Entering “Yes” assigns a value of 1 to field 20 in the UNIX_CONTROL record; entering “No” assigns a value of 0.

Template Value for NOMESSAGE Option

This field displays the template value for your UNIX_CONTROL record.

Host Type

This field allows you to view or update the value for the host type (suffix) of the source template record for the UNIX_CONTROL record. For example, if the source for the UNIX_CONTROL record is the UNIX_CONTROL_HP template record, this field would contain the string “HP”. This field is used for documentation purposes only.

This field references field 13 in the UNIX_CONTROL record.

Template Value for Host Type

This field displays the template value for your UNIX_CONTROL record.

70 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 71: Envision Runtime Administration

Editing a UNIX_CONTROL Record

Printer Subroutine

This field allows you to view or update the name of the printer subroutine that identifies a routine to extract printer and form information. This name will usually be similar to the following: S_platform _PRINT_INFO where platform describes the type of UNIX (for example, LINUX or AIX).

The name of the subroutine you enter will be validated. You can use LookUp to view a list of available subroutines.

This field references field 6 in the UNIX_CONTROL record.

Template Value for Printer Subroutine

This field displays the template value for your UNIX_CONTROL record.

Batch Subroutine

This field allows you to view or update the name of the batch subroutine that identifies a routine to submit a job to a batch queue for later execution. Currently, a job name, start time, queue name, and priority are used.

In addition to several platform-specific versions, there is also a generic UNIX version, and a version that supports third-party QBATCH.

The name of the subroutine you enter will be validated. You can use LookUp to view a list of available subroutines.

This field references field 7 in the UNIX_CONTROL record.

Template Value for Batch Subroutine

This field displays the template value for your UNIX_CONTROL record.

Note: If you are using QPRINT/USAM, then you need to enter S_QPRINT_PRINT_INFO or S_USAM_PRINT_INFO. The routine must return two arguments in the calling list: – The list of valid printers. – The list of valid forms.

Runtime Administration, March 10, 2010 71© 2010 Datatel, Inc.

Page 72: Envision Runtime Administration

Setup: Editing UNIX_CONTROL Records

Command for Defining Terminal Characteristics

This field allows you to view or update the UniData command needed to set the terminal characteristics before entering the Envision environment. This command must set to half-duplex mode at a minimum, and remap or turn off the erase and kill commands.

This field references field 4 in the UNIX_CONTROL record.

Template Value for Terminal Characteristics Cmd

This field displays the template value for your UNIX_CONTROL record.

Command for Retrieving Phantom Processes

This field allows you to view or update the UNIX command string that will be executed in a UniBasic program. The command returns a sorted, trimmed string of UNIX process IDs (PIDs) — one for each instance of UniData that is running a phantom process.

A typical definition for a System V implementation of UNIX is:

ps -aef | fgrep PHANTOM | fgrep -v fgrep | tr -s ' ' '\011' | cut -f3 | sort

This is similar to the command string for UNIX.GET.UDT.PROCESSES, except that the search finds the keyword PHANTOM, instead of UDT. This relies on the fact that UniData distinguishes phantom processes from interactive processes by using a command line argument of PHANTOM when starting the udt process.

A typical definition for a BSD implementation of UNIX is:

ps -aux | fgrep PHANTOM | fgrep -v fgrep | tr -s ' ' '\011' | cut -f2 | sort

This references field 10 in UNIX_CONTROL.

Template Value for Phantom Processes Command

This field displays the template value for your UNIX_CONTROL record.

72 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 73: Envision Runtime Administration

Editing a UNIX_CONTROL Record

Procedure for Editing a UNIX_CONTROL Record

Step 1. From the Envision Runtime (UT) application, access the UNIX_CONTROL Record Editing (UCRE) form.

Step 2. View or update the UNIX_CONTROL record. Refer to online help for more information.

Step 3. Save and exit from the UCRE form.

Runtime Administration, March 10, 2010 73© 2010 Datatel, Inc.

Page 74: Envision Runtime Administration

Setup: Editing UNIX_CONTROL Records

74 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 75: Envision Runtime Administration

Setup

Printing

Understanding Levels of PrintingThere are three levels of printing to understand in order to print your output in your application software. The levels are:

Operating System

Database Management System Software

Application Software

Operating System

Refer to your operating system documentation for information about configuring the printing on your operating system.

See the following sections, “Database Management System Software” immediately below, and “Application Software” on page 76 for additional information. See your operating system documentation for information on the lpr command and printer definitions.

Database Management System Software

LPTR

The LPTR keyword appended to the end of a query language sentence sends a query report to the printer. In UNIX the report will print at the default printer lp0.

Runtime Administration, March 10, 2010 75© 2010 Datatel, Inc.

Page 76: Envision Runtime Administration

Setup: Printing

SETPTR

You can change the destination of the printer by issuing a SETPTR command. The SETPTR command allows you to define the characteristics of your print job. For example, you can specify the number of copies to print, the banner page, page lengths, but most importantly the printer destination.

The SETPTR option that allows you to change the printer destination is the FORM option. The syntax of the command is:

:SETPTR ,,,,,,FORM formname

In UniData, formname is synonymous with the printer name in the printcap file. All reports with formname will print at the printer with the corresponding name.

We recommend that you enter the SETPTR command in the LOGIN paragraphs of your user remote accounts to direct output from the query language to the desired printer. Otherwise all output will be queued without a printer destination and will go the system printer.

Application Software

Change Peripheral Defaults Form

Envision-based software uses the Change Peripheral Defaults form to direct its output. It allows the user to change the form name. In addition, the user can change the number of copies, the margins, add a defer time, and designate a mode. Typically, the user accepts the options and chooses to change the form name and mode. The mode determines if the output is sent to the printer, terminal or tape.

A default form name displays on the form and the user can accept it or change it. If you change the defaults, the defaults return the next time the report is run.

Note: A SETPTR command remains in effect until another SETPTR command is run, or until a user logs off the system, or until a user ends the current UniData session.

76 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 77: Envision Runtime Administration

Understanding Levels of Printing

The defaults that display on the Change Peripheral Defaults form can be changed permanently through the Peripheral Default (PDEF) form in Runtime. Usually, the user changes just the default form name. The other characteristics such as page widths and lengths should not be changed.

Figure 5: Example Peripheral Default Form (PDEF) Form

Runtime Administration, March 10, 2010 77© 2010 Datatel, Inc.

Page 78: Envision Runtime Administration

Setup: Printing

Defining Printers to Envision for Windows NT and Windows 2003/2008

The procedure for defining a printer to Envision in Windows NT or Windows 2003/2008 is different from the procedure for UNIX. To identify the printer handling routine to be used, add the printer routine name to the first field of the OS_CONTROL record in the SYSDEFS file.

There are two options for printing routines, depending on how printers are defined in Windows NT or Windows 2003/2008.

If all printers are defined on the same local server as Colleague, see “For All Printers Defined On The Same Local Server as Colleague” immediately below.

If you are using a network print server, see “For a Network Print Server” beginning on page 79.

For All Printers Defined On The Same Local Server as Colleague

If all printers are defined on the same local server as Colleague, place S_NT_PRINT_INFO in field 1 of the OS_CONTROL record in the SYSDEFS file, as shown below:

AE SYSDEFS OS_CONTROL 1: S_NT_PRINT_INFO

This routine reads the Registry on the Windows NT or Windows 2000/2003 server and recognizes any printers that have been defined to the server.

Note: You must exit the account completely and log back into it in order to reset common with the new print routine.

78 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 79: Envision Runtime Administration

Defining Printers to Envision for Windows NT and Windows 2003/2008

For a Network Print Server

If you are using a network print server, you must place S_VALCODES_PRINT_INFO in field 1 of the OS_CONTROL record in the SYSDEFS file, as shown below:

AE SYSDEFS OS_CONTROL 1: S_VALCODES_PRINT_INFO

This routine uses a UT.VALCODES table called VALID.PRINTERS to determine the valid system printers.

The VALID.PRINTERS table is not delivered with the software, and must be added. You can specify printers in the valcode table using the UNC format (\\servername\printername) in order to make any printer on the network accessible. Printers defined to Envision using UNC need not be defined to the local NT server.

When using the S_VALCODES_PRINT_INFO routine as the printer control program, you must take great care in the construction of the entries in the VALID.PRINTERS valcode file in UT. You will probably want to put a familiar printer name in the code field on the VAL form, and then put the real path to the printer in the Special Processing 1 field. To accomplish this when the S_VALCODES_PRINT_INFO routine is being used, enter information on the VAL form in the VALID.PRINTERS valcode table as in Figure 6 on page 80. In the example, the familiar printer name is hpfirst, and its UNC path is \\pdc\hpfirst.

Runtime Administration, March 10, 2010 79© 2010 Datatel, Inc.

Page 80: Envision Runtime Administration

Setup: Printing

Figure 6: Defining a Printer in the VALID.PRINTERS Valcode Table

Complete the entry in the VALID.PRINTERS table as follows:

Enter the familiar name of the printer in the Code field.

Enter optional descriptive information in the Description field.

Enter the familiar name of the printer in the Min Entry field, exactly you entered it in the Code field.

Enter the UNC path to the printer in the Special Processing field.

Make certain that the contents of the Code field and the Min Entry field are identical in order to ensure that the print routines that handle printer validation (I_PRINTERS_CONVERT in UT.INSERTS) will use the information you have entered in the Special Processing field. If the Code field and the Min Entry field do not match exactly, the value from the Min Entry field is used in any SETPTR command and on the printer selection screen presented during batch processing. This can result in an error message if the value in the Code field is entered in a peripheral selection screen when the value in the Min Entry field does not match it.

Note: For the settings in the VALID.PRINTERS valcode table to take effect, you must exit and re-access the UniData account. In addition, you must exit and re-access the account in order to reset common with the new print routine when the OS_CONTROL record has been updated.

80 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 81: Envision Runtime Administration

Defining Printers to Envision for Windows NT and Windows 2003/2008

For more information about the S_VALCODES_PRINT_INFO routine, see AnswerNet pages 196.848 and 215.1569. Refer to AnswerNet page 733 for a technical over view of EasySpooler.

Runtime Administration, March 10, 2010 81© 2010 Datatel, Inc.

Page 82: Envision Runtime Administration

Setup: Printing

82 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 83: Envision Runtime Administration

Setup

Using the Envision Process Handler

What is the Envision Process Handler?The Envision Process Handler resides in the UT module and provides the means for storing, maintaining, scheduling, and running processes that have been selected to run in background mode. Stored sentences and paragraphs can also be run as background tasks. It is available with Colleague Release 17 or higher. The Process Handler menu is shown in Figure 7.

Figure 7: Envision Process Handler Menu

Runtime Administration, March 10, 2010 83© 2010 Datatel, Inc.

Page 84: Envision Runtime Administration

Setup: Using the Envision Process Handler

Submitting a Task to the Envision Process Handler

Users can submit tasks—including batch processes, reports and VOC paragraphs—to the Envision Process Handler for background processing.

Submitting a Batch Process or Report

When a user submits a batch process or report to Envision, the Process Submission form is displayed, as shown in Figure 8. This form allows the user to specify whether the task should run in background mode and, if so, whether it should run immediately or be submitted to the Envision Process Handler.

Figure 8: Example Process Submission Form

84 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 85: Envision Runtime Administration

Submitting a Task to the Envision Process Handler

Step 1. If the user enters “Yes” in the Execute in Background Mode field, the task will run in background mode. The Background Execution Type field is enabled for input.

Step 2. In the Background Execution Type field:

If the user selects I(mmediate Execution), the task runs immediately.

If the user selects E(nvision Process Handler), the task is submitted to the Envision Process Handler.

Step 3. When the Envision Process Handler is selected, the user can specify the date and time of the first run and schedule subsequent runs, if any, for the task, including a date to stop automatic scheduling.

Note: Although PSFP is displayed at the top of the form, this is the same form that will appear after any Envision form that runs a procedure which allows execution in phantom mode. Note that it “inherits” the mnemonic from its calling procedure.

Runtime Administration, March 10, 2010 85© 2010 Datatel, Inc.

Page 86: Envision Runtime Administration

Setup: Using the Envision Process Handler

Submitting a VOC Paragraph

The Custom Paragraph Entry (CPAE) form, shown in Figure 9, enables users to submit a custom paragraph to the Process Handler.

Figure 9: Custom Paragraph Entry (CPAE) Form

Step 1. Enter the names of one or more custom paragraphs in the Process Paragraph Names fields.

Step 2. Select a Process Handler queue for each paragraph in the Queue field. If no queue is specified, the DEFAULT queue is automatically selected.

Note: For information about defining Process Handler queues, see “The Process Handler Setup (PHSU) Form” beginning on page 89.

86 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 87: Envision Runtime Administration

Submitting a Task to the Envision Process Handler

Step 3. The remaining fields allow you to specify the date that the process should be run next and to schedule subsequent runs, if any, for the task, including a date to stop automatic scheduling.

Viewing and Editing Task Schedules

Access the My Processes (MYPR) maintenance form to view and schedule all processes submitted under the currently logged in user ID. For more information, see “The My Processes (MYPR) Form” beginning on page 102.

The System Administrator’s Role

As System Administrator, you can manage queues and tasks in the Process Handler as follows:

Define processing queues.

Assign specific security classes, security class characteristics, and/or user IDs to queues.

Specify how many tasks are allowed to run concurrently on a queue.

Start, stop, suspend, and reset processing queues.

Generate reports of completed processes from the Process Status file.

Purge records from the Process Status file.

Modify the queue assignment and scheduling of any task that has been submitted to the Process Handler.

Note: Datatel recommends that only the System Administrator have the necessary permissions to maintain the Process Handler. Typically, end users have access only to the Custom Paragraph Entry (CPAE) form, shown in Figure 9 on page 86, and the My Processes (MYPR) form, shown in Figure 19 on page 103. You may also want to allow end users access to the Process Handler inquiry forms (see “Using Inquiry Forms” beginning on page 110).

Runtime Administration, March 10, 2010 87© 2010 Datatel, Inc.

Page 88: Envision Runtime Administration

Setup: Using the Envision Process Handler

Setting Up the Process Handler and Managing Queues

Three forms enable you to set up and manipulate Process Handler queues:

Use the Process Handler Setup (PHSU) maintenance form, described in “The Process Handler Setup (PHSU) Form” beginning on page 89, to identify the available process queues and to assign security classes, security class characteristics, and/or user IDs to specific queues.

Use the Process Queue Management (PRQM) processing form, described in “The Process Queue Management (PRQM) Form” beginning on page 91, to start and stop Process Handler queues either globally or individually, to set the maximum number of concurrent tasks per queue either globally or individually, and to schedule times when specific running queues are to be suspended.

Use the Reset Process Queue Handler (RSPH) processing form, described in “The Reset Process Queue Handler (RSPH) Form” beginning on page 94, to stop all running queues and reset the Process Handler.

Note: When a queue is stopped, all currently processing tasks continue to run to completion. No new tasks are started.

88 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 89: Envision Runtime Administration

Setting Up the Process Handler and Managing Queues

The Process Handler Setup (PHSU) Form

The Process Handler Setup (PHSU) maintenance form, shown in Figure 10, is used to identify the available process queues and to assign security classes, security class characteristics, and user IDs to specific queues.

Figure 10: Example Process Handler Setup (PHSU) Form

The Processing Queue Names fields display the available queues. You can add or edit queue names in these fields.

Step 1. Whenever a task is submitted to the Envision Process Handler, it is assigned to a queue. If you do not specify a queue for a task, the Process Handler automatically selects the DEFAULT queue.

Step 2. To assign a security class or security class characteristic to a specific queue, enter the name of the security class or characteristic in the Security Class Queues Class field.

Runtime Administration, March 10, 2010 89© 2010 Datatel, Inc.

Page 90: Envision Runtime Administration

Setup: Using the Envision Process Handler

Step 3. In the Security Class Queues Queue field, enter one of the queue names shown in the Processing Queue Names fields. The Security class Queues Queue field is validated against the list of available queues in the Processing Queue Names fields.

Whenever you submit a Batch or Report to the Process Handler, the task is associated to the queue that corresponds to the security class associated with the user ID. If there is more than one security class associated with the user ID, the first one is used to assign the queue.

Step 4. To assign a user ID directly to a specific queue regardless of the user’s associated security classes, enter the user ID in the User Specific Queues User ID field. In the User Specific Queues Queue field, enter one of the queue names shown in the Processing Queue Names fields. The Queue field is validated against the list of available queues in the Processing Queue Names fields.

Whenever this user submits a Batch or Report to the Process Handler, the task is associated to the assigned queue for the user ID without regard to security classes.

Note: Queue assignment by security class is overridden by the direct assignment of a queue to a specific user ID in the User Specific Queues User ID and Queue fields.

90 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 91: Envision Runtime Administration

Setting Up the Process Handler and Managing Queues

The Process Queue Management (PRQM) Form

Use the Process Queue Management (PRQM) processing form, shown in Figure 11 on page 92, to start and stop Process Handler queues. Each process queue runs tasks in the order in which they appear in the Outstanding Process listing (see “The Outstanding Processes (OPRM) Form” beginning on page 95). The queue accepts tasks up to the Maximum Processes per queue, and then waits until one of the tasks is completed before starting a new task.

If you enter stop dates and times, the Process Handler will stop submitting tasks to the queue at that time. You can also specify suspend start and end times if you want the Process Handler to stop submitting tasks between certain times.

Process Handler processing is executed in the background. If for any reason it fails to execute or is prematurely aborted, you must use the Reset Process Handler (RSPH) process to reinitialize the records used in processing.

The header of the PRQM form displays the following two fields:

Process Handler COMO ID. The COMO ID associated with the Process Handler.

PID. The operating system process ID for the Process Handler.

If the Process Handler is unexpectedly stopped, the queue statuses stored in Envision may be out of sync. This means that they may show as “Running” when they are no longer active.

The Process Handler COMO ID is displayed so that its record in the _PH_ directory file can be analyzed, if needed. Also, the PID is displayed that originally created the COMO file. See AnswerNet Support Solution page 6154 for information on troubleshooting with COMO files.

When starting any inactive queues on this form, the PRQM process will populate the Expired Scheduled Processes window with any processes that are beyond their stop (expire) date, but which were never invoked due to an inactive queue. You must enter an action for the Process Handler to take for each expired scheduled process.

Note: Because only one instance of the Process Handler processor can run at a time, until you reset the Process Handler by using the RSPH form, the system regards the Process Handler as still running and will not allow you to restart it.

Runtime Administration, March 10, 2010 91© 2010 Datatel, Inc.

Page 92: Envision Runtime Administration

Setup: Using the Envision Process Handler

Figure 11: Example Process Queue Management (PRQM) Form

Step 1. To specify global settings that apply to all queues, complete the fields in the upper portion of the PRQM form.

Enter the date and time to start all queues in the Start All Queues on [date] at [time] fields.

Enter the maximum number of concurrent tasks for all queues in the Max for All Queues field. This maximum is enforced on each queue.

Note: When data is entered in the global fields, it automatically populates the Start Date/time, Stop Date/time, and Maximum Processes fields for all the queues in the lower portion of the PRQM form,

92 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 93: Envision Runtime Administration

Setting Up the Process Handler and Managing Queues

Step 2. To specify settings for an individual queue, complete the fields for that queue in the lower portion of the PRQM form.

Enter the date and time to start the queue in the Start Date/time fields.

Enter the date and time to stop the queue in the Stop Date/time fields.

To have the processor stop submitting tasks to the queue for a specified period of time, enter values in the Suspend Start and Suspend End Time fields.

Enter the maximum number of concurrent tasks for the queue in the Maximum Processes field.

Step 3. The Process Paragraph Name field displays the names of scheduled processes that have expired. These are processes with a stop date that has expired, but which were never started due to an inactive queue.

In the Action field, select an action to perform on the expired process. The following actions are available:

Run One Last Time. Use this action to run the expired process one last time.

Cancel. Use this action to cancel the expired process.

Note: You cannot set suspend start and suspend end times globally. They must be set for individual queues.

Note: If no number is entered in the Maximum Processes field for a queue, the default maximum is 1. This means that the queue waits for each task to be completed before accepting another task.

Runtime Administration, March 10, 2010 93© 2010 Datatel, Inc.

Page 94: Envision Runtime Administration

Setup: Using the Envision Process Handler

The Reset Process Queue Handler (RSPH) Form

If the Process Handler does not run or prematurely terminates, use the Reset Process Handler (RSPH) form to re-initialize the records. Only one instance of the Process Handler can run at a time. Until the Process Handler is reset, the system does not allow you to restart it.

Use the Reset Process Queue Handler (RSPH) processing form, shown in Figure 12, to stop all queue processing and to reset the Process Handler.

Figure 12: Example Reset Process Handler (RSPH) Form

The active queues and running tasks are displayed in informational fields.

Enter Yes in the Do you want to reset all Processing Queues field to reset the Process Handler.

Enter No or leave the field blank if you do not want to reset the Process Handler.

All tasks that are currently running will continue to completion, no new tasks are started, and the Process Handler is reset.

Note: If you want to view the same data that is shown on the RSPH form without the option of resetting the Process Handler, use the Running Processes (RPRI) inquiry form. For more information about inquiry forms, see “Using Inquiry Forms” beginning on page 110.

94 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 95: Envision Runtime Administration

Managing Processes

Managing ProcessesThree forms allow you to schedule tasks:

The Outstanding Processes (OPRM) maintenance form, described in “The Outstanding Processes (OPRM) Form” beginning on page 95

The My Processes (MYPR) maintenance form, described in “The My Processes (MYPR) Form” beginning on page 102

The Process Scheduling (PRSC) maintenance form, described in “The Process Scheduling (PRSC) Form” beginning on page 100

The Outstanding Processes (OPRM) Form

The Outstanding Processes (OPRM) maintenance form, shown in Figure 13, enables you to manipulate queues and reorder tasks within queues. You can also edit individual process schedules by detailing from the OPRM form to the Process Scheduling (PHTS) form, as shown in Figure 14 on page 97.

Figure 13: Example Outstanding Processes (OPRM) Form

Runtime Administration, March 10, 2010 95© 2010 Datatel, Inc.

Page 96: Envision Runtime Administration

Setup: Using the Envision Process Handler

The Process Paragraph Name, Sched, Submit Date and Submit Time fields are informational, and cannot be edited on the OPRM form. You must detail to the Process Scheduling (PHTS) form to edit individual process schedules.

The processes run in the order shown on the list, subject to eligibility conditions. If a task is ineligible to run for any reason, the Process Handler moves to the next task. In order for a task to be eligible to run, the following conditions must be met:

Step 1. The specified queue must be running.

Step 2. The specified queue must contain fewer than the maximum allowed number of concurrent processes.

Step 3. The current date and time must be later than or equal to the next run scheduled date and time.

Use the Move Process From Position/to Position fields to reorder the processes in the list. You can change the queue assignment of a process by selecting the desired queue in the Queue field.

Note: A process that runs repeatedly is termed scheduled, and Yes is displayed in the Sched field for the process on the OPRM form. A once-only process is termed unscheduled, and No is displayed in the Sched field for the process on the OPRM form.

Note: To view the data that is displayed on the OPRM form without the option of editing it, use the Outstanding Processes (OPRI) inquiry form. For more information about inquiry forms, see “Using Inquiry Forms” beginning on page 110.

96 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 97: Envision Runtime Administration

Managing Processes

To edit the scheduling of a task shown on the OPRM form, detail from the selected task to the Process Scheduling (PHTS) form, as shown in Figure 14.

Figure 14: Outstanding Processes (OPRM) Form Detailed to Process Scheduling (PHTS) Form

Runtime Administration, March 10, 2010 97© 2010 Datatel, Inc.

Page 98: Envision Runtime Administration

Setup: Using the Envision Process Handler

The Process Scheduling (PHTS) Form

You can detail to the Process Scheduling (PHTS) form, as shown in Figure 15, from the Outstanding Processes (OPRM) form, the My Processes (MYPR) form, or the Process Scheduling (PRSC) form.

Figure 15: Example Process Scheduling (PHTS) Form

Step 1. Use the Schedule Process to Run Next on fields to set the date and time you want a task to run.

If the task is to run only once, you can leave the remaining fields blank. A once-only process is termed unscheduled, and “No” is displayed in the Sched field for the process on the OPRM form.

98 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 99: Envision Runtime Administration

Managing Processes

Step 2. To schedule repeated runs, complete the remaining fields as follows:

Schedule Process to Run Every/From. This field has three parts: • In the first field, enter the interval. This number is used with the second

field, frequency. For example, to have a process repeat bi-weekly, enter 2 in this field, and then select Week in the second field.

• In the second field, enter a frequency. The process will be scheduled to run at specific intervals for specific seconds, minutes, hours, days, weeks, or months.

• In the third field, enter the next scheduled occurrence of this job. Use this field only if the frequency is set to Second, Minute, or Hour. This field determines whether the interval and frequency (such as 30 seconds, or 8 minutes, or 5 hours) is added to the start time/date or from the end time/date of the previous run.

Enter Yes in the Schedule Process on Weekdays Only field to restrict the runs to weekdays, or enter No to allow runs on Saturdays and Sundays.

Enter a time, using military (24-hour) format, or A and P to specify AM and PM, for the runs to begin. Use this field only if the frequency is set to Second, Minute, or Hour.

If you want scheduling to end on a specific date, enter the date in the Stop Automatically Scheduling Process on field.

A process that runs repeatedly is termed scheduled, and “Yes” is displayed in the Sched field for the process on the OPRM form. The Process Paragraph displays the generated paragraph saved in VOC that was created by the original run of the process. This paragraph will be rerun according to the schedule you enter. It is not editable.

If you plan to schedule jobs through the Process Handler to repeat continuously, such as every x number of seconds after the end of the previous job, the process handler queues that may be used for those jobs should be set up on the Process Queue Management (PRQM) form with the Maximum Processes column set to a value greater than 1. This is needed because you don't want the continuously repeating job to tie up the entire queue, preventing any other repeat jobs from getting invoked through that queue.

If the Process Handler stops abruptly or prematurely, such as by the Listener getting stopped and restarted or the database getting stopped and restarted, then the Process Handler will have to be reset on the Reset Process Queue

Technical Tip: To immediately restart a scheduled job, enter 10 as the interval, the frequency as Seconds, and then set the job to start after the previous run has ended.

Runtime Administration, March 10, 2010 99© 2010 Datatel, Inc.

Page 100: Envision Runtime Administration

Setup: Using the Envision Process Handler

Handler (RSPH) form and restarted on the PRQM form. And you will again have to make sure to set the Maximum Processes column to a value greater than 1.

The Process Scheduling (PRSC) Form

The Process Scheduling (PRSC) maintenance form, shown in Figure 16, displays only scheduled processes, such as processes that are set to run more than once.

Figure 16: Example Process Scheduling (PRSC) Form

The Date, Time, Int, Frequency and Weekday fields are informational, and cannot be edited on the PRSC form. You must detail to the Process Scheduling (PHTS) form to edit individual process schedules.

100 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 101: Envision Runtime Administration

Managing Processes

To edit the scheduling of a task shown on the PRSC form, detail from the selected task to the Process Scheduling (PHTS) form, as shown in Figure 17.

Figure 17: Process Scheduling (PRSC) Form Detailed to Process Scheduling (PHTS) Form

For information about using the PHTS form to edit a process schedule, see “The Process Scheduling (PHTS) Form” beginning on page 98.

Runtime Administration, March 10, 2010 101© 2010 Datatel, Inc.

Page 102: Envision Runtime Administration

Setup: Using the Envision Process Handler

The My Processes (MYPR) Form

The My Processes (MYPR) maintenance form, as shown in Figure 18, is typically available to end users, allowing them to view and schedule the processes that they have submitted under the currently logged in user ID. To edit a process schedule, detail to the Process Scheduling (PHTS) form, as shown in Figure 19 on page 103.

Figure 18: Example My Processes (MYPR) Form

All processes for the user ID, both scheduled and unscheduled, are shown on the MYPR form. When an unscheduled process runs to completion, its entry is removed from the MYPR form. See the note on page 96 for the definitions of scheduled and unscheduled processes.

The fields on the MYPR form are informational, and cannot be edited. To edit individual process schedules, you must detail from the Mnemonic field to the Process Scheduling (PHTS) form.

102 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 103: Envision Runtime Administration

Managing Processes

To edit the scheduling of a task shown on the MYPR form, detail from the selected task to the Process Scheduling (PHTS) form, as shown in Figure 19.

Figure 19: My Processes (MYPR) Form Detailed to Process Scheduling (PHTS) Form

For information about using the PHTS form to edit a process schedule, see “The Process Scheduling (PHTS) Form” beginning on page 98.

Runtime Administration, March 10, 2010 103© 2010 Datatel, Inc.

Page 104: Envision Runtime Administration

Setup: Using the Envision Process Handler

Working with Process Status File Records

Two forms enable you to work with the records in the Process Status file:

Use the Process Status Report (PSTR) reporting form, described in “The Process Status Report (PSTR) Form” beginning on page 105, to generate a report showing completed processes.

Use the Process Status File Purge (PSFP) processing form, described in “The Process Status File Purge (PSFP) Form” beginning on page 108, to purge records from the Process Status file.

104 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 105: Envision Runtime Administration

Working with Process Status File Records

The Process Status Report (PSTR) Form

The Process Status Report (PSTR) reporting form, shown in Figure 20, enables you to generate a report from the Process Status file listing all processes completed through the Envision Process Handler. Selection criteria may be limited by start date, end date, User ID, mnemonic, and any additional criteria you select.

This form also allows you to generate a report for just the most recent runs of all processes scheduled for the Envision Process Handler. When you choose this option, the start and end date fields are inquiry only.

Figure 20: Process Status Report (PSTR) Form

Runtime Administration, March 10, 2010 105© 2010 Datatel, Inc.

Page 106: Envision Runtime Administration

Setup: Using the Envision Process Handler

Step 1. In the Start Date field, enter the start date for selecting processes.

Processes are shown on this report only if they began on or after this start date. However, a process may have been run one time, or may have been repeated through the Envision Process Handler. If a process had repeated runs, this report will show only those instances that began on or after this start date.

Step 2. In the End Date field, enter an end date for selecting processes.

Processes are shown on this report only if they completed before or on this end date. However, a process may have been run one time, or may have been repeated through the Envision Process Handler. If a process had repeated runs, this report will show only those instances that completed before or on this end date.

Step 3. In the User IDs field, enter User IDs for selecting processes. The User IDs you enter will limit selection to only those processes that were submitted by these User IDs.

Step 4. In the Mnemonics field, enter the mnemonics for selecting processes. The mnemonics you enter will limit selection to only those processes that were executed from these mnemonics.

Step 5. In the Report Only Most Recent Run field, enter Yes to report only the most recent run of repeat processes.

Note: This field is a display only field if you set the Report Only Most Recent Run field to "Yes."

Note: This field is a display only field if you set the Report Only Most Recent Run field to "Yes."

Note: If the Start Date field is left blank, all records in the Process Status file with start dates up to the date specified in the End Date field are included in the report, subject to your selection criteria. If the End Date field is left blank, all records in the Process Status file with start dates on or after the date specified in the Start Date field are included in the report, subject to selection criteria. If both fields are left blank, all records in the Process Status file are included in the report, subject to your selection criteria.

106 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 107: Envision Runtime Administration

Working with Process Status File Records

A process may have been run one time, or may have been repeated through the Envision Process Handler. If a process had repeated runs and this field is set to “Yes,” this report will show only the most recent run of each process. Processes that were run only once will also be displayed on the report, provided they satisfy any criteria based on User ID, mnemonic, and additional selection criteria. If you enter “Yes” in this field, the Start Date and End Date fields will be inquiry only.

Step 6. Do you want to limit the selection of processes by specifying additional selection criteria?

Yes. Enter Yes in the Additional Selection Criteria field. The Additional Selection Criteria form is displayed, as shown in Figure 21. Use the Add’l Connective, Field Name, Relation and Parameter/Value fields to select additional criteria.

No. Enter No in the Additional Selection Criteria field. The Additional Selection Criteria form is not displayed, and all records in the specified date range are included in the report.

Figure 21: Process Status Report (PSTR) Addl Selection Criteria Form

Runtime Administration, March 10, 2010 107© 2010 Datatel, Inc.

Page 108: Envision Runtime Administration

Setup: Using the Envision Process Handler

Step 7. Update to the Process Submission form, as shown in Figure 8 on page 84, and specify how you want the report to be printed or displayed.

The Process Status File Purge (PSFP) Form

The Process Status File Purge (PSFP) processing form, shown in Figure 22, enables you to purge selected records from the PHANTOM.STATUS and PHANTOM.STATUS.DTL files. The PSFP form also purges any COMO files in the _PH_ directory created for the selected process runs.

Figure 22: Process Status File Purge (PSFP) Form

Step 1. In the Start Date field, enter the start date from which to purge records. Only processes run through the Envision Process Handler that started on or after this date will be selected.

108 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 109: Envision Runtime Administration

Working with Process Status File Records

Step 2. In the End Date field, enter the end date from which to purge records. Only processes run through the Envision Process Handler that ended before or on this date will be selected.

Step 3. In the User IDs field, enter the User IDs associated with the records to be purged. Only those records submitted by these User IDs will be purged.

Step 4. In the Mnemonics field, enter the mnemonics to be purged. Only those records executed from these mnemonics will be purged.

Step 5. Do you want to limit the selection of records by specifying additional selection criteria?

Yes. Enter Yes in the Additional Selection Criteria field. The Additional Selection Criteria form is displayed, as shown in Figure 21 on page 107. Use the Add’l Connective, Field Name, Relation and Parameter/Value fields to select additional criteria.

No. Enter No in the Additional Selection Criteria field. The Additional Selection Criteria form is not displayed, and all records in the specified date range are purged from the Process Status file.

Step 6. Update to the Process Submission form, as shown in Figure 8 on page 84, and specify how you want the PSFP process to be run.

Note: If the Start Date field is left blank, all records with start dates up to the date specified in the End Date field are purged, subject to your selection criteria. If the End Date field is left blank, all records with start dates on or after the date specified in the Start Date field are purged, subject to your selection criteria. If both fields are left blank, all records are purged, subject to your selection criteria.

Runtime Administration, March 10, 2010 109© 2010 Datatel, Inc.

Page 110: Envision Runtime Administration

Setup: Using the Envision Process Handler

Using Inquiry FormsTwo inquiry forms are available in the Process Handler.

Use the Outstanding Processes (OPRI) inquiry form, as shown in Figure 23, to view the available queues and their assigned tasks without the option of editing the data.

Figure 23: Example Outstanding Processes (OPRI) Form

Note: Use the Outstanding Processes (OPRM) form if you want to edit the data shown in the OPRI form. See “The Outstanding Processes (OPRM) Form” beginning on page 95 for more information.

110 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 111: Envision Runtime Administration

Using Inquiry Forms

Use the Running Processes (RPRI) inquiry form, as shown in Figure 24, to view the active queues and running processes without the option of resetting the queues.

Figure 24: Example Running Processes (RPRI) Form

Note: Use the Reset Process Queue Handler (RSPH) form if you want to reset the active queues. For more information, see “The Reset Process Queue Handler (RSPH) Form” beginning on page 94.

Runtime Administration, March 10, 2010 111© 2010 Datatel, Inc.

Page 112: Envision Runtime Administration

Setup: Using the Envision Process Handler

112 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 113: Envision Runtime Administration

Setup

Customizing an Application

FeaturesAs a part of your setup procedures, you have the option to customize several aspects of your software and system. Procedures are provided for customizing the following:

Header Blocks

Resolution Forms

Envision Menus

Standard Forms

Header Blocks

In Envision-based software, the header block is the set of fields at the top of the form, above the double horizontal line. The fields in the header block display information about the application and process with which you are working. Standard header blocks are provided for Runtime and each Envision application. The Runtime header blocks cannot be changed; however, the header blocks can be changed within each application and must be set up for the Correspondence Control module since a standard is not provided.

To change a header block, enter the application. Enter the Header Block Definition (PHD) form. Specific options are provided within the form. See the application administration guides for details.

Resolution Forms

A resolution form is a form that displays a list of all available items from which you may select one or one of the items with which to work. Many Envision-based applications use resolution forms. For example, if you enter [[...]] in response to the Menu ID LookUp prompt on the Menu Definition

Note: The STANDARD.FORMS directory file is no longer supported in Release 18.0.

Runtime Administration, March 10, 2010 113© 2010 Datatel, Inc.

Page 114: Envision Runtime Administration

Setup: Customizing an Application

(SMD) form, Envision displays a list of all available Menu IDs. It may also display certain characteristics about the records. We provide a default characteristics which you can change by application.

To obtain a list of all of the resolution specifications that Datatel provides, enter the LKUP: Resolution Specs (LPRT) from the application that you would like a report on. See “LKUP: Resolution Specs (LPRT)” on page 356, for further information.

To Change a Resolution Form

Step 1. Enter the application.

Step 2. Enter the LookUp Resolution Specs (UTRD) form.

Step 3. At the Resolution LookUp prompt, enter the primary file that the LookUp process uses. To assist you in entering the remaining information, you may want to get a hard copy of the dictionary of the primary file: LIST DICT primaryfile LPTR

Step 4. To add the new specifications, detail on Set Defaults and Resolution Specifications.

114 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 115: Envision Runtime Administration

Adding/Changing Envision Menus

Adding/Changing Envision MenusThe Envision Menu Processor uses menu definitions stored in the application file MENU to generate menu forms. These forms display to the user the options available on the menu, including both the mnemonic of the process and a description. While a process can be run from any menu prompt using the process’ mnemonic, a menu form displays a description of the process as well as allowing the user to enter a number instead of the mnemonic.

As system administrator, you may change the menus delivered with your application or you can create new ones. Since the MENU file is a shared file, any changes you make to a Datatel-defined menu will be overwritten the next time you install a release. The release installation, of course, will not affect the menus you have created.

To prevent losing your customized menus at each release installation, create new menus using the delivered menus as models. The simplest way to create a new menu is to copy the menu you wish to use as a model.

Creating a New Menu in the Same Application as the Model

1. Run the command:

COPY FROM appl.MENU model.menu, new.menu where appl is the mnemonic for the application, model.menu is the mnemonic for the model menu and new.menu is the mnemonic for the menu you are creating.

2. Enter the application appl and run the Menu Definition (SMD) form.

3. Add any valid process mnemonics or menu mnemonics to your new menu or delete existing mnemonics to customize the menu for your site.

When copying the new menu record, remember to choose a unique mnemonic for the new menu. Do not use a mnemonic defined for any Envision-based application or a custom mnemonic already created at your site. Remember that no Envision application delivered from Datatel will ever have a mnemonic which begins with the letter “X”. If you prefix your new menu mnemonic with the letter “X”, you can be sure that the mnemonic does not duplicate any Datatel-defined Envision mnemonic.

Runtime Administration, March 10, 2010 115© 2010 Datatel, Inc.

Page 116: Envision Runtime Administration

Setup: Customizing an Application

Creating a New Menu

Step 1. Enter the application for which you are defining the menu.

Step 2. Run the SMD form and enter a unique mnemonic for the new menu.

Step 3. Add valid process mnemonics to the menu.

Valid process mnemonics are those mnemonics for which a Process Control (PRCS.CTL) record is defined. The application file PRCS.CTL stores all the mnemonics which are executable by the Envision Menu Processor, as well as other records used by Envision Runtime. You can add new PRCS.CTL records from the SMD form, or you can use the Process Control Maintenance (PCM) form.

Define process control records for procedures, reports and Easy Screens so that these processes can be run from a menu. Remember that mnemonics cannot exceed four characters in length.

You can also redefine a menu from a higher application in a subordinate application. Since the application file MENU is subject to tree reads, Envision Runtime finds and uses the definition for the menu in the subordinate application. The Envision Tool Kit is required to define your own custom applications. You can prevent the loss of custom menus from a Datatel-defined application by creating your own custom menus in your subordinate application.

Creating a Menu Based on a Model in a Higher Application

Step 1. Run the following command:

COPY FROM appl.MENU TO subappl.MENU model.menu, new.menu where appl is the higher application in the application tree, sub.appl is the subordinate application, model.menu is the menu you wish to customize and new.menu is the mnemonics for the new menu you are creating.

116 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 117: Envision Runtime Administration

Adding/Changing Envision Menus

Step 2. Enter the application sub.appl and run the SMD form.

Step 3. Add any valid process mnemonics or menu mnemonics to your new menu or delete existing mnemonics to customize the menu for your site.

Because you are defining the custom menu in your own subordinate application, the new mnemonics for the menu can be the same as the model. Just remember that calls to Response Line will be much easier if you define unique mnemonics and avoid redefining mnemonics used in Datatel-defined application.

Runtime Administration, March 10, 2010 117© 2010 Datatel, Inc.

Page 118: Envision Runtime Administration

Setup: Customizing an Application

STANDARD.FORMS (Release 17.0 only)STANDARD.FORMS is a directory file that contains the source code and form images for programs you can modify. The source code has no prefix. This gives you a choice on some of the forms programs and allows you to change them even if you have not leased source code.

If you wish to make changes to a program in STANDARD.FORMS, identify the program that you wish to change. LIST STANDARD.FORMS gives you a list of the programs you can modify. Determine the program that you want to change, make the changes, and then test the program in your test account before you make the changes in your live account.

Modifying a Program in STANDARD.FORMS

Following is the procedure for changing STANDARD.FORMS programs. How to program is not covered.

Step 1. Copy the program from STANDARD.FORMS to CUSTOM.SOURCE. You will make the actual changes to the program once it is in CUSTOM.SOURCE.

:COPY FROM STANDARD.FORMS TO CUSTOM.SOURCE programname

If the program has the suffix -VER2 or .STD then change the name of the program to the Colleague standard name.

:CNAME CUSTOM.SOURCE programname,standardname

Step 2. Make the appropriate modifications. You should investigate the SOURCE.INSERTS that are inserted into the print routine. These will be prefaced by the $INSERT command. The SOURCE.INSERTS file holds the COMMON variables that are used throughout Colleague programs. Never modify the SOURCE.INSERTS file!

:edit CUSTOM.SOURCE programname

Note: STANDARD.FORMS is no longer supported in Release 18.0.

118 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 119: Envision Runtime Administration

STANDARD.FORMS (Release 17.0 only)

Step 3. Copy the modified program to the module.SOURCE or application.SOURCE file.

:COPY FROM CUSTOM.SOURCE TO module.SOURCE programname

Step 4. Compile the program.

:BASIC module.SOURCE programname

Step 5. Determine if the program requires a catalog VOC record. If so, catalog the program. In UniData, the program should be cataloged locally until it is thoroughly tested.

:edit VOC programname

If line 1 is a V for verb, then catalog the program.

:CATALOG module.SOURCE programname

Step 6. If there is a form image, copy it to FORM.IMAGES.

:COPY FROM STANDARD.FORMS TO FORM.IMAGES form_image

Runtime Administration, March 10, 2010 119© 2010 Datatel, Inc.

Page 120: Envision Runtime Administration

Setup: Customizing an Application

120 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 121: Envision Runtime Administration

Setup

Grouping Screens

Chaining ScreensYou can group, or chain, Envision screens to handle a specific workflow. The following are the key concepts related to screen chains. These are covered in more detail in the remainder of this chapter.

Not all Datatel screens function properly in a screen chain. In general, Datatel advises against using this feature.

You assign a unique mnemonic to each chain you define, and you may add this mnemonic to any menu.

You may include up to 16 screens in a chain.

You may chain only true screens; that is, individual screens used for data entry or inquiry.

You may not include procedure front-end screens, procedures, batch processes, or other chains in a chain. In general, you can recognize Envision procedures by the fact that they are usually listed on menus in the Processing or Reporting quadrants; batch processes never appear on menus.

You can make individual screens within a chain required. If the user bypasses required screens while working within a chain, those screens are automatically displayed before the user can completely finish with the chain.

You may specify a subroutine to be run after the user has finished with a chain.

Chains are application-specific; that is, you define them from within the application in which you want them used and in which the screens you want to include are accessible.

When the user enters the chain mnemonic, the first screen in the chain is displayed.

Each screen in a chain is displayed with the same screen title and mnemonic that would be displayed if the screen were accessed directly from the menu prompt.

The user’s work is saved only after the users finishes with the entire chain; that is, the user’s work is not saved as the user moves from screen to screen within the chain.

Runtime Administration, March 10, 2010 121© 2010 Datatel, Inc.

Page 122: Envision Runtime Administration

Setup: Grouping Screens

All screens within a chain take on the security rights specified for the chain.

The screens you include in a chain continue to be accessible individually, in the normal way, unless you change your security class definitions to prevent this.

The most seamless chain of screens is one where each screen would otherwise prompt the user for the same thing. For example, in the Demographics module, in the Core System, the following all prompt the user for a person ID:

Name and Address Maintenance (NAE)

Relation Information (REL)

Emergency Information (EMER)

If you were to chain these screens in the order shown above, the Person LookUp prompt would be displayed, prompting the user for a person ID, when the chain was accessed and the Name and Address Maintenance form was displayed. When the user finished the Name and Address Maintenance form, the Relation Information form would be displayed for the same person with no further prompting, and when the user finished the Relation Information form, the Emergency Information form would be displayed for the same person without further prompting.

If you chain screens that would otherwise prompt the user for different things, then the appropriate prompts are displayed when each screen is displayed. You can, therefore, chain screens that are totally unrelated.

Security and Chaining

All screens within a chain take on the security rights specified for the chain. If the security rights you specify for a screen differ from the security rights you specify for a chain to which that screen belongs, the security rights specified for the chain take precedence. It is important to ensure that you limit access to the Screen Chaining Specification (SCSP) form. Otherwise, someone could use the SCSP form to add an otherwise inaccessible screen to an accessible chain.

To restrict access to the SCSP form, Datatel has included it in the privileged list in the ADMIN security class in UT, which includes screens that are usually restricted to the system administrator.

122 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 123: Envision Runtime Administration

Chaining Screens

Application Hierarchy and Chaining

You define screen chains from within the application in which you want them used. Like operator records and security classes, chains that are defined at the top of the application hierarchy (for example, in the Core System), are visible to applications lower in the hierarchy.

Chains defined in peer applications, such as the Human Resources System and the Financial System, are not visible in both; that is, if a chain is defined in the Human Resources System, it is not visible in the Financial System. Only screens that are otherwise visible to an application—that is, those within and above the application in the hierarchy—may be included in a chain.

Function Keys and Chaining

To support movement among chained screens, use the following three function keys:

Table 3: Movement Function Keys

Function Function Description

FWD Displays the next screen in the chain.

If you go forward while the last screen in the chain is displayed, the system responds as if you had Finished.

BACK Displays the previous screen in the chain.

If you go back while the first screen in the chain is displayed, the system responds with a beep.

JUMP Displays a mini-menu of all screens in the chain, from which you can select the screen you want to display.

Runtime Administration, March 10, 2010 123© 2010 Datatel, Inc.

Page 124: Envision Runtime Administration

Setup: Grouping Screens

As shown in Table 4, some of the existing function keys work a little differently for chained screens, although they perform essentially the same functions they always have. The behavior of all other existing function keys remains unchanged.

Table 4: Existing Function Keys and Chained Screens

Function Function Description

CANCEL Cancels changes made to the current record.

When you cancel, the following prompt is displayed:

Field JUMP to make changes, cancel to discard changes to this screen only

Field JUMP to return to the screen without cancelling or cancel if you do no want to save the work you have done on the current screen.

If you cancel the second time, your work on the current screen is discarded and you are asked to further confirm the cancellation:

RETURN to continue, cancel to discard all changes in chain

RETURN to redisplay the current screen with the original data or cancel to discard all changes made on all screens in the chain. If you cancel this time, the first screen in the chain is redisplayed and you are prompted for a new record ID.

Direct ACCESS

Invokes another screen from the current screen without returning to the menu. If the current screen has a LookUp prompt, you must respond to the prompt before pressing this key.

When you press Direct ACCESS, the following prompt is displayed:

Field JUMP to make changes, return to confirm or cancel to abort.

To save any changes you might have made and continue, press Enter. The following prompt is then displayed:

Enter mnemonic of process to run or cancel.

Once you have accessed a chain, you may access only screens within that chain. You cannot jump out of a chain using Direct ACCESS. Although you can move from screen to screen within a chain using Direct ACCESS, it may be easier to move around within a chain using the screen movement keys. See Table 3 on page 123 for further information on screen movement keys.

124 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 125: Envision Runtime Administration

Chaining Screens

EXIT Exits from the current screen and returns you to the menu from which the chain was accessed. If you used Direct ACCESS to access the chain, you are returned to the menu from which you accessed the screen you were on when you pressed Direct ACCESS.

When you EXIT, the following prompt is displayed:

Field JUMP to make changes, RETURN to confirm, cancel to abort this screen.

Field JUMP to return to the screen without cancelling, RETURN to save your work and exit to the menu, or CANCEL if you do no want to save the work you have done on the current screen.

If the chain includes required screens and if you EXIT before you have displayed the required screens, each required screen is displayed before you return to the menu.

FINISH Exits from the current screen and returns you to the menu from which the chain was accessed. If you used Direct ACCESS to access the chain, you are returned to the screen you were on when you pressed Direct ACCESS.

When you FINISH, the following prompt is displayed:

Field JUMP to make changes, RETURN to confirm, CANCEL to abort this screen.

Field JUMP to return to the screen without cancelling, RETURN to save your work and return to the menu or direct access screen, or CANCEL if you do no want to save the work you have done on the current screen.

If the chain includes required screens and if you FINISH before you have displayed the required screens, each required screen is displayed before you return to the menu or the direct access screen.

UPDATE Exits from the current record, redisplays the first screen in the chain, and prompts for a new record ID.

When you UPDATE, the following prompt is displayed:

Field JUMP to make changes, RETURN to confirm, CANCEL to abort this screen.

Field JUMP to return to the screen without updating, RETURN to save your work and return to the first screen in the chain, or CANCEL if you do no want to save the work you have done on the current screen.

If the chain includes required screens and if you UPDATE before you have displayed the required screens, each required screen is displayed before you return to the first screen in the chain.

Table 4: Existing Function Keys and Chained Screens (cont’d)

Function Function Description

Runtime Administration, March 10, 2010 125© 2010 Datatel, Inc.

Page 126: Envision Runtime Administration

Setup: Grouping Screens

Components of a Screen Chain Definition

Use the Screen Chaining Specification (SCSP) form to define a group of screens in a way that mimics the flow of screens in Colleague processes.

Figure 25: Example Screen Chaining Specification (SCSP) Form

Use Table 5 to guide you in completing this form.

Table 5: Fields on the Screen Chaining Specification (SCSP) Form

Field UsageRequired/Optional

Description Describes the group of screens. The description is displayed next to the mnemonic on any menus to which you add the chain.

Optional

Short Help Message

Provides a one-line message further describing the chain. The user can display this message by typing the chain mnemonic at a menu prompt and accessing Process Help.

Optional

Long Help Text Provides a longer message describing the chain. The user can display this message by typing the chain mnemonic at a menu prompt and accessing Process Help. If the chain has short help, the short help message is displayed first. When the user Returns after viewing the short help, the long help is displayed. If the chain does not have short help, the long help is displayed immediately after the user accessing Process Help.

Optional

126 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 127: Envision Runtime Administration

Procedure for Chaining Screens

Procedure for Chaining Screens Follow these steps to define a new screen chain and make it available to your users:

Step 1. Choose a mnemonic for the chain.

Step 2. Access the application in which you wish to define the chain. The application’s main menu is displayed.

Step 3. Enter SCSP at the menu prompt.

Step 4. Enter the chain mnemonic at the Chain Process LookUp prompt. The following prompt is displayed:

Record not found -- Enter (A) to add or RETURN to reenter

Mnemonic Lists the mnemonics of the screens in the chain in the order in which they will be displayed. You may include up to 16 screens in a chain. You may chain only true screens; that is, individual screens used for data entry or inquiry. You may not include procedure front-end screens, procedures, batch processes, or other chains in a chain. In general, you can recognize Envision procedures by the fact that they are usually listed on menus in the Processing or Reporting quadrants; batch processes never appear on menus.

Required

Require Determines whether the user must display the screen before finishing with the chain. The default is No. See Table 4 on page 124 for a description of what happens when there are required screens in a chain.

Optional

Post-Commit Subroutine

Specifies the name of the subroutine that will be run after the user has confirmed that her work should be saved. The specified subroutine is run after all error checks are done and the records used in the chain have been written to disk.

Optional

Table 5: Fields on the Screen Chaining Specification (SCSP) Form (cont’d)

Field UsageRequired/Optional

Runtime Administration, March 10, 2010 127© 2010 Datatel, Inc.

Page 128: Envision Runtime Administration

Setup: Grouping Screens

Step 5. Enter A at the prompt. The cursor moves to the Description field. Notice that the code entered at the LookUp prompt is displayed in the header.

Step 6. Complete this form, using the field definitions in Table 5 on page 126 as a guideline.

Step 7. FINISH to save your work and return to the menu. The screen chain is immediately accessible to users unless you are using “Do Only These” security. Continue with Step 8 if your security classes are set up as “Do Only These.”

Step 8. Create a new security class containing the chain mnemonic or add the chain mnemonic to an existing security class. If you create a new security class, then add that security class to the appropriate users’ operator records.

See “Security and Chaining” on page 122 for a discussion of special security issues with respect to screen chains.

See the documentation for the Security Class Definition (SCD) form for information on defining security classes. See the documentation for the Operator Definition (SOD) form for information on defining operator records.

If you created a new security class, then the chain is accessible to your users after you have added that security class to their operator records.

If you added the chain to an existing security class, the chain is accessible to your users as soon as you complete the update of the security class definition.

128 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 129: Envision Runtime Administration

Procedure for Reporting on Chained Screens

Procedure for Reporting on Chained Screens

Follow these steps to report on screen chains:

1. Access the application on which you wish to report.

2. The application’s main menu is displayed. Enter CHUS at the menu prompt.

3. The Chain Usage Report is displayed.

You wish to list all of the chains defined in an application along with the screens that belong to those chains. Enter C in the Report by Chains or by screens field.

You wish to list all of the screens in an application that belong to a chain along with the chains to which they belong. Enter S in the Report by Chains or by screens field.

4. RETURN twice.

5. The Change Peripheral Defaults form is displayed.

6. Complete the Change Peripheral Defaults form as desired. FINISH and RETURN.

7. The Process Submission form is displayed.

8. Complete the Process Submission form as desired. FINISH and RETURN to run the report.

The report is sent to the peripheral device you specified on the Change Peripheral Defaults form.

Runtime Administration, March 10, 2010 129© 2010 Datatel, Inc.

Page 130: Envision Runtime Administration

Setup: Grouping Screens

130 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 131: Envision Runtime Administration

Runtime Administration

Security

Page 132: Envision Runtime Administration
Page 133: Envision Runtime Administration

Security

Security Overview

IntroductionThe Security section of Runtime Administration contains the information you need to secure Colleague programs, files, and data from unauthorized access. Presented in the chapters are guidelines for operating system security, securing the DBMS, and procedures for creating user remote accounts. Full information for establishing process, record, and field security is also provided. Worksheets to assist with the security setup are in “System Setup Worksheets” beginning on page 295. There are three levels of security on the system:

Operating System

Database Management System

Application Software

Your application software combines the three levels, with an emphasis on the Database Management System and Application Software, to create a secure system for your site.

Logging InWhen logging into the system, a user passes through the operating system, to the data base management system, and to the application software. In detail, the user goes through the following steps:

Runtime Administration, March 10, 2010 133© 2010 Datatel, Inc.

Page 134: Envision Runtime Administration

Security: Security Overview

UNIX

Step 1. The Operating system login ID and password are validated.

Step 2. In your home directory, the following files, .login and .cshrc, are run if you are executing the C SHELL. If you are executing the BOURNE SHELL then, .profile is run.

The .cshrc is run first and then the .login file. There are many uses for these files for a user that has access to UNIX. For an application software user, the files are used to move the user to their user remote account and to invoke UniData with the “exec” command.

The exec command is used with the udt command to prevent users from entering UNIX upon logging out of UniData. When you precede a command with exec, it tells the system to run only this process. When the user leaves UniData, he has no other processes to run and is logged off of the system.

Step 3. On entering UniData at the user remote account, the system looks for a LOGIN paragraph in the VOC file. For the UniData user, the paragraph must contain ENV.INIT. You can customize the paragraph to bring up the application menu.

Windows 2003/2008

Step 1. The Operating system login ID and password are validated.

Step 2. You are directed to the UniData account you last accessed, or prompted for the path of the account you wish to access, depending on the way you are set up in UniData.

Step 3. Upon entering UniData at the user remote account, the system looks for a LOGIN paragraph in the VOC file. For the UniData user, the paragraph must

ALERT! The .login and .cshrc files must be present in your home directory.

134 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 135: Envision Runtime Administration

Logging In

contain ENV.INIT. You can customize the paragraph to bring up the application menu.

For All Platforms

Step 1. Once the Device is established, the outermost layers of Envision Security become active. Each device may potentially have a password and security class associated with it. If a password is active, you are prompted for it. If a security class is associated with it, it becomes active.

Step 2. The rest of Envision Runtime Security becomes active when you enter the application.

Step 3. Envision looks for an OPERS record keyed by your login ID in each application in your application tree. If an OPERS record is not found, Envision informs you that you are not a valid user and runs LO.

Step 4. If your OPERS record is found, Envision Runtime uses the user definition supplied by that record. In that record, an additional Envision password may be defined. Envision Runtime prompts you for your Envision password. You must correctly enter this password or Envision Runtime runs LO.

Step 5. To determine the application processes to which you have access, Envision Runtime examines all of the security classes defined for you, taking into consideration both device and operator security classes. Envision Runtime starts with the “Do Only These” lists of processes. If any of the security classes defined has a “Do Only These” list, that list becomes the global list of processes to which you have access. If more than one security class has a “Do Only These” list, the lists are combined, and the union of the several “Do Only These” lists become the global access list for you. If none of the security classes defined for the operator or the device has a “Do Only These” list, you currently have access to every process in the current application and every process in the applications above the current one in the application tree.

Technical Tip: Device Security Classes are ignored for Switch-based systems.

Runtime Administration, March 10, 2010 135© 2010 Datatel, Inc.

Page 136: Envision Runtime Administration

Security: Security Overview

Step 6. Once the global access list has been defined, Envision Runtime then examines the “Never Do These” lists for each security class. These processes are removed from the global access list. If more than one security class has a “Never Do These” list of processes, the lists are combined, and each process in the union of the lists is removed from the global access list.

Step 7. Next, Envision Runtime checks to determine if any of the processes in the global access list is defined as privileged in another class. If a process is privileged, you must have the privileged class defined for him or the privileged process is removed from the global access list. If a privileged process is defined as privileged in more than one class, you must have at least one of the privileged classes.

Step 8. Finally, Envision Runtime flags those processes listed in the “Inquiry Only” list so that you may view but not add to or alter the data maintained in that process. If more than one of your security classes has an “Inquiry Only” list, then the lists are combined, and the processes in the union are flagged as inquiry processes.

Step 9. Envision Runtime also sets up your record security characteristics. These characteristics are used to evaluate selection criteria defined for a file. Values for specific fields within a file are compared to selected user characteristics to determine whether a user has access to a record from the file. If your characteristics do not match the specified value in the record, your access to that record is limited according to the record security specification.

Step 10. Envision Runtime then determines the process you can run first. The SOD form allows you to define the initial application process to run. Since your OPERS record comes from UT, this initial process should come from the UT application. You can, however, make the initial process the main application menu by specifying your initial process is an asterisk (*). Envision Runtime then uses the main menu from the current application as the initial application process. In this case, the user ADMIN is presented with the main menu for the application XCF.

136 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 137: Envision Runtime Administration

Logging Off

Logging OffWhen the user logs off, the system looks for the paragraph LOGOUT and runs it if it exists.

Runtime Administration, March 10, 2010 137© 2010 Datatel, Inc.

Page 138: Envision Runtime Administration

Security: Security Overview

138 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 139: Envision Runtime Administration

Security

Operating System Security

Within the operating system, you have two security areas to address:

Setting Up Login IDs and Passwords for Users

Setting Rights on Directories and Files

Setting Up Login IDs and Passwords for Users

Refer to the documentation for your operating system for full details on adding users to your host system.

A login ID and password are required to gain access to the host system. Each operating system provides different utilities for setting up IDs and passwords for users. In general, these utilities establish the following information about each user:

Login Id

Password

Initial attach point (home directory)

Operating system security rights

Command environment attributes

These utilities provide methods for adding, deleting, and modifying users’ login IDs and other user attributes.

Setting Up Users in UNIX

In the UNIX operating system, use the adduser utility to set up user attributes. In UNIX, setting up new user accounts and setting up remote accounts are closely related.

Note: You must be logged in to your host system as the system administrator to use these utilities.

Runtime Administration, March 10, 2010 139© 2010 Datatel, Inc.

Page 140: Envision Runtime Administration

Security: Operating System Security

Operating System Security in UniData

UniData’s security, in combination with Colleague’s setup procedures, adequately covers most security needs. Datatel recommends that you devise an uncomplicated and straightforward user authorization file setup. Usually, this means setting user authorization files on the master file directory (MFD) and user file directory (UFD) levels and allowing those rights to default to subsequent files and subdirectories.

Accessing the Database Management System

Every site must decide whether to allow end users access to the database management system. Several levels of security exist within the database management and application software that restrict what end users can do. There are basically three levels of restriction that a site can choose for each of its users:

Complete restriction to the database management system

Limited restriction to the database management system

Access to the database management system

Degrees of restriction exist within each of the above.

140 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 141: Envision Runtime Administration

Complete Restriction

Complete RestrictionComplete restriction from the database management system allows a user to enter the application software that is applicable to the user’s job. When the user logs in, only the menu options that the user is allowed to access appear on the user’s menu.

Guidelines for Complete Restriction

Step 1. Create a user remote account. Log the user directory into this account.

Step 2. In the login paragraph of the remote account, enter the application or the module from which the user will perform the user’s job. Enter LO as the last line in the paragraph to prevent the user from entering the DBMS level.

Step 3. Assign a security class to a user that allows the user to run LO but not EX. EX allows access to the DBMS level.

Limited RestrictionLimited restriction to the database management system allows a user to enter the application software that is applicable to the user’s job and some level of access to the Query language. Within the application software, there are two processes that allow this:

Sequential File BROWSE Shell (UTFB) process

Query Builder (User Interface)

If neither one of these options will work for your user, you could create a separate user remote account for the end user to log in to. This account would contain only the Query language commands necessary to perform the user’s job function and the limited files that you want the user to access with the query language. However, you may want to consider limiting this method since it could potentially create a multitude of accounts requiring maintenance.

Runtime Administration, March 10, 2010 141© 2010 Datatel, Inc.

Page 142: Envision Runtime Administration

Security: Operating System Security

Guidelines for Limited Restriction

Follow “Guidelines for Complete Restriction” beginning on page 141 for Complete Restriction. To add Browse:

Step 1. Assign the user a security class that contains the mnemonic UTFB.

Step 2. Define the directories that the user is allowed to access through the BROWSE File Authorization (UTFA) process in UT. These might include:

Command logs

Documentation directories

Word processing directories

Vocabulary (VOC) records

If you do not define any directories, the user will be able to access the HOLD directory only, which contains generated reports.

Using the Sequential File BROWSE Shell (UTFB) Process

The UTFB process allows users to view data records in a file directory. In the BROWSE process, the screen acts as a 22-line, 80-character window into a record.

Locate a file directory to browse. The default system file is the Printer Hold File. In most data screens, the LookUp prompt allows you to enter a value that matches the key field value of a record in your database. The key field contains a field value that uniquely identifies a record.

Technical Tip: BROWSE has a delete capability and allows a user to delete records from the directory. Use discretion in deciding the files the user can access and never allow the user access to a source code directory.

142 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 143: Envision Runtime Administration

Limited Restriction

HOLD File Security

In Release 18.0, Envision 4.8 allows you to select the security you want to associate with your file output. Locate a file directory to browse. The default system file is the Printer Hold File.

Public file security (PB)

Public file security sends the output to the HOLD file, only using the default security associated with the person creating the output. Public file security means that the output can be viewed by anyone.

Private file security (PR)

Private file security sends the output to a subdirectory using the User ID of the person creating the output. This subdirectory is located in a PRIVATE subdirectory within the HOLD file. A VOC pointer is also created named HOLD.PRIVATE.userid, where userid is the ID of the person who creates the output. Private file security means that the output can be viewed only by the person who creates the output.

Shared file security (SH)

Shared file security sends the output to a subdirectory, whose name is the same as the group name. You must specify the group name. This subdirectory is located in a SHARED subdirectory within the HOLD file. A VOC pointer is also created named HOLD.SHARED.groupname, where groupname is the name of the group. Shared file security means that the output can be viewed only by members of a pre-approved group. See also “Output Security Groups” beginning on page 145.

Note: In order to write, transfer, and delete PDF files for report processes, permissions on private and shared _HOLD_ directories allow access to the DMI listener. On Windows servers, this equates to granting the SYSTEM user full access to these directories (because DMI runs as a service). On UNIX and Linux servers, this translates to granting global write access to these directories. (Read access remains the same.)

Runtime Administration, March 10, 2010 143© 2010 Datatel, Inc.

Page 144: Envision Runtime Administration

Security: Operating System Security

Figure 26: Sample Sequential File BROWSE Shell (UTFB) Form

Step 1. Use the Directory File Name LookUp to locate an existing file directory to browse. The default is the Printer Hold File. In most data screens, the LookUp prompt allows you to enter a value that matches the key field value of a record in your database.

Step 2. Select the security to associate with your file output.

Public file security (PB)

Private file security (PR)

Shared file security (SH)

Step 3. Locate existing items that exist in the file directory to browse.

Note: This version of the UTFB form (including Security Type) is available in Release 18.0 for Envision 4.8 only.

Envision 4.8 only

144 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 145: Envision Runtime Administration

Limited Restriction

Step 4. Enter a browse file option:

S - Spool the item to the line printer (132x60).

B - Browse the item at your terminal.

D - Delete the item from the file.

You may enter one, two, or all three options:

BS - Browse the item and then spool it to the line printer.

SD - Spool the item and then delete it from the file.

BSD - Browse the item, spool it, and then delete it from the file.

Output Security Groups

When you are creating output to a hold file, as selected on the Change Peripheral Defaults (CPDE) process, you can specify a group type security. This type of security limits access to the document to only those accounts that are members of the group.

The name of the group will also be used in constructing the path to the HOLD file subdirectory that contains the output files. The path will consist of a subdirectory called SHARED within the HOLD file containing a further subdirectory by the name of the group (containing the actual secured output files). In addition, a VOC pointer named HOLD.SHARED.groupname will be created, where groupname is the name of the group.

Runtime Administration, March 10, 2010 145© 2010 Datatel, Inc.

Page 146: Envision Runtime Administration

Security: Operating System Security

Figure 27: Sample Output Security Groups (OSGD) Form

Provide a key indentifier for the hold shared security groups. This key will be used for LookUp in places where shared hold security must be specified. Associated with this identifier is a description, and also the operating specific equivalent that will be issued to secure any files that are created using this group.

146 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 147: Envision Runtime Administration

Security

Application Security

Types of SecurityEnvision Runtime security is based on the premise that what the end user sees is what the user is allowed to use. Any menu, process, record or field for which an end user has no security is never available as an option for that user while in the Envision environment. Security in Envision is defined in three layers:

Process Security

Record Security

Field Security

Process Security is based on security classes. Security classes assign groups of users security rights for specified menus and processes. Before allowing users to run an Envision-based application, define the security classes for your system so that the work-flow for each user can be controlled.

Each person that is to access the application must have an operator definition record or OPERS record. The security class is then assigned to the individual through the OPERS record.

Operator definition is covered in the next chapter.

Record and Field security allow you to secure certain records and even certain fields from a user. Record and Field Security are covered in the last two chapters of this section.

Runtime Administration, March 10, 2010 147© 2010 Datatel, Inc.

Page 148: Envision Runtime Administration

Security: Application Security

Security ClassesSecurity classes are structured after the work-flows of the application users. For example, data entry clerks are allowed to use processes that allow data entry. Office managers have a wider set of responsibilities and therefore have fewer restrictions. There are also certain processes which only you as system administrator should be able to run.

Remember to consider the Envision application structure when defining your security classes. At the top of every application’s application tree is the Runtime application (UT). When examining the system files, Envision Runtime first checks the current application’s system files for the record requested. If the record is not found, Envision Runtime begins to traverse the application tree, searching each subsequent set of system files for the requested record. If Envision finds the requested record in an application higher in the tree, it will use the data from that record. Envision continues to traverse the application tree until it reaches the UT application. If the requested record is not found after examining the UT application, then the record does not exist in the current application’s tree structure.

Example: Consider the following application tree: at the base of the application tree is the current application, a user defined application called XCF. This application is defined as a subordinate application to the Datatel application CF. Completing the application tree are the Datatel application CORE and the Runtime application UT.

One of the system files for which Envision uses in tree reads is the security class definition file called appl.SECLASS, where appl is the mnemonic for an application. Consider, then, a security class called ADMIN.

As system administrator, you have access to the Envision Runtime application (UT). Since UT is an application with associated forms and files, you can run UT just like any other application. In the Envision application structure, the UT application is at the top of every other application’s tree. What this structure means to you is that, for all Envision files, Envision Runtime will examine the UT system files if the requested record is not found in lower applications of the application tree. As system administrator, therefore, you can define one OPERS record, for example, which will be used by all applications that do not have an OPERS record with the same key.

148 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 149: Envision Runtime Administration

Security Classes

Restricting User Access on the Security Class Definition (SCD) Form

The Security Class Definition (SCD) form allows you to define security classes based on the work-flows of your application’s end users. The four categories of processes provide four different ways of restricting user access.

Do Only These. The Do Only These category limits the end user’s access to the application to the finite list of menus and processes included in this list. When combining security classes, the Do Only These list from each class is combined into one list. If a Do Only These list exists, this list of processes and menus becomes the global access list for the user. If the user has not defined Do Only These lists, the user’s global access list is every process in the current application and every application above it in the application tree.

Never Do These. The Never Do These category allows you to prevent end users from accessing a finite list of processes and menus. If an end user can have access to all but a few processes, it is easier to define which processes the user cannot access rather than list the numerous processes which the user can access. Each process or menu listed in the Never Do These list is removed from the end user’s global access list, thereby preventing user access to that process or menu. If the end user has more than one security class, the Never Do These lists are combined and the menus and processes in the union of these lists are removed from the user’s global access list. If the user does not have Never Do These lists defined, the user has access to all menus and processes left after determining the global access list defined by the Only Do These category.

Inquiry Only. The Inquiry Only category allows you to let users in the security class access the processes listed, but these users may only view the data maintained on these forms; they may neither add nor modify this data. Processes defined as Inquiry Only for a security class remain in a user’s global access list, but are flagged so that Envision Runtime will prevent any changes. If the user has more than one security class, the Inquiry Only list for each class is combined and processes in the resulting list are marked as inquiry in the global access list.

Privileged. The Privileged category allows you to restrict access to a finite list of processes and menus so that only members of certain security classes can access them. If a user is not a member of a security class for a Privileged process or menu, that user may not access that process or menu. If the Privileged process or menu is not in the user’s current global access list, the user may not access that process or menu. If a process or menu is defined as Privileged in more than one security class, a user need only be a member of one of those classes to potentially have access to that process or menu.

Runtime Administration, March 10, 2010 149© 2010 Datatel, Inc.

Page 150: Envision Runtime Administration

Security: Application Security

Restricting User Access for Detail Forms

It is important to note that if a form in a list allows detailing to other forms, the UI and WebAdvisor interfaces act differently in how they handle these detail forms.

Detail Forms in UI

In UI, when users detail from one form to another, they have the same access rights to the detail form that they had on the form from which they detailed. For example, if the user is currently in a form to which the user has only inquiry-only rights, then all detail forms are also inquiry-only for the user. If you want to change the security level when a user details, access rights to any detail forms must be explicitly defined for the user. For example, the following user has only one security class assigned, and it has the following setup:

DO.ONLY.THESE: NAE

This user has full access rights to the Name and Address Entry (NAE) form and to all forms to which the user can detail, either directly or indirectly. The user could detail from the NAE form to the BIO form, and from there to the Foreign Person Information (FINF) form, and have full access rights (be able to change data) on any of those three forms.

However, if the security class were set up as follows:

DO.ONLY.THESE: NAE

INQUIRY ONLY: BIO

Then when the user details from the NAE form to the BIO form, the user has inquiry-only access. If the user then details from the BIO form to the FINF form, the user is restricted to inquiry-only rights.

Detail Forms in WebAdvisor

WebAdvisor works differently. In WebAdvisor, each time a user details, the access rights are evaluated independently of where the user came from. There is no concept of inheriting access rights from another form. For WebAdvisor forms, each form should be explicitly referenced in a security class.

Note: See AnswerNet document 5166.75 for an issue when users have “Inquiry Only” access to a PERSON-based detail form, and the user selects “A” to add from a Resolution screen. Unless the user cancels at this point, a bogus PERSON record is created when the user saves.

150 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 151: Envision Runtime Administration

Security Classes

Guidelines for Defining Security Classes for an Application

For each work-flow you have defined for your application users, create a security class. Keep the security classes simple. Envision security is a simple concept to grasp if the classes you define are remain simple. In the following discussion, menus as well as processes can be listed on the Security Class Definition (SCD) form. The use of the word process implies menus as well.

On SCD, you can limit the range of processes that a class of users can run (Do Only These), you can restrict a class of users from executing a list of processes (Never Do These), you can restrict a class of users from modifying the data for a list of processes (Inquiry Only), or you can restrict a list of processes to only one class (Privileged).

At the initialization of the application, Envision Runtime builds a list of the processes to which a user has access. This list begins as a list of all processes defined for the application. Envision Runtime then compares the global list to the list of Do Only These processes. If this restricted list is defined, it becomes the global list of processes to which the user has access. If this restricted list is not defined, the user still has access to all application processes.

Envision Runtime then removes any processes in the Never Do These process list from the global list. If the restricted list is not defined, the global list remains as is.

Any processes defined in the Inquiry Only process list are left in the global list, but are flagged so that this class of users may not modify data maintained on the processes in the inquiry list.

Finally, Envision Runtime verifies that each process in the current global list is not defined as a Privileged process in another class. Privileged processes are removed from the user’s list. If a user is in a class that has access to a privileged process, that process will remain in the global list. If the process is privileged in more than one class, the user must be a member of at least one class for which the process is privileged in order to have access to the process.

The final list of processes defines those processes that a user may access. This global list remains in effect until the user logs off of the system or until the user leaves the database environment.

Note: Note that restricting the access of a user to a menu does not restrict each process on that menu; you must restrict each process as well.

Runtime Administration, March 10, 2010 151© 2010 Datatel, Inc.

Page 152: Envision Runtime Administration

Security: Application Security

Use the worksheet included in “System Setup Worksheets” beginning on page 295 to define the processes that each class of users may access. Check the list of processes for an application in the user documentation for that application. Also use the list of Runtime mnemonics included in the Appendices. The work-flows of each class of users determine the processes each class needs to run. Be sure that every work-flow of every possible user of the application is defined by a security class. Also be sure that each work-flow has one and only one class so that you need not worry about the ramifications of combining security classes.

Procedure for Creating Security Classes

Step 1. With the department manager, determine the classifications for your end users by job function. For example, data entry, managerial, or computer center staff.

Step 2. Complete the security class worksheet in “System Setup Worksheets” beginning on page 295.

Step 3. To add a new security class, enter the Security Class Definition (SCD) form from UT. Fill in the appropriate fields according to your worksheet.

Step 4. Add the security class to the appropriate opers records through SOD. Remember, you can assign the same security class to several opers records.

152 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 153: Envision Runtime Administration

Operator Definition

Operator DefinitionEach person that is to access an application must have an Operator Definition record. The record is stored in the application file OPERS. Each application has its own OPERS file. The ID of the opers record should correspond to the login ID of the person. If a login ID is shared, then the opers record will also be shared. We recommend that each person have their own login ID.

The application file OPERS is subject to tree reads. Every operator does not need an OPERS record in each application to which the operator has access. If Envision Runtime does not find an operator definition in the current application’s OPERS file then it will read the OPERS file in each of the applications in the current tree. If an OPERS record is not found after traversing the tree, then the operator is assumed to be unauthorized and is logged out.

The main information that is associated with an operator record is:

User ID (must be the same as the login ID)

Envision Password

Security Classes

Initial mnemonic to run when the operator enters the application

Runtime Administration, March 10, 2010 153© 2010 Datatel, Inc.

Page 154: Envision Runtime Administration

Security: Application Security

Creating/Deleting Operator Definition Records

You may define operator records from within any application in the hierarchy. Datatel recommends that you define all operator records from within Runtime (UT). This makes it easier for you to keep track of your operator definitions and reduces the likelihood of users having problems accessing certain applications.

Use the Operator Definition (SOD) form to define operator records for all individuals who are allowed access to Envision-based applications. Before you define operator records, first define security classes in each application using the Security Class Definition (SCD) form.

Figure 28: Example Operator Definition (SOD) Form

154 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 155: Envision Runtime Administration

Creating/Deleting Operator Definition Records

Procedure for Creating an Operator Definition Record

Step 1. Create a unique OPERS record for each user.

Step 2. The OPERS record ID must be the same as the operating system login ID.

Step 3. Complete the Worksheet in “System Setup Worksheets” beginning on page 295.

Step 4. To add a new OPERS record, enter the system Operator Definition (SOD) form in UT. Define the following fields:

User ID

Name (required)

Initial menu

Envision Password

Password Expiration Date

Security Classes

Maximum Login Retries

Step 5. Test the record. Log the user in to the system and access the application software.

Procedure for Deleting an Operator Definition Record

Step 1. Determine the application OPERS file that the obsolete operator definition resides in.

Step 2. Run the application.

Runtime Administration, March 10, 2010 155© 2010 Datatel, Inc.

Page 156: Envision Runtime Administration

Security: Application Security

Step 3. Run the Envision Runtime System Operator Definition (SOD) form.

Step 4. Enter the ID of the obsolete operator definition.

Step 5. Press the [RECORD DELETE] key. Envision Runtime prompts you to press the [RECORD DELETE] key a second time to confirm.

Step 6. Press [RETURN] at the final prompt to delete the operator definition from the application’s OPERS file.

Step 7. Make sure to remove the user’s login privileges at the operating system level to ensure the user can no longer access your system.

156 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 157: Envision Runtime Administration

Using the PRCS.CTL Security Inquiry (PCSI) Form

Using the PRCS.CTL Security Inquiry (PCSI) Form

The PRCS.CTL Security Inquiry (PCSI) form, shown in Figure 29, is a useful tool for security troubleshooting. This inquiry form allows you to verify at a glance which security classes are denied access, permitted access, or permitted inquiry-only access to a process or a field.

Figure 29: PRCS.CTL Security Inquiry (PCSI) Form

Use the PCSI form to inquire about the security classes that currently affect the selected process. If a security class restricts a process, end users in that class are unable to run or even see the process on a menu. End users can only run the processes that their security classes allow.

Runtime Administration, March 10, 2010 157© 2010 Datatel, Inc.

Page 158: Envision Runtime Administration

Security: Application Security

Process Security Classes

The Denial fields show the list of classes which are not permitted to use the process.

The Access Only fields show the list of security classes that have exclusive (privileged) rights to use the process. If a user does not belong to one of the listed classes, the user cannot run the process.

The Inquiry Only fields show the list of security classes that may only use the process in inquiry mode. Users belonging to any class in this list can view the data, but cannot change it.

Field Security Classes

The Secure Fields fields show the list of fields in the selected process that have some form of field security.

The Denial field shows the security classes which are not permitted to view or edit the contents of the selected field.

The Access field shows the security classes that have read/write access to the selected field.

The Inquiry field shows the security classes that have read-only access to the selected field. Users in these classes can view the contents of the selected field, but cannot change it.

The No Change field shows the security classes that are not permitted to change the contents of the selected field.

The No Delete field shows the security classes that are not permitted to delete the selected field.

Note: An empty list implies all classes.

Technical Tip: This list is derived from the application’s SECLASS file.

158 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 159: Envision Runtime Administration

Using the Process Security Summary (PSCS) Form

Using the Process Security Summary (PSCS) Form

Use the Process Security Summary (PSCS) form to generate a security-related report for a process you specify.

Figure 30: Process Security Summary (PSCS) Form

This report contains the following sections:

Section 1: Security Classes Referencing the Process

Lists all the security classes that reference this process, and identifies the manner in which they reference it.

Runtime Administration, March 10, 2010 159© 2010 Datatel, Inc.

Page 160: Envision Runtime Administration

Security: Application Security

Section 2: Process Access Points

Lists all the Access Points related to the process (that is, from where can this process be accessed, and to what other forms does it allow access?). This contains several subsections:

Subsection 1: MENUS - Menus on which this process appears.

Subsection 2: Forms FROM - Forms that detail to this process.

Subsection 3: Forms TO - Forms that this process can detail to.

This includes all forms that are either directly or indirectly accessible, starting from the primary form.

For example, the call statement may be in a block of code shared by many forms (for example, in an insert file, or in hook code of a demanded CDD element), and the conditions that allow it to execute might occur only in some of those forms. Another possibility is that the conditions that allow it to execute may depend on environment parameters (For example, it may depend on the list of modules your institution has licensed, or how your system parameters are set up).

Section 3: User Access Rights

If you specify that you want to see access rights for certain users, this section lists all the security classes associated with the users, and displays the type of access the users have (No access, Full access, Inquiry only, etc.) for the process being reported on.

Note: The list of forms shown in the Forms FROM and Forms TO subsections may be larger than is possible at your institution. This is true because a call to a detail form is often executed conditionally, and it may be that the conditions that allow it to be executed will never occur.

Note: If you are reporting on a procedure that may be accessed by both its mnemonic and its procedure name (such as CSRP in ST, which may also be accessed via CRJ011), then an additional Section is produced for the CRJ011 procedure access.

160 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 161: Envision Runtime Administration

Using the Process Security Summary (PSCS) Form

Noteworthy Fields on the PSCS Form

The fields described in this section are important for generating a security-related report for a process you specify.

Process

In the Process field, specify a form or procedure for which information is wanted. You can specify it as either a mnemonic or a process ID. To specify a mnemonic, prefix the mnemonic with “;M ”. For example, to specify CORE's Name and Address Entry (NAE) form, enter one of the following:

;M NAE

DMSU22

Show User Access Rights for

In the “Show User Access Rights for” field, select one of the following options if you want to include a “User Access Rights” section on the report:

All Users. Displays access rights for all users.

Users with Access. Displays access rights for all users with access.

Selected Users. Displays access rights for only the users you specify.

You can also select No Users to exclude the “User Access Rights” section from the report.

User

If the “Show User Access Rights for” field has been set to Selected Users, use this field to limit the report to show access rights for only those users you specify.

Runtime Administration, March 10, 2010 161© 2010 Datatel, Inc.

Page 162: Envision Runtime Administration

Security: Application Security

Procedure for Using the Process Security Summary Report

Step 1. Access the PSCS form.

Step 2. In the Process field, enter the form or procedure for which you want information.

Step 3. In the “Show User Access Rights for” field, select the option for this report. If you choose Selected Users, continue with Step 4; otherwise, skip to Step 5.

Step 4. In the User field, specify the users for whom you want to access rights to be displayed on this report.

Step 5. Save from the PSCS form.

162 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 163: Envision Runtime Administration

Using the Process Security Summary (PSCS) Form

Example of the Process Security Summary Report

July 02 2009 Process Security Summary Report Page 1 Procedure CSRP (Cash Receipt Print)=================================================================================Mnemonic...: CSRP / CRJ011Process....: CRJ011Application: STType.......: Procedure---------------------------------------------------------------------------------

Section 1: Security Classes Referencing the Process ---------------------------------------------------

Appln Class Usage------ -------------------- -----------------------------------------------------ST ALLOW.CRJ011 Do Only TheseST ALLOW.CSRP Do Only TheseST BLOCK.CRJ011 Never Do TheseST BLOCK.CSRP Never Do These

July 02 2009 Process Security Summary Report Page 2 Procedure CSRP (Cash Receipt Print)================================================================================= Section 2: Process Access Points --------------------------------

Access Points, Subsection 1: MENUS (Menus on which CSRP appears)

Appln Menu------ --------------------------------------------------------------------------ST CR - Cash Receipts

Access Points, Subsection 2: Forms FROM (forms that can detail to CSRP)

Appln Form------ -------------------------------------------------------------------------- < none >

Access Points, Subsection 3: Forms TO (forms that CSRP can detail to)

--------------------------------------------------------------------------------- < none >

Runtime Administration, March 10, 2010 163© 2010 Datatel, Inc.

Page 164: Envision Runtime Administration

Security: Application Security

July 02 2009 Process Security Summary Report Page 3 Procedure CSRP (Cash Receipt Print)================================================================================= Section 3: User Access Rights for CSRP --------------------------------------

User Access Rights / Security Classes- --------------------------------- ---------------------------------------------F GUEST1 - GUEST 1 ................ Full access > ADMIN, ADMIN.1, GL.ADMIN, BUDADMIN, FA.ADMIN,

> AP.ADMIN,PU.ADMIN, HR.ADMIN, PC.ADMIN

July 02 2009 Process Security Summary Report Page 4 Procedure CSRP (Cash Receipt Print)================================================================================= Section 4: User Access Rights for CRJ011 ----------------------------------------

User Access Rights / Security Classes- --------------------------------- ---------------------------------------------F GUEST1 - GUEST 1 ................ Full access > ADMIN, ADMIN.1, GL.ADMIN, BUDADMIN, FA.ADMIN,

> AP.ADMIN,PU.ADMIN, HR.ADMIN, PC.ADMIN

164 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 165: Envision Runtime Administration

Security

Record and Field Security

Security LayersRecord and field security are two additional layers of security available in Envision-based software. They add a layer of complexity to your system so it is best to keep the setup as simple as possible. Processes that are programmed in Envision are currently the only processes that use record and field security.

Record SecurityEnvision Runtime’s Record Security allows you to limit the access to a class of records in a file. Within the records that you wish to secure, there is usually a value or values which either uniquely define the record or place the record in a selected subset that includes records with the same value or values. For example, a file called EMPLOYEES has a field called POSITION.CODE. This field contains a value from a finite set of position codes. This field can be used to break the records in the file into subsets, where each subset of records has the same POSITION.CODE value.

User Characteristics

Record Security in Envision is based on defining user characteristics. Each user characteristics is named and has associated with it an algorithm for determining a value. The algorithm requires:

File name

The field in that file to retrieve

The key to use when reading a record from the file.

Example: If you have a non-Envision file called USERS, which contains information about each user who can login to the system. Each USERS record is keyed by the user’s login ID. In the USERS file is a list of position codes that the user is allowed to view on an employment information form. You can then define user characteristics which evaluate to the user’s accessible employment codes.

Runtime Administration, March 10, 2010 165© 2010 Datatel, Inc.

Page 166: Envision Runtime Administration

Security: Record and Field Security

Evaluation by Envision Runtime

Envision Runtime evaluates each of the user characteristics defined when a user enters an Envision-based application. This evaluation provides Envision Runtime a list of user characteristic names and their associated values. For example, the user ADMIN logs in and enters the Envision-based application “XCF”. The system administrator has defined four user characteristics: ACCESS.POS1, ACCESS.POS2, ACCESS.POS3 AND ACCESS.POS4. In the USERS file are four fields, each of which contains a position code for which the user may access EMPLOYEE records. These four fields contain “MGT”, “CLERK”, “STAFF” and “AIDE”, respectively. Envision Runtime assigns these values to the ACCESS.POS characteristics in order: ACCESS.POS1 is “MGT”; ACCESS.POS2 is “CLERK”; ACCESS.POS3 is “STAFF”; and ACCESS.POS4 is “AIDE”.

Whenever a user tries to access a record in a file for which there is a record security definition, Envision Runtime evaluates the definition against the characteristics values to determine if the user can have access to the requested record. A record security definition is comprised of selection-like criteria. For example, the EMPLOYEES file has the following record security definition:

WITH POSITION.CODE EQ ACCESS.POS1 A

OR

POSITION.CODE EQ ACCESS.POS2 A

Envision Runtime compares the characteristic values in ACCESS.POS1 and in ACCESS.POS2 against the data stored in the POSITION.CODE field. If each of the record security criteria are true, the user has “A”, or “All”, access to the record. If either of the record security criteria is false, the user does not have access to the record, assuming no other record security criteria are defined.

Guidelines for Specifying Record Security

As with all Envision security, keep the definition of record security simple. They provide better Runtime performance and are easier to understand and troubleshoot.

Step 1. Keep the number of records you secure to a minimum. Use field and/or process security to keep users from seeing sensitive data if possible.

166 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 167: Envision Runtime Administration

Record Security

Step 2. For those cases that warrant or require record security, identify the field or fields that can be used to classify records in the secured file into groups. Usually status fields or code fields make the best candidates. Envision-based files also have fields identifying the operator who created the record and the operator who last changed the record. These fields are also good choices for the security criteria comparison field.

Step 3. Store the values for the user characteristics in one file, if possible. As system administrator, you can add an additional level of security to this file by securing it from the operating system so that users may use or view the data in the file but cannot change it.

Step 4. When specifying more than one security criteria for a security definition, remember that the criteria are evaluated one at a time for single record access and are concatenated when accessing more than one record. The highest access calculated for a single record request is the access the user gets. When more than one record is accessed, Envision Runtime performs a security selection before the user even knows about the records available.

Step 5. Secured files can use fields from a co-file (the selection file) as the security criteria comparison field.

Step 6. Changes to user characteristics do not take effect until Envision is re-initialized.

Step 7. Changes to record security definitions do not take effect until Envision is re-initialized.

Defining Record Security User Characteristics

Use the Record Security User Characteristics (RSUC) form to define characteristics for each user. This form also allows you to see the values Envision Runtime would use for you, the current user.

The first step to define Envision Runtime Record Security is to determine where the data about each user is stored. The RSUC form requires a file and a record key in order to extract data for a user characteristic. As an example, let’s see how you would specify the user characteristics from the previous example.

Runtime Administration, March 10, 2010 167© 2010 Datatel, Inc.

Page 168: Envision Runtime Administration

Security: Record and Field Security

The first field on the RSUC form is a window field in which you enter the definition for each user characteristic. Begin by naming the user characteristic. The name can be whatever meaningful string you want. For the current example, enter “ACCESS.POS1”.

The next field in the window is the file from which to read the specified record. This file must be defined as a file in the VOC file, but does not need to be a file defined using Envision. For the current example, enter the name of the non-Envision file “USERS”.

The next two fields in the window are used to specify which field in the file contains the data we need. One prompts for the field name, the other for the field’s position in the file, or attribute number. If you are using a non-Envision file, you must specify the attribute number, since Envision does not know what fields are in the file. If you are using an Envision-based file, you may specify either the field name or the attribute number. For the current example, Return through the field name prompt and enter “1” at the attribute number prompt.

The last field in the window determines how the key for reading the record is derived. There are four options for specifying the key derivation:

1. A keyword

2. A constant

3. A function expression

4. A previously defined Parameter Definition name.

Keywords

Following is a list of the valid keywords recognized for parameter definition key derivations. Each keyword must be prefixed with an at-sign, @:

DEVICE.NAME. The user’s current device type

USERID. The user’s login ID

APPL.NAME. The current application

STARTUP.PROCESS. The menu or process the user runs upon entering current application

TERMINAL.USER. Whether the current user is terminal user (1) or a background process (0)

168 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 169: Envision Runtime Administration

Record Security

Constants

Constants are enclosed in either double or single quotation marks and are evaluated literally. Record Security characteristics defined with constant key derivations are, by definition, the same for each user on the system.

Function Expressions

In order to enter or modify a Function Expression, detail at a blank line at the end of the list of the User Record Security Characteristic Definitions to run the Key Derivation Function form.

Prompts for this form vary depending on the Key Derivation Function you choose. The valid Key Derivation Functions are:

Concatenation. Concatenate two definitions separated by a delimiter

Field Extraction. Choose a part of a multi-part key using a delimiter to determine which part

Substring Extraction. Specify the start character and string length for the substring

Previously Defined Parameter Definitions

You can use any parameter definition name already defined in specifying a key derivation or alone as a key.

To begin the user characteristic specification, it is best to use a keyword. For the current example, enter [[@USERID]] to request the current operator’s login ID as the key to the file for the first user characteristic.

For the current example, Envision Runtime will evaluate this characteristic to the value in Field 1 of the record keyed by the operator’s login ID from the file USERS.

Assuming that the other ACCESS.POS values are stored in consecutive fields in a USERS record, the other three user characteristics would differ only by the attribute numbers entered.

Runtime Administration, March 10, 2010 169© 2010 Datatel, Inc.

Page 170: Envision Runtime Administration

Security: Record and Field Security

In the current example, each field in a USERS record contains a single code. You may define user characteristics that evaluate to more than one value. These values would be stored as a separated list. Envision Runtime recognizes the following list separators:

Value Marks

Single Quotation Marks

Double Quotation Marks

If you use either of the quotation marks as value delimiters, the list of values must also begin and end with the same quotation marks. Multi-valued lists, that is, each value separated by a value mark, need only have delimiters between values.

More complicated user characteristics use Key Derivation Functions to generate more complex record keys. For example, the file USERS contains special records that allow different access codes when a user enters different applications. These special records are keyed by the concatenation of the user’s login ID and the application he has entered. The key derivation in this cause would concatenate @USERID with @CURRENT.

APPLICATION with an asterisk (*). Similar modifications to either keywords or previously defined user characteristics allow you to link user characteristics together to form complex and intricate chains of records and characteristic values. Remember, however, that Envision Runtime must evaluate these chains, at the expense of Runtime performance.

A user can re-initialize the Envision environment by:

Leaving the database environment entirely and returning

Logging off the system and starting the login procedure over again

Returning to the database environment prompt and executing the Envision initialization program ENVINIT.

Note: Remember that changes or additions to the current user characteristics do not take effect until a user re-initializes the Envision environment.

170 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 171: Envision Runtime Administration

Record Security

Record Security Definitions

Record Security Definitions are selection-like statements that determine if a user can have access to a requested record. There are three levels of access a user may have:

1. All access. The user has the highest access available for the process from which he requests the record.

2. Inquiry access. The user may view data in the record for the process from which he requests the record.

3. No access. The user is denied access to the record for any purpose for the process from which he requests the record.

For maintenance forms, the highest access to a record is all access, where the user can add, modify, delete and view any data on the form.

For inquiry forms, reports, procedures and Query-by-Example, the highest access to a record is inquiry, where the user can only view the data.

A user has no access to a record when he fails to have inquiry access or all access. For example, a user who has all access to a record can change data on a maintenance form and view data on a report. A user who has inquiry access can only view data on both a maintenance form and a report. If the criteria are such that a user has neither all nor inquiry access, the user has no access to the requested record.

For each file containing records you wish to secure, specify a Record Security Definition on the Record Security Specification (UTMR) form.

UTMR allows you to base record security on either data in the current record or data in a record from a co-file. A co-file is a file that contains data different from the current file, but records in each file are keyed the same and the data in each file, while different, is related. The first field on the UTMR form allows you to specify a co-file to use in comparing the values in the record to the values of the user characteristics. For example, you wish to secure a file called PAYROLL, which contains payroll information for employees, keyed by the employee’s ID. The field which determines whether a user can view the data stored in the PAYROLL file is the field POSITION.CODE in the EMPLOYEES file. To tell Envision Runtime to use the field POSITION.CODE in the EMPLOYEES file when checking the user’s access to a record in the PAYROLL file, enter “EMPLOYEES” as the select file on the UTMR form. The default for this field is the secured file.

Runtime Administration, March 10, 2010 171© 2010 Datatel, Inc.

Page 172: Envision Runtime Administration

Security: Record and Field Security

The next field on UTMR is a window field for the specification of the security criteria for this definition. Each criteria has a connective, a comparison field, a comparison operator, a comparison value and the resulting access. There are three valid connectives:

WITH - and WITH

AND - and WITH

OR - or WITH

As you can see, the WITH connective is an implied “and WITH”. For single record access from a form process, Envision Runtime evaluates all the criteria. The highest access code for that criteria that are true determines the user’s access to the record. For example, four criteria are defined, two of which are true for the current record. One has an access code of “I”, the other “A”. The user will have “All” access to the record since “A” access is higher than “I” access.

For access to more than one record (for example, a report, a resolution form or a selection), Envision Runtime uses the security criteria to narrow the range of records before any other selection takes place. Each of the security criteria is used in building the security select statement. The connectives are used to concatenate the criteria into a single select statement. This pre-selection of records prevents the user from even knowing about records for which he has no access.

Returning to the UTMR form, the second field in the window is the name of a field in the selection file. The name of any valid field from the file you have specified as the selection file is a valid entry for this field. For the example stated above, the connective for your security criteria is “WITH” and the field name is “POSITION.CODE”.

172 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 173: Envision Runtime Administration

Record Security

The next field in the window is where you enter the comparison operator for the security criteria. Here is a list of the valid comparison operators for this field:

NE Not Equal

EQ Equal

LT Less Than

EQ Equal

LE Less than Equal

GE Greater than Equal

EQ Equal

GT Greater Than

LE Less than Equal

GT Greater Than

GE Greater than Equal

LE Less than Equal

GT Greater Than

LT Less Than

GE Greater than Equal

LT Less Than

GT Greater Than

NE Not Equal

LT Less Than

NOT Not Equal

The next field in the window is for the comparison value. The value stored in the comparison field against the comparison value using the comparison operator, yielding either true or false. The comparison value has three valid formats:

A user characteristic defined on RSUC

A keyword

A constant enclosed in quotation marks

Your entry here is validated. Keywords begin with an asterisk, constants begin with quotation marks. Anything else is considered a user characteristic and is validated against the list of user characteristics defined on RSUC. Continuing the above example, enter “ACCESS.POS1” in comparison value field to compare POSITION codes with the value of ACCESS.POS for the current user. If you specify constants in the comparison value field, the same test is used for all users. If a user fails the test, he does not have access to the record. If he passes the test, he has the access specified. All users will have access to the same records and will be denied access for the same records.

Runtime Administration, March 10, 2010 173© 2010 Datatel, Inc.

Page 174: Envision Runtime Administration

Security: Record and Field Security

The final field in the window is for the access code the user gets when he passes the security criteria. There are only two valid entries; “A” for all access or “I” for inquiry access. A user does not have access to a record if he does not have either “all” nor “inquiry” access.

The final field on the UTMR form is a “Yes” / “No” field prompting if you wish to activate the security definition. You list all of your criteria and leave them turned off if you wish to do some research. Until you enter “Yes” in this last field, record security for the current secured file is disabled.

A user can re-initialize the Envision environment by:

Leaving the database environment entirely and returning

Logging off the system and starting the login procedure over again

Returning to the database environment prompt and executing the Envision initialization program ENVINIT.

Note: Remember that changes or additions to the current record security definition do not take effect until a user re-initializes the Envision environment.

174 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 175: Envision Runtime Administration

Field Security

Field SecurityEnvision Runtime Field Security allows you to control the access that certain classes of users can have to the data stored in specified fields. Only data elements delivered with an Envision-based application can be secured by Envision Runtime. Field Security works not only with form processes, but procedures, reports and Query-by-Example (QBE) also obey field security definitions.

Envision Runtime merges Process Security and Field Security so that the user has the most restrictive access to the data in the field possible. For example, a user is a member of a security class that restricts a form process to “Inquiry Only” access. The user is also a member of a class that restricts a field to “Privileged” (see below). Since “Inquiry Only” is more restrictive than “Privileged”, Envision Runtime merges the two classes so that the user has “Inquiry Only” access to the data in the field. Another example has a user executing a form for which he does not have process security restrictions. A field on the form, however, is secured so that the user is denied access. Envision Runtime displays asterisks (*) in place of the data so that the user cannot even see the data for which he is denied access.

Defining Field Security

To define Field Security for Envision Runtime, run the Field Security Definition (SCDF) form.

The first field on the SCDF form prompts you for a security class. You may use an already-defined security class from the Security Class Definition (SCD) form or you may create a new security class. Field Security is simply another attribute of a security class. A new security class you define on the SCDF form may be assigned to operator definitions and device definitions. Field Security class definitions are stored in the appl.SECLASS file just as other security class definitions are. Enter the name of the security class with which you wish to work or use the LookUp Processor to retrieve a name.

The second field on SCDF is a text window where you can describe the security class you entered in the last field. If you are creating a new security class, enter free-form text documenting the use and restriction of the new security class. If you are using an existing security class, the previously entered description displays in this window.

Runtime Administration, March 10, 2010 175© 2010 Datatel, Inc.

Page 176: Envision Runtime Administration

Security: Record and Field Security

The third field on SCDF allows you to detail to the Security Class Definition (SCD) form.

The next field on SCDF is a window field where you specify the fields for the security class and the restrictions on those fields for users in the class. Enter the name of the field or fields you want to restrict, or use the LookUp Processor to retrieve the name. For each field you restrict, you must specify a code defining the restriction. Below is the list of valid restriction codes:

P - Privileged Access. User must be a member of this class to have any access to the data in the field

PI - Privileged Inquiry. User must be a member of this class to be able to view the data in the field; can only view; cannot modify

PM - Privileged Modify. User must be a member of this class to be able to modify the data in the field; cannot add new data

D - Denied Access. Users in this class do not have access to the data in the field

I - Inquiry Only. Users in this class can only view the data in the field; cannot modify data

M - Modify Data Only. User in this class can only modify the data in the field; cannot add new data

As mentioned before, Field Security is honored by all Envision-based processes in the application. Remember than, since the Field Security definitions are stored in the Application file SECLASS, Envision Runtime checks the current application and all applications in the current application tree for security class definitions.

176 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 177: Envision Runtime Administration

Updating and Maintaining Security

Updating and Maintaining SecurityThe Envision Release system, the Envision Toolkit, and Colleague Studio have been enhanced to keep mnemonic, field, and record security up-to-date as soon as a mnemonic is changed, or a form or reporting process is either installed or generated, or a security class is changed on the Security Class Definition (SCD), Field Security Definition (SCDF), or Record Security Setup (SCDR) forms.

If you add or change a mnemonic on a UI or web form, or on a process flagged as a report, any existing security class that may already have the old and/or new mnemonic will immediately be updated by the mnemonic change. These changes are monitored on the Screen Process Definition (SCRN), Batch Global Parameters (BGP), External Global Parameters (EGP), and Screen Global Parameters (SGP) toolkit forms; as well as when exporting (or checking custom code in) via Colleague Studio for UI form processes, web form processes, and report processes.

Also, if a developer adds a field (such as SSN) to a UI form, web form, or report process, and the field is secured by an existing field security definition; then when the process is generated (and the field is added to the newly generated process), the field security for the new process will updated to reflect the existing field security.

In addition, as software updates are installed into an environment (either Datatel-delivered updates or custom software update packages), the Release System will track each modified UI/web/report process definition record installed and update its corresponding mnemonic, field and record security. This means that any new software being installed will immediately be aligned with the environment’s defined Envision security.

Technical Tip: You must run the Build Application Security (BSEC) process to rebuild all Envision security for an entire application if any of the following conditions arise: – Mnemonics or field changes are made outside Envision and Colleague Studio. – Envision object code is installed outside the Envision Release System. – Immediately after a new Colleague environment is built (see Installation Procedures for Colleague R18). This should be done on a quiet system, as the BSEC process clears the security information, and then rebuilds it, one security class at a time.

Runtime Administration, March 10, 2010 177© 2010 Datatel, Inc.

Page 178: Envision Runtime Administration

Security: Record and Field Security

178 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 179: Envision Runtime Administration

Security

Encrypting Colleague Data

In This ChapterThis chapter provides information on the encryption capabilities available for Colleague processes.

Table 6 lists the topics covered in this chapter.

Before You BeginTable 7 lists the actions that must be complete before you can continue with the procedures in this chapter.

Table 6: Topics in this Chapter

Topic Page

Before You Begin 179

Understanding Colleague Encryption 180

Defining Colleague Encryption 183

Troubleshooting 185

Table 7: Before You Begin

Action Reference

Live on UniData 6.1 or higher. The encryption schemes used by Colleague are not available in earlier UniData versions.

Load software updates for Colleague encryption.

AnswerNet document 16990.15.

Runtime Administration, March 10, 2010 179© 2010 Datatel, Inc.

Page 180: Envision Runtime Administration

Security: Encrypting Colleague Data

Understanding Colleague EncryptionIn cryptography, encryption is the process of obscuring information to make it unreadable without special knowledge. The “special knowledge” includes which encryption algorithm is used and what encryption key was used to encrypt the data. Either piece of information is useless without the other, because proper decryption cannot occur without both the encryption algorithm and the encryption key. An encryption scheme is comprised of the encryption algorithm and the encryption key.

Determining which encryption scheme to use will depend on your institution’s particular needs. You may have to meet certain minimum requirements for encryption in order to process credit card transactions, for example.

Encryption Algorithm and Encryption Key

An encryption algorithm is a formula used to turn ordinary data into a secret code, sometimes referred to as ciphertext. Each algorithm uses a string of bits known as an encryption key to perform the translation from regular data to encrypted data. The larger the key (the more bits), the greater the number of potential patterns can be created, thus making it harder to break the code and descramble the contents.

For example, two encryption algorithms available in Colleague are R2-40-CBC, which is 40-bit strength (a 40-bit key), and R2-CBC, which is 128-bit strength (a 128-bit key). Roughly speaking, 128-bit encryption is 309,485,009,821,345,068,724,781,056 times stronger than 40-bit encryption.

Colleague has several encryption schemes available from which you can choose. These encryption schemes are determined by the encryption schemes supported in UniData 6.1 and later. For more information about the encryption scheme choices, see the UniData manual, UniBasic Extensions, particularly the “Encrypting Data” section.

Technical Tip: Due to the amount of terminology and dense concepts regarding cryptography, interested readers may refer to the following publications: Applied Cryptography by Bruce Schneier, and Internet Cryptography by Richard E. Smith. Both publications expound upon the UniData documentation and the encryption schemes supported by UniData.

180 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 181: Envision Runtime Administration

Understanding Colleague Encryption

Key Concepts

There are several key concepts of which you need to be aware when implementing Colleague encryption:

“Quiet” system. Change your encryption scheme only during a period of no database activity. If queries are made to the database for elements that are currently being encrypted, your users will encounter runtime errors and you will corrupt your database.

Back up your database. Because you are manipulating data into an encrypted format, if something goes wrong the data most likely would be unrecoverable. It is very important to back up your database before implementing encryption, as well as when changing your encryption scheme.

Encryption process runs immediately. If you change either the encryption scheme or the encryption key, a batch re-encryption process is immediately started after saving from the UT Encryption (UTEP) form. The process cycles through all of the fields listed in the Encrypted Fields Registry table, converting them from the previous encryption scheme to the new encryption scheme.

Form Used

Table 8 lists the form used in this section and a description of the form.

Table 8: Form Used to Implement Colleague Encryption

Form Purpose

UT Encryption (UTEP) Define the encryption scheme used to encrypt predefined CDD elements.

Runtime Administration, March 10, 2010 181© 2010 Datatel, Inc.

Page 182: Envision Runtime Administration

Security: Encrypting Colleague Data

File Used

Table 9 lists the primary file used with Colleague encryption.

Table 9: File Used with Colleague Encryption

File Description

EDPARMS Stores data from the UTEP form, including encryption scheme and encryption status information.

182 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 183: Envision Runtime Administration

Defining Colleague Encryption

Defining Colleague EncryptionFigure 31 shows an example of the UT Encryption (UTEP) form, available from the UT application. Use the UTEP form to change encryption parameters and to start the encryption process.

Figure 31: The UT Encryption (UTEP) Form

Noteworthy Fields on the UTEP Form

The fields described in this section are particularly important for using Colleague encryption. See online help for information about other fields on this form.

The “Status” Field

Note: The “Status” field refers to the large, unnamed informational field at the top of the UTEP form.

Runtime Administration, March 10, 2010 183© 2010 Datatel, Inc.

Page 184: Envision Runtime Administration

Security: Encrypting Colleague Data

The “Status” field is a single block of inquiry-only status information. It indicates whether the system believes that the batch re-encryption process is running, and provides additional instructions and warnings.

Under normal circumstances, the status will show INACTIVE. This status means the re-encryption process is not running. If the encryption process appears to be running, the status will show ACTIVE, and the entire form will be inquiry-only.

If you believe that the status of ACTIVE is erroneous because the batch process aborted, see “Troubleshooting” on page 185 for more information.

The Encrypted Elements Registry Field

The data elements listed in the Encrypted Elements Registry field are the elements that the system will update whenever you change your encryption scheme.

Procedure for Changing an Encryption Parameter

Use this procedure to change the encryption scheme or encryption key.

Step 1. Back up your database.

Step 2. Access the UT Encryption (UTEP) form.

Step 3. Do you want to change the encryption scheme?

Yes. In the Encryption Algorithm field, choose the encryption algorithm you want to use. Changing the encryption algorithm will also change the encryption key.

No. Skip to Step 5.

ALERT! Before changing the encryption scheme or key, you must make sure your database is not currently in use. Failure to do so can result in database corruption.

184 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 185: Envision Runtime Administration

Troubleshooting

Step 4. Save from the UTEP form. The batch encryption process starts as soon as you save from the UTEP form. You are finished with this procedure.

Step 5. If you want to change the encryption key, enter Yes in the Reset Key field.

Step 6. Save from the UTEP form.

TroubleshootingThe UT Encryption (UTEP) form is designed with a “must run perfectly” philosophy. Before starting to process data records, the UTEP process does extensive validations of the EDPARMS parameter record. Everything about the record must be correct before the process starts. If anything unusual is detected, the process throws an error and then ends. The error is logged to the UT.THROWN.ERRORS file. Errors are also logged if the encryption process encounters anything wrong while processing.

If the encryption process aborts gracefully (it is able to detect a problem, throw the error, and shut down), then it will write ABORTED into the EDPARMS.CONV.IN.PROGRESS field of the EDPARMS parameter record. This allows the UTEP form to recognize that the encryption process aborted, and enables the process to attempt a graceful restart when the UTEP form is saved.

Figure 32: Example of the UTEP Form with an ABORTED Status

If the encryption process aborts in any other way, then the system administrator will have to edit the parameter record and change that field to ABORTED in order to be able to get the process to continue.

Runtime Administration, March 10, 2010 185© 2010 Datatel, Inc.

Page 186: Envision Runtime Administration

Security: Encrypting Colleague Data

Troubleshooting a Failed Encryption Process

An aborted encryption process can leave the UTEP form in two states:

ABORTED. The encryption process aborted cleanly and will resume from where it stopped after the UTEP form is saved.

ACTIVE. If the encryption process has thrown an error (logged to the UT.THROWN.ERRORS file) but did not abort cleanly, the UTEP form will believe that the process is still running, and will return the current status as ACTIVE.

If the UTEP form displays the encryption status as ABORTED, fix the problem (refer to the error in the UT.THROWN.ERRORS file), and then simply save from the UTEP form. The encryption process will resume from where it stopped. Restarting the encryption process when the UTEP form believes it is currently running (the UTEP form displays a status of ACTIVE but the encryption process has thrown an error and aborted) is a bit more tricky.

In order to restart the encryption process when the UTEP form believes it is still running, you must first determine what the problem is, and then correct that problem. Refer to the error in the UT.THROWN.ERRORS file to determine the problem. After the problem is fixed, edit the value of the EDPARMS.CONV.IN.PROGRESS field to ABORTED. This will cause the UTEP form to recognize that the encryption process has aborted, and will invoke the encryption process to resume when you save from the UTEP form.

ALERT! Datatel strongly recommends contacting the Solution Center for assistance to restart the encryption process when it does not abort cleanly.

186 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 187: Envision Runtime Administration

Runtime Administration

Maintenance

Page 188: Envision Runtime Administration
Page 189: Envision Runtime Administration

Maintenance

Maintenance Introduction

This chapter covers the overall maintenance tasks that you must perform for a Colleague site. A sample schedule is provided for system maintenance along with DBMS tasks.

Guidelines for purging files and handling duplicate records is provided along with the purpose of the utility programs and directions for running.

Policies for upgrading releases and the background information for Colleague release loads are outlined.

Scheduling System MaintenanceScheduling system maintenance is a challenge and differs from site to site. Below is an example of how one site handles their maintenance activities. The maintenance activities include:

Saves

Consolidation of job histories

Purges

Disk maintenance

Saves

Saves or backups should be performed daily. There are two types of saves:

Full backups. Save everything in a requested partition or directory whether it has changed since the last save or not.

Incremental backups. Save just the files and directories that have changed since the last full save. See your operating system documentation for information on performing saves.

The example site recommends that you perform a full save everyday on your partition that contains Colleague data files. This allows you to easily recover an account without having to restore your full save and then overlaying it with each incremental save performed since. This recommendation, however, depends on your manpower, machine and tape resources.

Runtime Administration, March 10, 2010 189© 2010 Datatel, Inc.

Page 190: Envision Runtime Administration

Maintenance: Maintenance Introduction

Consolidation of Job Histories

Many programs create job histories or como files to record events during execution to disk. Batch or background mode processes in Colleague and the data base management system create these files in the PH file of the current directory. These files take up considerable disk space over time and should be deleted. You may wish to keep them in a consolidated file for future reference.

The example site collects all of the como files from its directories and appends them together, with headers, in one file for future reference, and then deletes the original form the PH directory.

Purges

Reports run to the HOLD file, SAVEDLISTS generated by programs or users, command stacks, and temporary files accumulate over time and use additional disk space. Purge these files periodically. See Chapter Purging Files in this manual for additional information.

The example site uses the following guidelines and naming conventions in deciding which files to purge:

The HOLD file is archived daily and all records in it are deleted.

Any savedlist or command stack that hasn’t been modified for a month is deleted, unless it is named, “PERM.xxx”.

Temporary files beginning with “T$...” are deleted.

Disk Maintenance

Each operating system provides disk maintenance utilities that you should perform according to your vendor’s recommendations. Typically, you run these after a full backup.

190 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 191: Envision Runtime Administration

Sample Daily Schedule

Sample Daily ScheduleBelow is the example site’s daily schedule.

Notes1. It is very important you run the processes in the order listed and only if the

previous process completed successfully. This ensures that files are saved to tape before deletion.

2. Run each process early in the morning on the day indicated before allowing users on the system. Perform the full save and disk maintenance at any convenient time on the weekend. Be sure to perform the save before running the disk maintenance utilities.

3. Do not allow users should not be on the system while these processes are running.

4. These processes may be run interactively in the foreground by an operator with a como file on, or in the background with a batch monitor with cyclic features such as Batchmaster, or submitted daily to a batch queue by an operator.

Table 10: Sample Daily Schedule

Sample Daily Maintenance Schedule

DaysTime and Task performed

3:00 am 5:45 am 6:00 am

Monday Incremental save Job history Purge

Tuesday Incremental save Job history Purge

Wednesday Incremental save Job history Purge

Thursday Incremental save Job history Purge

Friday Incremental save Job history Purge

Saturday Full save Job history Disk maintenance

Runtime Administration, March 10, 2010 191© 2010 Datatel, Inc.

Page 192: Envision Runtime Administration

Maintenance: Maintenance Introduction

192 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 193: Envision Runtime Administration

Maintenance

Using File and Index Analysis Utilities

In This ChapterThis chapter provides information about file and index analysis utilities for UniData. There are two utilities that are external UT programs to Envision that can help you to maintain your system:

WEEKLY.UDT.FILE.ANALYSIS (WUFA)

WEEKLY.UDT.INDEX.ANALYSIS (WUIA)

Although these utilities are most beneficial to institutions using UniData, institutions using SQL Server or Oracle should also run the utilities. There are some application server files that always reside in UniData that should be analyzed regularly through these utilities.

For example, UT.THROWN.ERRORS is an application server file that contains errors programatically invoked when an unusual and/or fatal event occurs. If this file grows too large, the WUFA utility will set up a resize for the file. Similarly, if indexing on that file is corrupted for any reason, the WUIA utility will set up a delete, create, and rebuild of the indexes for that file.

Table 11 lists the topics covered in this chapter.

Table 11: Topics in This Chapter

Topic Page

Using WEEKLY.UDT.FILE.ANALYSIS (WUFA) 194

Using WEEKLY.UDT.INDEX.ANALYSIS (WUIA) 201

Runtime Administration, March 10, 2010 193© 2010 Datatel, Inc.

Page 194: Envision Runtime Administration

Maintenance: Using File and Index Analysis Utilities

Using WEEKLY.UDT.FILE.ANALYSIS (WUFA)

The WEEKLY.UDT.FILE.ANALYSIS (WUFA) utility assists in monitoring and maintaining the condition of your file system so that you can optimize your UniData database, and is used to analyze your data files for overflows and potential resizing. The state of your file system can have a significant impact on system performance, especially if a file is sized too small.

The WUFA utility performs the following functions:

Checks for damaged files.

Gathers file statistics for all hashed files in an environment.

Analyzes those file statistics and makes recommendations about the block size and modulo for each file in an environment. These recommendations are written to a paragraph to automate file system maintenance. You can run this paragraph after the WUFA utility finishes running.

Builds a resize paragraph to automate file system maintenance.

Estimates the disk space savings or cost that will result if you run the resize paragraph.

Builds a report paragraph with suggested update parameters.

Creates saved lists of either invalid VOC records that point to invalid files or VOC records that could not be opened.

On completion, a file analysis report will be output to the default printer. The report will be sorted in order of the condition of the files. Damaged files will be listed first, then those files that have groups in level-two overflow, then in descending order of “average bytes per group.” If a file is sized too small, it will typically have a very large “average bytes per group.”

The WUFA utility will also create a resize paragraph to simplify the task of correctly sizing your files. The resize paragraph is in the same order as the report. You should modify this paragraph to include only those files that you want to resize.

Datatel recommends that you try not to resize too many files at once, as any file being resized will be unusable until the resize is complete. Many factors determine how long a resize will take, including the size of the file, how poorly sized the file currently is, and how much memory you allocate to the command for memory resizing (memresize command).

194 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 195: Envision Runtime Administration

Using WEEKLY.UDT.FILE.ANALYSIS (WUFA)

Output Items from the WUFA Utility

When you run the WUFA utility, the following five output items are created:

UDT_GUIDE. This file contains all of the file statistics for all hashed files in the environment where the WUFA utility is run.

If you want to use your own formula to calculate the correct modulo/block size, you can use the statistics in this file. This file is cleared and repopulated every time that you run the WUFA utility.

UDT_GUIDE.RPT. This report paragraph is run on completion of the utility. This report may be used as an example for any other reports that you might want to build from the UDT_GUIDE file.

DATATEL.RESIZE.FILES. This paragraph will only resize those files that require resizing. The first time that you run the WUFA utility, a number of files may need to be resized. After subsequent scans, only those files that have changed significantly in size since the last resize will be included in the paragraph. Further, after running this utility several times, you will begin to see which files tend to change in size as they will migrate to the top of both the file statistics report and the resize paragraph.

BAD.FILES.IN.VOC. A saved list of files that could not be opened using their existing VOC pointer. This list is provided for your convenience in cleaning up your VOC file.

BAD.VOC.FILES. A saved list of logical view files that could be opened with their logical name, but could not be opened with their physical name. This could be due to a bad physical VOC entry, or it could be due to a missing VOC entry for the physical file. For example, when trying to analyze SPOUSE (a logical view of PERSON), if the VOC entry for SPOUSE is correct, but the VOC entry for PERSON is either missing or incorrect, then the BAD.VOC.FILES saved list will be populated with both SPOUSE and PERSON.

Runtime Administration, March 10, 2010 195© 2010 Datatel, Inc.

Page 196: Envision Runtime Administration

Maintenance: Using File and Index Analysis Utilities

Workflow for Using the WUFA Utility

Datatel recommends that you run the WUFA utility weekly. You may want to consider running the WUFA utility overnight, and then review the report in the morning, or simply execute the following statement to check for any damaged files:

:LIST UDT_GUIDE FILE_NAME DATATEL.DAMAGED ID.SUP WITH DATATEL.DAMAGED GT " "

The WUFA utility also creates the paragraph DATATEL.RESIZE.FILES. For example, you might want to modify the DATATEL.RESIZE.FILES that was created on a Thursday night and run it on Friday night, after backups are completed, so that it has the entire weekend to process.

Before you run the resize paragraph, execute the following statement to find out the largest file that may need to be resized.

:LIST UDT_GUIDE BY.DSND SIZE FILE_NAME SIZE ID.SUP

If you notice that a static file is approaching 2GB, you should convert the file to dynamic since static files have a 2GB size limit. Datatel recommends leaving your files static as much as possible as they are easier to tune.

Some of the benefits of running the WUFA utility on a weekly basis are:

Fewer files go into overflow each week. When they do, there is minimal level-one overflow.

Fewer files process during the resize, allowing resizing to run quickly.

No severe level-one or level-two overflows should occur, unless you perform a massive conversion. In this case, run the WUFA utility immediately after the conversion.

Improved performance of file operations, as most files are overflow free.

Note: See AnswerNet Document 156.19 for information on how to fix damaged files.

Note: See AnswerNet document 147.992 for more information on whether to use static or dynamic UniData files in Colleague.

Note: For Colleague R18 on UniData, the WUFA utility should also be run in the Local Product Repository (LPR) as UniData files should be checked for damage and overflow there.

196 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 197: Envision Runtime Administration

Using WEEKLY.UDT.FILE.ANALYSIS (WUFA)

Running the WUFA Utility

Datatel recommends that you run the WUFA utility overnight, as a background process, by executing the following command:

:PHANTOM WEEKLY.UDT.FILE.ANALYSIS

To achieve this, you can create the following paragraph:

:AE VOC FILE.MAINT

0001: PA

0002: COMO ON FILE.MAINT

0003: DATE

0004: SELECT VOC WITH F1 LIKE ‘F...’ AND F2 UNLIKE '@UDTHOME...'

0005: WEEKLY.UDT.FILE.ANALYSIS

0006: DATE

0007: COMO OFF

The following two arguments can be appended to the WEEKLY.UDT.FILE.ANALYSIS command:

-AD

-ED

The –AD option allows a decrease in file size. The default behavior does not allow a decrease in size of a file. The reasoning for this is that if a file grew large enough to warrant its current size (such as a temporary work file), then even if its current contents are small, the file may grow large again and cause overflow problems (if resized based on its current contents). The –AD option allows you to override that default behavior and allow a decrease in file size.

The –ED option allows you to exclude dictionaries of each file from analysis. The default behavior is to analyze dictionaries of each file included. For example, when analyzing PERSON, the dictionary D_PERSON will also be analyzed. The –ED option allows you to override that default behavior and exclude analysis of dictionaries of each file.

Note: Files listed on the WebAdvisor File Maintenance (WAFM) form are not affected by this option. Running the WUFA utility on the files specified on that form will always set up a MEMRESIZE statement in DATATEL.RESIZE.FILES, based on the modulo and block size specified on the WAFM form for each file.

Runtime Administration, March 10, 2010 197© 2010 Datatel, Inc.

Page 198: Envision Runtime Administration

Maintenance: Using File and Index Analysis Utilities

To run the WUFA utility as a background process, enter the following:

:PHANTOM FILE.MAINT

To monitor its progress by scanning the COMO file, enter the following:

:AE _PH_ O_FILE.MAINT

When the WUFA utility has completed, you should review the file analysis report and the recommended block sizes and modulos. You should then modify the resize paragraph to include only those files that you actually want to resize.

The resize paragraph, DATATEL.RESIZE.FILES, has been set up to use the UniData memresize command, which is faster than the ECL RESIZE command. The memresize command uses a memory buffer and writes to disk only when the buffer is full. This causes fewer writes to disk; thus, performance can be significantly enhanced.

To run the resize paragraph, enter the following at the colon prompt:

:DATATEL.RESIZE.FILES

or

:PHANTOM DATATEL.RESIZE.FILES

DATATEL.RESIZE.FILES will turn on a COMO file called O_DATATEL.RESIZE.FILES when it is executed so that you can monitor its progress.

Disk space estimates will be displayed when the WUFA utility is finished. They will also be inserted into the resize paragraph DATATEL.RESIZE.FILES. The disk space estimates are only approximations, they do not account for overflow groups. They should give you a reasonable estimate of how much disk space you will need or get back after running the DATATEL.RESIZE.FILES paragraph.

ALERT! You must have a complete backup of your system before running the resize paragraph. If your system experiences a power failure or any other problem while it is in the middle of resizing a file, the file can be left in an incomplete or broken state. The only recourse if this happens is to restore the file from backup.

ALERT! Before running the resize paragraph, all users must log out of the system and the environment’s DMI listeners must be stopped. After running the DATATEL.RESIZE.FILES paragraph, you can restart the DMI listeners.

198 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 199: Envision Runtime Administration

Using WEEKLY.UDT.FILE.ANALYSIS (WUFA)

Note: In order to run the memresize command, you must have enough disk space within the partition where the temporary copy of the file will be created. For static files, this is the /tmp directory in UNIX or \temp in Windows. You can override this default by setting the TMP environment variable. For dynamic files, this is the same partition as the file being resized.

Runtime Administration, March 10, 2010 199© 2010 Datatel, Inc.

Page 200: Envision Runtime Administration

Maintenance: Using File and Index Analysis Utilities

Excluding Files from Analysis

You can maintain a list of files to be skipped by adding the name of each file to a SAVEDLISTS record called RESIZE.EXCLUDE. Any file name found in this list by the WUFA utility will be analyzed, but will not be included in the resize paragraph DATATEL.RESIZE.FILES. The excluded files will be flagged in the analysis report by prefixing the file name with a '*'.

:EDIT.LIST RESIZE.EXCLUDE

The VOC file will always be excluded, whether or not it is specifically included in the RESIZE.EXCLUDE saved list, as it must be resized from the operating system level (that is, outside of the UniData environment). You can look for any excluded file in the DATATEL.RESIZE.FILES paragraph to see what the recommended block size and modulo would be, and then resize the file manually. It is very important for performance to keep the VOC file sized properly.

Note: See AnswerNet Document 107.1437 for how to resize the VOC file.

200 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 201: Envision Runtime Administration

Using WEEKLY.UDT.INDEX.ANALYSIS (WUIA)

Using WEEKLY.UDT.INDEX.ANALYSIS (WUIA)

You can use the utility WEEKLY.UDT.INDEX.ANALYSIS (WUIA) to execute UniData’s guide_ndx command in order to analyze index files. The WUIA utility creates paragraphs and saved lists that you can use to clean up index files.

If cleanup is necessary, you can either use a paragraph alone, or combine a paragraph with the Multiple File Indexing (UTBA) process. If you use the UTBA process, you enter a saved list (created by the WUIA utility) to rebuild indexing for the files, then enter one of the following in the Indexing Function field:

B (Create & Build All)

M (Create & Build Missing)

You will run the WUIA utility at the colon prompt or in a VOC paragraph. Because the WUIA process does not clean up index files, it can be run on an active system. However, you should run the resulting paragraphs and the UTBA process only on a quiet system.

Understanding the WUIA Utility

The WUIA utility can be run with an active list of files you have selected, or on all files. The WUIA process will determine if each of the files has any UniData indexing associated with it. If so, any problems or corruption found with the indexing is reported.

When you enter WEEKLY.UDT.INDEX.ANALYSIS at the colon prompt or in a VOC paragraph, the default mode of the WUIA utility runs the following command on each file analyzed:

guide_ndx -x 1, ALL <file name>

In this command, the “1” triggers physical checking of the index file.

You can also enter the following:

WEEKLY.UDT.INDEX.ANALYSIS -L

Runtime Administration, March 10, 2010 201© 2010 Datatel, Inc.

Page 202: Envision Runtime Administration

Maintenance: Using File and Index Analysis Utilities

This triggers logical checking of the index file for any non-null indexed fields, by issuing this command:

guide_ndx -x 2, <list of non-null indexed fields> <file name>

In this command, the “2” triggers logical checking of the index file.

When you run this utility, the final statement shown will indicate whether or not any problem index files were found. One of the following statements will be displayed:

No problem index files found...

Saving list of problem index files in SAVEDLISTS...

Using the WUIA utility to run guide_ndx on each file will populate a GUIDE_XERROR.LIS record file with output such as shown in the following examples:

PERSON

Checking index 'SSN' physically...

Checking index 'AARS' physically...

Checking index 'D01.CUSTOM.FLD' physically...

The index has not been built yet.

or

PERSON

Checking index 'SSN' logically...

Checking index 'AARS' logically...

Checking index 'D01.CUSTOM.FLD' logically...

Index D01.CUSTOM.FLD is not built or deleted.

Whenever text appears in that report, excluding the file name and the “Checking...” phrase, the WUIA utility detects a problem with at least one index for the file, and will then set up the deleting, recreating, and rebuilding of all indexes for the file.

202 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 203: Envision Runtime Administration

Using WEEKLY.UDT.INDEX.ANALYSIS (WUIA)

Examples of Running the WUIA Utility

Three examples of running the WUIA utility are shown below.

Example 1

Step 1. To run the WUIA utility for the PERSON file for physical checking, enter the following at the colon prompt:

MIOSEL CORE.FILE.SPECS "PERSON"

The following displays:

1 record selected to list 0.

>

Step 2. Enter the following:

WEEKLY.UDT.INDEX.ANALYSIS

The following displays:

Running physical check only. To run a logical check, use option '-L'

Weekly UniData Index Analysis utility, version '03/04/2008'

Analyzing indexing for PERSON...

No problem index files found for this physical check.

:

Runtime Administration, March 10, 2010 203© 2010 Datatel, Inc.

Page 204: Envision Runtime Administration

Maintenance: Using File and Index Analysis Utilities

Example 2

Step 1. To run the WUIA utility for the PERSON file for logical checking, enter the following at the colon prompt:

MIOSEL CORE.FILE.SPECS "PERSON"

The following displays:

1 record selected to list 0.

>

Step 2. Enter the following:

WEEKLY.UDT.INDEX.ANALYSIS -L

The following displays:

Running logical check only. Empty index files will be skipped.

Weekly UniData Index Analysis utility, version '03/04/2008'

Analyzing indexing for PERSON...

No problem index files found for this logical check.

:

204 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 205: Envision Runtime Administration

Using WEEKLY.UDT.INDEX.ANALYSIS (WUIA)

Example 3

Step 1. To run the WUIA utility for all files for physical checking, enter the following at the colon prompt:

WEEKLY.UDT.INDEX.ANALYSIS

The following displays:

Running physical check only. To run a logical check, use option '-L'

Weekly UniData Index Analysis utility, version '03/04/2008'

Selecting all physical files in account, please wait...

Saving list of bad file pointers in SAVEDLISTS 'PHYS.BAD.FILES.IN.VOC'

Saving list of bad VOC pointers in SAVEDLISTS 'PHYS.BAD.VOC.FILES'

Analyzing indexing for ACAD.CREDENTIALS...

Analyzing indexing for ACAD.LEVELS...

<>

Analyzing indexing for privilege...

Saving list of problem index files in SAVEDLISTS 'PHYS.BAD.INDEX.FILES'.

:

Runtime Administration, March 10, 2010 205© 2010 Datatel, Inc.

Page 206: Envision Runtime Administration

Maintenance: Using File and Index Analysis Utilities

Results of Running a Physical Check on Index Files

When you run the WUIA utility in default mode to run a physical check on index files, there are six possible output items. Each of these items is cleared at the start of the utility, so that if the output item exists after a run, it was created by the most recent run.

Output Item 1: PHYS.IDX.STATS.AND.ERRORS in _HOLD_

This report is created and concatenates the results of the GUIDE_XSTATS.LIS and GUIDE_XERROR.LIS reports from the guide_ndx execution for each file processed.

Output Item 2: PHYS.BAD.INDEX.FILES Record in SAVEDLISTS

This saved list is created only if problems are found, and will contain a list of files with indexing issues.

Output Item 3: DATATEL.PHYS.DEL.IDX.FILES Paragraph in VOC

This paragraph is created if you are not in a Local Product Repository (LPR) environment. If the saved list in Output Item 2 was created, the paragraph will contain a series of DELETE.INDEX statements for the files in the saved list. If the saved list was not created, the paragraph will contain a display statement indicating there were no problem indexes.

When problem indexes are found, you can run this paragraph to clear out each file’s indexing. You then run the Multiple File Indexing (UTBA) process using the saved list in Output Item 2 to rebuild indexing for the files. On the UTBA form, enter one of the following options in the Indexing Function field:

B (Create & Build All)

M (Create & Build Missing)

Each run of the utility will save the previous run’s output paragraph as DATATEL.PHYS.DEL.IDX.FILES.PREV.

Note: Running this utility deletes any custom indexes created for the files in the paragraph. If the custom indexes are not defined to Envision specifications, they are not recreated and rebuilt by the UTBA process.

206 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 207: Envision Runtime Administration

Using WEEKLY.UDT.INDEX.ANALYSIS (WUIA)

Output Item 4: DATATEL.PHYS.DEL.RBD.IDX.FILES Paragraph in VOC

This paragraph is always created; however, the content depends on the following:

If the saved list in Output Item 2 was created, the paragraph will contain a series of DELETE.INDEX, CREATE.INDEX, and BUILD.INDEX statements for the files in the saved list. Running the paragraph clears out each file’s indexing and recreates and rebuilds it.

If the saved list was not created, the paragraph will contain a display statement indicating there were no problem indexes.

In either case, you do not need to then run the UTBA process.

This paragraph can be used in LPR environments, (which do not have Colleague or Envision, so the UTBA process is not available). For apphome environments, this can be used instead of the paragraph in Output Item 3 and the UTBA process.

Each run of the utility will save the previous run’s output paragraph as DATATEL.PHYS.DEL.RBD.IDX.FILES.PREV.

Output Item 5: PHYS.BAD.FILES.IN.VOC record in SAVEDLISTS

If created, this saved list contains a list of files that could not be opened using their existing VOC pointer. This list is provided for your convenience in cleaning up your VOC file.

Note: Running this utility will initially delete any custom indexes created for the files in the paragraph. However, it will then recreate and rebuild any indexes that existed for each file when the WUIA utility was run. The list is not driven from RFSPECS, and therefore may not be complete (from an RFSPECS, UTBI/UTBA perspective), but any indexes that are deleted by the paragraph will be recreated by the paragraph.

Runtime Administration, March 10, 2010 207© 2010 Datatel, Inc.

Page 208: Envision Runtime Administration

Maintenance: Using File and Index Analysis Utilities

Output Item 6: PHYS.BAD.VOC.FILES record in SAVEDLISTS

If created, this saved list contains a list of logical view files that could be opened with their logical name, but could not be opened with their physical name. This could be due to a bad physical VOC entry, or it could be due to a missing VOC entry for the physical file.

For example, when trying to analyze SPOUSE (a logical view of PERSON), if the VOC entry for SPOUSE is correct, but the VOC entry for PERSON is either missing or incorrect, then the saved list will be populated with both SPOUSE and PERSON.

208 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 209: Envision Runtime Administration

Using WEEKLY.UDT.INDEX.ANALYSIS (WUIA)

Results of Running a Logical Check on Index Files

When you run the WUIA utility with the optional logical check on index files (by adding -L), there are six possible output items. Each of these items is cleared at the start of the utility, so that if the output item exists after a run, it was created by the most recent run.

Output Item 1: LOGI.IDX.STATS.AND.ERRORS in _HOLD_

This report is created when you run a logical check on index files. It concatenates the results of the GUIDE_XSTATS.LIS and GUIDE_XERROR.LIS reports from the guide_ndx execution for each file processed.

Output Item 2: LOGI.BAD.INDEX.FILES Record in SAVEDLISTS

This saved list is created only if problems are found, and will contain a list of files with indexing issues.

Output Item 3: DATATEL.LOGI.DEL.IDX.FILES Paragraph in VOC

This paragraph is created if you are not in an LPR environment. If the saved list in Output Item 2 was created, the paragraph will contain a series of DELETE.INDEX statements for the files in the saved list. If the saved list was not created, the paragraph will contain a display statement indicating there were no problem indexes.

When problem indexes are found, you can run this paragraph to clear out each file’s indexing. You then run the Multiple File Indexing (UTBA) process using the saved list in Output Item 2 to rebuild indexing for the files. On the UTBA form, enter one of the following options in the Indexing Function field:

B (Create & Build All)

M (Create & Build Missing)

Each run of the utility will save the previous run’s output paragraph as DATATEL.LOGI.DEL.IDX.FILES.PREV.

Runtime Administration, March 10, 2010 209© 2010 Datatel, Inc.

Page 210: Envision Runtime Administration

Maintenance: Using File and Index Analysis Utilities

Output Item 4: DATATEL.LOGI.DEL.RBD.IDX.FILES Paragraph in VOC

This paragraph is always created; however, the content depends on the following:

If the saved list in Output Item 2 was created, the paragraph will contain a series of DELETE.INDEX, CREATE.INDEX, and BUILD.INDEX statements for the files in the saved list. Running the paragraph clears out each file's indexing and recreates and rebuilds it.

If the saved list was not created, the paragraph will contain a display statement indicating there were no problem indexes.

In either case, you do not need to then run the UTBA process.

This paragraph can be used in LPR environments, (which do not have Colleague or Envision, so the UTBA process is not available). For apphome environments, this can be used instead of the paragraph in Output Item 3 and the UTBA process.

Each run of the utility will save the previous run’s output paragraph as DATATEL.LOGI.DEL.RBD.IDX.FILES.PREV.

Output Item 5: LOGI.BAD.FILES.IN.VOC Record in SAVEDLISTS

If created, this saved list contains a list of files that could not be opened using their existing VOC pointer. This list is provided for your convenience in cleaning up your VOC file.

Note: Running this utility deletes any custom indexes created for the files in the paragraph. If the custom indexes are not defined to Envision specifications, they are not recreated and rebuilt by the UTBA process.

Note: Running this utility will initially delete any custom indexes created for the files in the paragraph. However, it will then recreate and rebuild any indexes that existed for each file when the WUIA utility was run. The list is not driven from RFSPECS, and therefore may not be complete (from an RFSPECS, UTBI/UTBA perspective), but any indexes that are deleted by the paragraph will be recreated by the paragraph.

210 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 211: Envision Runtime Administration

Using WEEKLY.UDT.INDEX.ANALYSIS (WUIA)

Output Item 6: LOGI.BAD.VOC.FILES Record in SAVEDLISTS

If created, this saved list contains a list of logical view files that could be opened with their logical name, but could not be opened with their physical name. This could be due to a bad physical VOC entry, or it could be due to a missing VOC entry for the physical file.

For example, when trying to analyze SPOUSE (a logical view of PERSON), if the VOC entry for SPOUSE is correct, but the VOC entry for PERSON is either missing or incorrect, then the saved list will be populated with both SPOUSE and PERSON.

Runtime Administration, March 10, 2010 211© 2010 Datatel, Inc.

Page 212: Envision Runtime Administration

Maintenance: Using File and Index Analysis Utilities

Recommendations When Running the WUIA Utility

Datatel makes the following recommendations for using the WUIA utility.

How to Run Both Physical and Logical Checking

If you want to do both physical and logical checking, two separate runs of the WUIA utility must be executed. Also, you should run only one session using the WUIA utility at a time. This means you should not enter WEEKLY.UDT.INDEX.ANALYSIS in one session, while running WEEKLY.UDT.INDEX.ANALYSIS -L in another session.

The reason for this is that both physical and logical checking rely on the interim results UniData provides in GUIDE_XSTATS.LIS and GUIDE_XERROR.LIS for each execution of the guide_ndx command. Results from one session would likely skew the other session. So the two runs of the utility should be performed sequentially, either manually or through a paragraph.

Running on an Active versus a Quiet System

The WUIA utility can be run on an active system. However, the following paragraphs created by the utility should be run only on a quiet system:

DATATEL.PHYS.DEL.IDX.FILES

DATATEL.PHYS.DEL.RBD.IDX.FILES

DATATEL.LOGI.DEL.IDX.FILES

DATATEL.LOGI.DEL.RBD.IDX.FILES

Also, use a quiet system if you run the UTBA process with the Indexing Function field set to B or M.

212 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 213: Envision Runtime Administration

Using WEEKLY.UDT.INDEX.ANALYSIS (WUIA)

Setting up Paragraphs for the WUIA Utility

You may want to set up paragraphs to execute regular runs of the WUIA process and its cleanup paragraphs. Although the WUIA utility may be run on an active system, the cleanup paragraphs and the UTBA process must be run on a quiet system. This means that any paragraphs you set up should also be run on a quiet system.

The following is an example VOC paragraph that can be created and used in an LPR or in an apphome environment:

:AE VOC WUIA.DELETE.REBUILD

0001: PA

0002: COMO ON WUIA.DELETE.REBUILD

0003: DATE

0004: WEEKLY.UDT.INDEX.ANALYSIS

0005: DATATEL.PHYS.DEL.RBD.IDX.FILES

0006: WEEKLY.UDT.INDEX.ANALYSIS -L

0007: DATATEL.LOGI.DEL.RBD.IDX.FILES

0008: COMO OFF

However, remember that the DATATEL.PHYS.DEL.RBD.IDX.FILES and DATATEL.LOGI.DEL.RBD.IDX.FILES paragraphs simply recreate and rebuild the indexes that previously existed. They do not recreate and rebuild the indexes specified in Envision. So you may want to use a paragraph like the following in an apphome environment:

:AE VOC WUIA.DELETE.ONLY

0001: PA

0002: COMO ON WUIA.DELETE.ONLY

0003: DATE

0004: WEEKLY.UDT.INDEX.ANALYSIS

0005: DATATEL.PHYS.DEL.IDX.FILES

0006: WEEKLY.UDT.INDEX.ANALYSIS -L

0007: DATATEL.LOGI.DEL.IDX.FILES

0008: COMO OFF

After you execute this paragraph:

If the saved list PHYS.BAD.INDEX.FILES exists, run the UTBA process with the Indexing Function field set to “B” or “M” for that saved list.

If the saved list LOGI.BAD.INDEX.FILES exists, run the UTBA process with the Indexing Function field set to “B” or “M” for that saved list.

Runtime Administration, March 10, 2010 213© 2010 Datatel, Inc.

Page 214: Envision Runtime Administration

Maintenance: Using File and Index Analysis Utilities

214 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 215: Envision Runtime Administration

Maintenance

Envision File Services

Envision Runtime automatically provides certain services for files in the application’s database. While these services occur at runtime, each service is defined by the analyst who created the specification for the files and the data elements within those files. These specifications are defined through the Envision Tool Kit and are not modifiable by the end users. The automatic file services include:

Add/Change Tracking for records

Record Link Management

Record Deletion

Tracking File Activity

Indexing

Runtime Administration, March 10, 2010 215© 2010 Datatel, Inc.

Page 216: Envision Runtime Administration

Maintenance: Envision File Services

Add/Change TrackingAdd/Change Tracking for records in a file occurs automatically and is completely transparent to the user. For almost every Envision file, there are four fields defined which Envision Runtime uses to track additions and changes:

filename.ADD.DATE

filename.ADD.OPERATOR

filename.CHANGE.DATE

filename.CHANGE.OPERATOR

If these fields are present in the dictionary of a file accessed by an Envision process, the corresponding data is automatically maintained. For example, consider a file PARTS with the fields PARTS.ADD.DATA and PARTS.ADD.OPERATOR.

Any time a new part record is added to the PARTS file, Envision Runtime date stamps the record with the date the record was added and the operator who added it. Similarly, if the PARTS file also has the fields PARTS.CHANGE.DATE and PARTS.CHANGE.OPERATOR, any time a record in the PARTS file is modified, Envision Runtime automatically stamps the record with the date that it was changed on and the operator who changed it.

If any of the above fields are not defined for a file, Envision Runtime does not maintain the data for that field. Date stamping information is not maintained and this level of tracking is ignored.

You may not add or remove this tracking from a particular file. The existence of the changed data fields in the dictionary of a file does not automatically ensure date stamping. The date stamping fields must be defined through the Envision Tool Kit in order for Envision Runtime to recognize them.

Note: For Oracle support where shorter names are required with a maximum of 28 characters, Datatel now also allows: • filename.ADDDATE • filename.ADDOPR • filename.CHGDATE • filename.CHGOPR

216 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 217: Envision Runtime Administration

Record Link Management

Record Link ManagementSome fields within the database files of your application do not store data. These fields store the keys to other records either in the same file or in other files. The fields which store record IDs are named pointer fields and the record IDs stored in these fields are named record links.

Pointer fields can either be single or multivalued. Single-valued pointer fields are called X-pointers and multi-valued pointer fields are called Q-pointers. The X in X-pointer refers to a field that is a cross-reference (xref) to another record. The Q in Q-pointer originated from the original PICK programming term Qselect, which allows you to select a list of record IDs from a field within a record.

Example of an X-pointer is a person’s spouse. The Spouse field in one person’s demographic record contains an ID for the demographic record of the person’s spouse. Since the relationship “spouse” is a reciprocal relationship, the spouse’s demographic record in turn contains a link to the original person’s demographic record. When a record contains a link to another record which in turn has a link to the original, these links are called return links. The link defined for a person’s spouse has a return link of the spouse’s spouse.

Example of a Q-pointer is a person’s address. Many people have more than one address. A person’s demographic record, therefore, may contain a list of IDs to records in an address file. The address record additionally may have a list of person IDs for those people who live or work at the address. The person record, therefore, has a multi-valued return link to the address file, the return link being the residents of the address.

Record links play an important part in maintaining the integrity of your database. The relationships between records in the database fall into four categories:

One-to-one (person to spouse)

One-to-many (employer to employees)

Many-to-one (person to political party)

Many-to-many (children to parents)

The management of these record links is performed automatically by Envision Runtime each time a record is updated. The specifications for record link management are encoded in the Runtime File Specifications file RFSPECS for the file in which a pointer field resides. The record link specifications are defined by the analyst(s) who creates the structure of the database. Record link specifications, therefore, cannot be modified by the end user.

Runtime Administration, March 10, 2010 217© 2010 Datatel, Inc.

Page 218: Envision Runtime Administration

Maintenance: Envision File Services

Envision Runtime ensures that the integrity of these record links in maintained and does not rely on either the programmer who defines a new form process or the end user of that form. The specifications for record link management are stored in the Central Data Dictionary (CDD) for the application and therefore become part of any program definition. These specifications are encoded into the RFSPECS file for use at runtime.

The relationships between entities in the database usually implies that certain information is true only when the two entities are considered at the same time. For example, the data stored for the date a person was hired by a company and the person’s telephone extension at the company are valid only when you consider the person and the company at the same time. When data about the relationship between two entities is stored, that file is called a relation file. A relation file is keyed by a combination of the IDs of the related entities. This relational structure ensures that data is stored only once. The date two people are married on is not stored in each of their demographic records: one relation record provides the logical location, so that the data is stored only once.

Specifications about relation files are also stored in the CDD, automatically becoming part of a program definition and ensuring the proper retrieval and maintenance of a relation record. The generated and compiled program uses Envision Runtime file management to retrieve the relation record and modify the data stored, if appropriate. The relationship between entities in the database and the relation record associated to the entities is defined through the Envision Tool Kit and therefore cannot be changed by the end user.

218 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 219: Envision Runtime Administration

Record Deletion

Record DeletionRecord Deletion occurs on the Envision screen processes for which deleting records is allowed. The ability to delete records is defined through the Envision Tool Kit when the screen process is defined. You can not add or remove the delete ability from the screen processes.

For those screens that allow record deletion, the user presses the RECORD DELETE function key. Envision Runtime prompts the user to make sure he really means it. If the user presses the RECORD DELETE function key a second time, Envision Runtime removes the record from the file.

Runtime Administration, March 10, 2010 219© 2010 Datatel, Inc.

Page 220: Envision Runtime Administration

Maintenance: Envision File Services

Transaction LoggingWith the Transaction Logging function, Envision Runtime allows you to track changes to, additions of and deletions of records in a specified file. For files that contain sensitive data, this tracking allows an additional layer of security and provides a mechanism for recovering from mistakes and disasters. Whenever a record is written back to disk, Envision Runtime checks to see if transaction logging has been requested for that file. If you have requested transaction logging, Envision Runtime writes both the old and new version of the changes in the record. For a changed or deleted field, only the values for the fields that change are written to the log file in order to conserve disk space. If a record is deleted or added, the entire record is written to the log file. In addition, Envision Runtime tracks the date and time of the change and the operator who made the change.

Requesting transaction logging, while providing additional security and peace of mind, comes at the cost of disk I/O performance and disk space requirements. Once the transaction logging information has served its purpose, purge it using the TXLOG Purge (UTTP) form.

Requesting Transaction Logging

Step 1. Run the Transaction Log Specification (UTML) form.

Step 2. Enter the filename. The file must have a corresponding UFSPECS record. Currently, only Envision-based software meets this criteria.

Step 3. The current status of the file displays. Enter if you wish to change the status from on to off or off to on.

Step 4. Indicate the date to which you wish to track file activity.

220 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 221: Envision Runtime Administration

History Logging

History LoggingHistory logging enables you to use field and file history to track changes and view records as they existed at an earlier time.

To track changes made by users to the values in specific fields in a file, use the Define Field History (DHST) form, described in “Define Field History (DHST)” beginning on page 335.

To view an earlier version of a record from field history, use the Field History Detail (FHDT) form, described in “Field History Detail (FHDT)” beginning on page 340.

To view an earlier version of a record from a history value, use the Rebuild Field History (RBFD) form, described in “Rebuild Field History (RBFD)” beginning on page 368.

To view a record in a file as of a certain date, use the Rebuild File History (RBFH) form, described in “Rebuild File History (RBFH)” beginning on page 369.

Note: You can only view data in inquiry mode. History logging does not allow you to change records or restore them to earlier versions.

Runtime Administration, March 10, 2010 221© 2010 Datatel, Inc.

Page 222: Envision Runtime Administration

Maintenance: Envision File Services

File IndexingPrior to using Colleague 18.0, you will have converted all files to database indexing. Database indexing enables you to define indexes to Envision while using the indexing capabilities of your database, rather than Envision, to store and maintain index values. There are several advantages to database indexing:

Database queries can take advantage of Envision-defined indexes

Calculated indexes are stored as data rather than derived

Database indexing is more efficient and more robust.

The indexing processes are found in the System File Administration menu, as shown in Figure 33.

Figure 33: System File Administration Menu

222 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 223: Envision Runtime Administration

File Indexing

Datatel Defined Indexes

Certain files for applications are delivered by Datatel. You are not able to change these delivered definitions. You may add your own definitions, but those defined by Datatel cannot be modified.

User Defined Indexing

To define your own indexing for selected files, run the User File Index Specification (UTMI) form, as shown in Figure 34. This form stores the indexing definitions you enter in the user file specifications file UFSPECS. Each time the indexing definitions for a file are stored in UFSPECS, Envision Runtime “compiles” these specifications into runtime file specifications stored in the runtime specifications file RFSPECS. Envision Runtime uses these compiled versions of the indexing definitions whenever a record for that file is written to disk. Index records are created in the specified target file for each index definition associated with the file.

Figure 34: Example User File Index Specification (UTMI) Form

The Constructing File Name field indicates the file for which you want to define indexing. If you want to use an index that is defined and maintained through another file, you can enter the name of the file in this field. This enables you to use the index in read-only mode. Enter the name of the file

Envision 4.7 only

Runtime Administration, March 10, 2010 223© 2010 Datatel, Inc.

Page 224: Envision Runtime Administration

Maintenance: Envision File Services

or use LookUp to retrieve its name. This file must already have a valid UFSPECS record defined.

An indexing association is a field or list of fields which, when changed, trigger indexing. A change to the value stored in any of the fields in the association causes Envision Runtime to recalculate the index value and update the corresponding index record.

Enter in the Index Association Data Elements fields the data elements that comprise the indexing association. If a change to the value in only one data element triggers indexing, enter the name of that data element as the only member of the indexing association. If more than one data element triggers indexing, enter the name of each data element on a separate line.

For example, a file called ORGANIZATIONS is indexed by the field ORG.NAME. For this indexing association in ORGANIZATIONS, ORG.NAME is the only data element and, whenever the name for an organization changes, Envision Runtime uses the new value to calculate the index record key. Another file, PERSON, is indexed by LAST.NAME, FIRST.NAME and MIDDLE.NAME. Whenever any of these fields changes, Envision Runtime compares the new values and the old values to calculate the index record key.

Enter, or use LookUp to retrieve, the name of the file in which index IDs are to be stored in the Target File for Index Records field. By convention, this file is usually called INDEX.filename, where filename is the name of the file for which Envision Runtime performs the indexing. The file designated to store the indexing records must be a valid file defined in the VOC. (This field is used in Envision 4.7 only.)

The default algorithm for determining the indexing key is simply to use the value of the data element. When you specify more than one field in the indexing association, the default algorithm concatenates the values in the data elements together. This default indexing key is usually insufficient and unwieldy. The Subroutine to Calculate Index Keys field allows you to specify the name of a subroutine which can be used to transform the value or values passed into a more efficient and concise indexing key. The subroutine must have one argument: a list of values. It should return the string or strings of characters to use as indexing record keys. If the subroutine returns more than one indexing key, each value in the returned list must be separated by a field mark (@FM).

Note: If you are using a subroutine, you must list here all elements that are referenced by that subroutine in order to give the subroutine access to the fields and ensure correct index updating.

Note: By default, each field in the association is used as a key for a record in the target file. To concatenate fields, use the subroutine that you designate in this field.

224 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 225: Envision Runtime Administration

File Indexing

Enter Yes in the Index Null Keys field if you want null values to be used in indexing. If you enter “No” or leave the field blank, null values are not used.

In the Primary File Storage Field Name field, enter the name of the field in the main file that is designated for storage of intermediate index values, i.e., the calculated result from the associated subroutine that is defined for the index.

If you designated an alternate storage file for intermediate index values, specify the designated numeric field in the Alternate Storage File Position field.

Enter the name(s) of the data field(s) to store in the index record in the Data Elements to Store in Index fields.

If you want to delete this index association, enter Yes in the Delete this Index Association field. Enter No or leave the field blank to retain the association.

Note: The default entry for a Data Elements to Store in Index field is the key to the record in the primary file. If Envision uses a field other than the record key to index a record, this field specifies which field of the current record to store as the key for this record in the index file. The Index Key Subroutine determines which field to use as the key.

Runtime Administration, March 10, 2010 225© 2010 Datatel, Inc.

Page 226: Envision Runtime Administration

Maintenance: Envision File Services

Converting Files to Database Indexing

Perform the following steps to convert a group of files or an entire application to database indexing.

Step 1. Run the Batch Runtime RFSPECS Refresh (BRRR) utility, as shown in Figure 35, on each application.

Figure 35: Batch Runtime RFSPECS Refresh (BRRR) Form

The BRRR form contains information on various functions that need to be performed on a file when writes occur, including indexing. The information in this file is generated from the appl.FILE.SPECS file in the Tool Kit, and from UFSPECS on the runtime side. You can specify one of three ways to define which files to process.

If you want to do one of the following:

Convert the files in a saved list, enter a saved list name that contains the file names you want to convert in the Rebuild Saved List field.

Manually select a group of files to convert, enter a manual list of files to process in the Rebuild File List fields.

Convert all files in the current application, leave all fields blank.

When you update from the BRRR form, the selected files are converted.

226 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 227: Envision Runtime Administration

File Indexing

Step 2. If you have created custom Envision indexes that use a subroutine to calculate index keys, you must run the Index Storage Field Report (ISFR), shown in Figure 36, to identify the indexes that need additional storage fields, and to specify the storage fields for values created by subroutines.

Figure 36: Index Storage Field Report (ISFR) Form

Do you want to run the report for every file in the application?

Yes. Leave the Report Limit List field blank.

No. Enter the name of a saved list in the Report Limit List field.

Note: If you have not created custom indexes, skip to step 5 on page 231.

Runtime Administration, March 10, 2010 227© 2010 Datatel, Inc.

Page 228: Envision Runtime Administration

Maintenance: Envision File Services

Step 3. Update to generate the Missing Index Storage Fields Report, as shown in Figure 37.

Figure 37: Example Missing Index Storage Fields Report

228 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 229: Envision Runtime Administration

File Indexing

Step 4. Use the User File Index Specification (UTMI) form, shown in Figure 38, to define the additional storage fields.

For detailed general information about the UTMI form, see “User Defined Indexing” beginning on page 223.

Figure 38: Example User File Index Specification (UTMI) Form

If you want to use an index that is defined and maintained through another file, you can enter the name of the file in the Constructing File Name field. This enables you to use the index in read-only mode.

In the Index Association Data Elements fields, enter the names of fields that activate Envision indexing when they change.

Enter the name of the file in which index IDs are to be stored in the Target File for Index Records field. (Envision 4.7 only)

In the Subroutine to calculate Index Keys field, enter the name of a subroutine used for indexing.

By default, each field in the association is used as a key for a record in the target file. To concatenate fields, use the subroutine that you designate in

Envision 4.7 only

Note: If you are using a subroutine, you must list here all elements that are referenced by that subroutine in order to give the subroutine access to the fields and ensure correct index updating.

Runtime Administration, March 10, 2010 229© 2010 Datatel, Inc.

Page 230: Envision Runtime Administration

Maintenance: Envision File Services

this field.

Enter Yes in the Index Null Keys field if you want null values to be used in indexing. If you enter “No” or leave the field blank, null values are not used.

In the Primary File Storage Field Name field, enter the name of the field in the main file that is designated for storage of intermediate index values, i.e., the calculated result from the associated subroutine that is defined for the index.

The Primary File Storage Field Name field is a required field if you use a subroutine for indexing.

If you have designated an alternate storage file for intermediate index values, specify the designated numeric field in the Alternate Storage File Position field.

Enter the name of the data fields to be stored in the index record in the Data Elements to Store in Index fields.

The default entry for a Data Elements to Store in Index field is the key to the record in the primary file. If Envision uses a field other than the record key to index a record, this field specifies which field of the current record to store as the key for this record in the index file. The Index Key Subroutine determines which field to use as the key.

If you want to delete this index association, enter Yes in the Delete this Index Association field. Enter No or leave the field blank to retain the association.

If you use UniData and have already created database indexes, there is no need to modify them. If you have indexed a field that is indexed by Envision, the name of the index may change, but this should have no effect on processing or the use of the index.

230 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 231: Envision Runtime Administration

File Indexing

Step 5. Access the Envision Parameters Edit (EPED) form, shown in Figure 39, to specify your current indexing mode.

Figure 39: Envision Parameters Edit (EPED) Form (Envision 4.7)

Enter 5 in the MIO Indexing Mode field to set the mode to a combination of Envision and database indexing.

When all files in the application have been successfully converted to database indexing, set the MIO Indexing Mode to 4.

For information about the other fields on the EPED form, see “Using the Envision Parameters Edit (EPED) Form” beginning on page 55.

Envision 4.7 only

Note: Datatel recommends choosing 5 (combined Envision and database indexing) during the conversion period. If any problems arise with a database indexed file, you can revert to Envision indexing for that file. When conversion is complete, you can select 4 to change to exclusively database indexing.

Note: The DMI Print Server IP/Port fields are used in Envision 4.7 only. In Release 18.0,you can set up a DMI listener with a print server role as described in Implementing Stylesheet Printing available on the Datatel web site at: http://www.datatel.com/support/documentation/colleague/collr18doc.cfm.

Runtime Administration, March 10, 2010 231© 2010 Datatel, Inc.

Page 232: Envision Runtime Administration

Maintenance: Envision File Services

Step 6. Use the File Indexing (UTBI) form, shown in Figure 40, to index your files individually, or the Multiple File Indexing (UTBA) form, shown in Figure 41 on page 233, to index multiple files.

Figure 40: File Indexing (UTBI) Form

Complete the File Indexing (UTBI) form as follows:

In the File field, enter the name of a file for which indexing needs to be maintained.

The Indexing Type field displays the type of indexing to use with the file that you specified (used in Envision 4.7 only).

Envision 4.7

Technical Tip: If your account is set up for Envision/Database Indexing, you can change the default target type by using the drop-down list. You cannot make this change with any other type of account-wide indexing.

232 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 233: Envision Runtime Administration

File Indexing

In the Indexing Function field, select the indexing function that you want to run.

In the Saved List Name field, enter an optional saved list of files for indexing. If computed index columns are calculated, only records in this saved list are updated.

In the Indexes to Maintain fields, delete all indexes that you do not want to maintain. You can also use these fields to enter any index associations that you accidentally removed.

To maintain indexes on multiple files, use the Multiple File Indexing (UTBA) form, as shown in Figure 41.

Figure 41: Multiple File Indexing (UTBA) Form

Step 7. In the Saved List Name field, enter a saved list of files for indexing.

ALERT! Some files, such as Express Load files, are shared between your install account and your main accounts. When converting these files from Envision indexing to database indexing, you will need to run UTBI on the file in the install account and again in each main account to make sure all accounts can access the file correctly. For example, when converting EXPL.PATCH.CTL from Envision indexing to database indexing, run UTBI in the install account, and then run it again in each main account linked to the install account.

Runtime Administration, March 10, 2010 233© 2010 Datatel, Inc.

Page 234: Envision Runtime Administration

Maintenance: Envision File Services

Step 8. In the Indexing Function field, select the type of indexing function that you want to run.

When File Conversion Is Complete

Complete the following steps after all files have been converted to database indexing.

Step 1. Use the Envision Parameters Edit (EPED) form, shown in Figure 39 on page 231, to switch the indexing mode parameter for the application to 4 (exclusively database indexing).

Step 2. When all files have been successfully converted to database indexing, you can use the Delete Obsolete Index Files (DOIF) form, as shown in Figure 42, to purge the Envision index files.

Figure 42: Delete Obsolete Index Files (DOIF) Form

Note: Datatel recommends retaining the Envision index files until you are confident that there are no problems with any of the converted files. Once the Envision index files have been purged, you cannot revert files to Envision indexing.

234 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 235: Envision Runtime Administration

File Indexing

If you want to do one of the following:

Delete the Envision index files in a saved list, enter a saved list name that contains the file names you want to delete in the Delete Saved List field.

Manually select a group of Envision index files to delete, enter a manual list of files to delete in the Delete File List fields.

Delete all Envision index files in the current application, leave all fields blank.

When you update from the DOIF form, the selected index files are deleted.

Runtime Administration, March 10, 2010 235© 2010 Datatel, Inc.

Page 236: Envision Runtime Administration

Maintenance: Envision File Services

236 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 237: Envision Runtime Administration

Maintenance

Envision Runtime Reports

A number of reports and documentation features are included with Envision Runtime and therefore are available to every Envision-based application. The seven Runtime reports documented in this section allow you to retrieve valuable information, including the following:

How procedures are defined

What results did a given procedure produce when run

For each report documented, a brief description of the report and its fields precedes the technical listing of the procedure definition for the report. While reviewing the technical listings, remember that values that appear in square brackets ([]) are variable, which are evaluated based on user entries at runtime.

Procedure Rules DocumentationThe Procedure Rules Documentation (JPRT) report lists the specifications for an Envision procedure. The first section of the report describes global information for the procedure. The description is free-form text. For reports, the procedure class is always “R” for “Report”; for procedures that are not reports, the procedure class is “P” for “Process”. This procedure class determines the menu quadrant the Menu Processor places the procedure’s mnemonic. The securable flag determines if users in the field can modify Datatel-defined procedure. The phantom allowed flag determines if the procedure is executable as a background process.

The JRPT report also lists the date/operator stamp for when the procedure was added and when it was last changed.

The bottom section of the report shows each step defined for the procedure. Each step has a mnemonic and can optionally have a label and a description. Procedure steps that are “jobs” have listed the mnemonic and the calling interface to the Procedure Generator. “User Screens” show the name of the screen and the process name. “IF” and “STMT” steps show the detailed information for the analyst-defined special statement. “List” specifications show the criteria for generating the list, including sort and select options and any branching on error.

Runtime Administration, March 10, 2010 237© 2010 Datatel, Inc.

Page 238: Envision Runtime Administration

Maintenance: Envision Runtime Reports

Lookup Resolution SpecificationsThe Lookup Resolution Specifications (LPRT) report lists the definitions for a resolution screen called when the LookUp Processor finds more than one record ID match to a user’s input.

The first section of the report shows the description of the resolution definition and the file on which the template is operating. This section also shows the key transformation subroutine if one has been specified.

The second section of the report describes each component part of a display block. These display blocks show the user information to aid his choice of a record ID. Each component part has displayed the character that represents it in the block image, the line of the block on which it appears, the column of that line in which it appears, the length and justification of the part and the definition for what displays in that part.

The last section of the report shows how a block of resolution data would appear. Each letter in the display block corresponds to a letter in the part listing. This display block also shows the template text for the resolution screen.

Record Security SpecificationsThe Record Security: List Specs (RPRT) report lists the record security definitions for a particular file. The first part of this report shows the file for which you are securing records and whether the security definition is currently enforced. This first part also shows who last changed the security definition and when it was changed.

The second part of the report shows the current definition of record security on the selected file. This definition includes the record security criteria shown here as a select statement. The value shown in square brackets ([]) is the access a user who meets that criteria has to a requested record: “I” is for “Inquiry” and “A” is for “All”.

238 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 239: Envision Runtime Administration

Batch Error Report

Batch Error ReportThe Batch Error Report (UTBE) details the step-by-step results of selected procedures.

The first column of information on this report shows the particular job statistics record used to generate the report. This column also shows the description of the error, if applicable. The second column of this report shows which step the report block is describing. Each step in an executed procedure will have its own report block. The second column describes what the procedure step was doing and what the status of the step is. A step can have one of the following statuses:

[[S]] for started, still in progress

[[F]] for finished

[[C]] for canceled by the user

The third report block column shows the accumulated totals for the procedure. The last column shows the start time and duration for the procedure step.

Job Statistics ReportThe Job Statistics Report (UTJR) lists all the information available about executed procedure. The first section of this report shows information concerning the overall procedure. The next section shows the results of each step for the procedure. Next, any error messages from the procedure steps are shown. Finally, UTJR shows the actual paragraph created by the Procedure Generator to run the procedure.

Runtime Administration, March 10, 2010 239© 2010 Datatel, Inc.

Page 240: Envision Runtime Administration

Maintenance: Envision Runtime Reports

Audit Trail ReportThe Audit Trail Report (UTXL) lists the changes, additions and deletions for a file based on the records stored in the file’s transaction log file.

Each report block this report shows one transaction for a record in the logged file. The three transaction types (Added, Changed, Deleted) are shown in the first column of each report, enter the date on which the transaction occurred. The next column shows the time the transaction occurred and the operator for the transactions, as well as all the fields which are affected by the transactions. The next column shows the record in the logged file affected by the transactions as well as the original values for the fields that changed. Finally, UTXL shows the new values for the fields that changed.

240 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 241: Envision Runtime Administration

Maintenance

Purging Files

To ensure that your system runs at peak performance, you should remove obsolete records from heavily used files. The removal of obsolete records is called purging. This chapter describes the types of files to purge and provides procedures to remove records from several frequently used files.

The frequency of use for each file varies from site to site. The purging of these files, therefore, occurs at different time intervals for each system administrator. You should review the following files on a periodic basis:

Data files updated by the application software

Background system files

Database management files

Data FilesPurging, archiving, and condensing programs are provided within the modules of your application software. Purging programs remove the data from your system and often allow you to dump the data to tape. Archiving programs allow you to move your data to a set of archiving files to allow more space in your working files. You can still access the demographic information. Condensing programs allow you to consolidate history information in its own file.

See the user documentation for your modules for details on the programs provided within that module.

Runtime Administration, March 10, 2010 241© 2010 Datatel, Inc.

Page 242: Envision Runtime Administration

Maintenance: Purging Files

Background System FilesThe following processes store data about a process in background system files as your users run programs.

Batch Status

Transaction Logging

Batch Status

Use the Job Statistics Purge (UTJP) procedure to purge data that is automatically collected and stored when an end user runs a procedure. This data is used not only to track the current status of a procedure while it is still running, but is also used to generate the Job Statistics Report (UTJR). The job statistics include the date the procedure was run, the start and end times of the procedure, the records the procedure processed, as well as detailed statistics for each step in the procedure.

These statistics are stored in the file appl.PPROCESS, where appl is the mnemonic for the current application. The purge process clears the file of the selected data.

To delete obsolete statistics records, run the application for which you wish to purge the PPROCESS file. From the main menu of the application, run the Job Statistics Purge procedure, UTJP.

As with most Envision procedures, the first step is to provide the Procedure Generator with the values for its runtime parameters. For the Job Statistics Purge procedure the front-end screen is used to gather the values of the parameters.

Several options allow you to selectively delete a finite number of records. You can specify a date range if the records you want to delete fall in a period of unusually high activity. You can specify a time range if, for instance, your important procedures are run at night and the statistics records you wish to delete are all from daytime jobs. You can select to purge records for a list of selected users or for a list of particular procedure mnemonics. The detail to which you specify the records to delete is entirely up to you. You can even specify no selection criteria to completely clear the job statistics file.

242 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 243: Envision Runtime Administration

Background System Files

A final option on this front-end screen allows you to generate a detailed report of the records deleted from the job statistics file. This report is run before the purging is done. You can cancel out of the procedure before the records are deleted if you do not want to purge the selected record. The purging batch program, when run, automatically prints a report of the records it has deleted.

Transaction Logging

Use the TXLOG Purge (UTTP) procedure to purge data that is automatically collected and stored for a file that has the transaction logging feature enabled. The data includes the operator’s login ID and the date and time the transaction was created. Transaction data includes all records added, changed, or deleted within the file. Envision stores transaction data in the log file TX_filename, where filename is the name of the file for which you are logging transactions. This purge process clears the transaction log file of the records you select.

The TXLOG Purge procedure begins with a front-end screen which allows you to select specific transaction records for deletion from the transaction logging file. First select the file for which you would like to purge transaction log records. If you specify no selection criteria, the procedure removes all of the records from the selected transaction log file.

You can selectively delete records by specifying selection criteria. You delete records:

Within a specific date range or time range

For specified users or records

By type, including old and new values for changed transactions

The batch program which performs the actual deletion of the selected records automatically generates a report of the records it has purged from the selected transaction log file.

Runtime Administration, March 10, 2010 243© 2010 Datatel, Inc.

Page 244: Envision Runtime Administration

Maintenance: Purging Files

Database Management FilesThree database files are used by Envision Runtime whenever a procedure is run:

HOLD

PH

SAVEDLISTS

The HOLD file is the target file for any report or other procedure output which the user selected to view at his terminal. The PH file stores the record of procedure execution whenever a procedure is run as a background process. The SAVEDLISTS file stores the lists of IDs whenever the report or procedure requires the generation of a list.

Database Management System Files Naming Conventions

UniData and SQL Server

_HOLD_

_PH_

SAVEDLISTS

These files can affect the performance of your system if they become too large. The time it takes to do backups is also affected by the size of these directories. It is important, therefore, that you periodically clean out the obsolete records from these files. While Envision Runtime does not provide specific screen or batch processes to aid you in removing records from these files, the following sections describe the procedures you can follow to remove records from these files.

244 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 245: Envision Runtime Administration

Database Management Files

HOLD

The HOLD file is the database file in which Envision Runtime writes report output for processing by the BROWSE utility. Some records in this file are keyed by the date and time the user sent report output to the HOLD file. Other records in the HOLD file have IDs that are strings the users entered. In order to purge the HOLD file:

1. In the database environment, select the HOLD file, sorting by ID. Save this list to the SAVEDLISTS file. :SSELECT HOLD :SAVE.LIST HOLD.LIST

2. Edit the list you just created. Determine the HOLD file records that you want to save. Remove the line containing the name of the record that you want to save from the list. When the list contains only those records you wish to remove from the HOLD file, file the list back into SAVEDLISTS.

3. In the database environment, retrieve the list you just modified and delete the records from the HOLD file: :GET.LIST HOLD.LIST :DELETE HOLD

The system prompts you to make sure you wish to delete records from the file using a select list. Answer [[Y]] to this prompt.

PH

The PH file stores the record of all processes run in background mode. Each record in the PH file has a multi-part key:

The ID of the VOC record run in background mode

The internal representation of the time the process was run

The internal representation of the date on which the process was run

In order to purge the PH file:

Step 1. In the database environment, select the PH file, sorting by ID. Save this list to the SAVEDLISTS file.

Step 2. :SSELECT PH :SAVE.LIST PH.LIST

Runtime Administration, March 10, 2010 245© 2010 Datatel, Inc.

Page 246: Envision Runtime Administration

Maintenance: Purging Files

Step 3. Edit the list you just created. Determine the PH file records you want to save. For each record that you want to save, remove the line containing the name of the record from the list. When the list contains only those records you wish to remove from the PH file, file the list.

Step 4. In the database environment, retrieve the list you just modified and delete the records from the PH file:

Step 5. :GET.LIST PH.LIST :DELETE PH

The system prompts you to make sure you want to delete records from the file using a select list. Answer [Y] to this prompt.

SAVEDLISTS

The SAVEDLISTS file stores any created list a user has saved using the SAVE.LIST command. Envision Runtime also uses the SAVEDLISTS file to temporarily store lists of record IDs for use in procedures. In order to purge the SAVEDLISTS file:

Step 1. In the database environment, select the SAVEDLISTS file, sorting by ID. Save this list to the SAVEDLISTS file.

:SSELECT SAVEDLISTS :SAVE.LIST SAVEDLISTS.LIST

Step 2. Edit the list you just created. Determine the SAVEDLISTS file records you want to save. remove the line containing the name of the record that you want to save from the list. When the list contains only those records you wish to remove from the SAVEDLISTS file, file the list back into SAVEDLISTS.

Step 3. Retrieve the list you just modified and delete the records from the SAVEDLISTS file:

:GET.LIST SAVEDLISTS.LIST :DELETE SAVEDLISTS

The system prompts you to make sure you want to delete records from the file using a select list. Answer [Y] to this prompt.

246 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 247: Envision Runtime Administration

Runtime Administration

Troubleshooting

Page 248: Envision Runtime Administration
Page 249: Envision Runtime Administration

Troubleshooting

Introduction to Troubleshooting

The Troubleshooting section of Runtime Administration provides information you need to understand how to troubleshoot the software. The final chapter outlines common problems and their corresponding solution.

Recovery GuidelinesOccasionally application programs are interrupted because:

A user breaks out of a program or turns off a terminal,

The system has forced a logout of a terminal,

There has been a power failure, or

The system has halted.

As system administrator, you should take precautions to guard against some of these interruptions. Train users not to turn terminals off during a process and not to break out of programs. In fact, you should consider disabling [BREAK]. Keep terminal cables out of the way; and if necessary, secure the cables to the floor.

Because the user remote account does not have the vocabulary to do the setup for the recovery, this must be done from the main remote account. The actual recovery, however, must be done from the user remote account that initiated the process.

Runtime Administration, March 10, 2010 249© 2010 Datatel, Inc.

Page 250: Envision Runtime Administration

Troubleshooting: Introduction to Troubleshooting

Troubleshooting Envision-Based Software

In order to troubleshoot an interrupted program, it is helpful to understand the steps that a program follows during execution. Below are these steps and the utilities that allow you to view the status of each step.

Step 1. When you run a program, the program builds a paragraph containing the steps that the program will follow. These steps may include programs, subroutines, and select statements. This paragraph is written to the VOC and to the JOBSTATS files with the key of mnemonic_loginID_time_date.

You can view the paragraph from the View Batch Process Status (VBS) form. In addition, VBS shows the number of records processed and remaining, the elapsed time, the time remaining, and the number of errors. Detail to View Single Batch Job Step (VBSD) to view additional details for each step including the last record read.

Step 2. As each step of the paragraph is run, the status in VBS changes from a blank to “started”. When the step is complete, the status changes to “finished”.

Step 3. When the program has successfully completed, the VOC paragraph is deleted. The completed steps remain in the JOBSTATS file and may be reviewed for errors in VBS.

Step 4. If the program is interrupted, you can determine the step that the program stopped on by looking at the VBS form. At this point, you have the appropriate information to call Response Line to assist in recovery.

Step 5. You may be able to restart the process from the beginning depending on the implications of the completed steps. Or you may be able to start the process where it left off. In either case, the Rerun a Procedure (UTRR) form allows you to either start the process from the beginning or recreate the VOC paragraph with the process steps.

If you choose to restart the process from the beginning, you may do so within UTRR.

250 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 251: Envision Runtime Administration

Troubleshooting Envision-Based Software

If you want to restart the process where the process left off, in UTRR, choose the option to recreate the VOC record. You may then edit the VOC record and delete the steps from the paragraph that successfully completed. You can then run the paragraph and it will pick up with the next step.

Runtime Administration, March 10, 2010 251© 2010 Datatel, Inc.

Page 252: Envision Runtime Administration

Troubleshooting: Introduction to Troubleshooting

252 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 253: Envision Runtime Administration

Troubleshooting

Problems in Envision Applications

System Setup or Security IssuesThis chapter lists some commonly encountered problems, followed by the cause of the problem and its solution. Problem statements are shown in italics and causes are underlined.

Runtime Administration, March 10, 2010 253© 2010 Datatel, Inc.

Page 254: Envision Runtime Administration

Trou

blesh

oo

ting

: Pro

blem

s in E

nvisio

n A

pp

lication

s

254R

untime A

dministration, M

arch 10, 2010©

2010 Datatel, Inc.

Table 12 lists common problems with system setup or security, with their causes and solutions

Solution

record. Start with the application the r the application and run SOD. If the

not in the current application, determine if an application higher up in the tree. If the the current application, create a new

OD.

ld has data entered.

E record. For port-based systems, run DEVICES type from the user’s line d systems, use the user’s login ID as the

D from any application for the device to the display table field and use the

lect a valid display table.

E record. For port-based systems, run DEVICES type from the user’s line d systems, use the user’s login ID as the

D from any application for the device to the display table field and use the ect a valid display table. You may need to ard table.

Table 12: Problems With System Setup or Security

Problem Cause

I get logged out when I try to enter an application.

Invalid or missing OPERS record.

Check the user’s OPERSuser is trying to run. Enteuser’s OPERS record is the OPERS record is in user should only accessOPERS record through S

Make sure the Name fie

My terminal display is all messed up when I enter an application.

Missing or invalid display table defined in the DEVICES record.

Check the user’s DEVICSND and determine the number. For switch-baseDEVICES type. Run SDdefinition in question. GoLookUp Processor to se

The function keys on my keyboard don’t do what the template says they are supposed to.

Missing or invalid keyboard table defined in the DEVICES record.

Check the user’s DEVICSND and determine the number. For switch-baseDEVICES type. Run SDdefinition in question. GoLookUp Processor to seldefine the desired keybo

Page 255: Envision Runtime Administration

System

Setu

p o

r Secu

rity Issues

Runtim

e Adm

inistration, March 10, 2010

255©

2010 Datatel, Inc.

red mnemonic. If spelled incorrectly, he user has insufficient security if the user is supposed to use that ity class definition on SCD for the r should have access to the urity class for the current application

ecific operator definition for the e the operator definition includes the mnemonic. If the user does not r the current application, either add for the current application or check next higher application in the tree.

r does not show mnemonics for rights. If the user is supposed to see the solution to the last problem.

nition for the field in question on igned for field security. Then check SOD. If the user should have , add the proper security class for

s to more than one process, check SOD. If the user does not have an rent application, check the operator pplication. Make sure the initial is a menu.

can re-initialize the Envision

vironment entirely and returning

d starting the login procedure over

environment prompt and executing program ENVINIT.

olution

My terminal just beeps when I enter a mnemonic at a menu prompt.

Invalid mnemonic or insufficient security rights.

Check the spelling of the enteenter the correct spelling. If trights for a mnemonic, checkprocess and check the secursecured mnemonic. If the useprocess, check the user’s secon SOD. If the user has a spcurrent application, make sursecurity class for the securedhave an operator definition foa specific operator definition the operator definition for the

A mnemonic does not show up on the menu. Insufficient security right for the mnemonic.

The Runtime Menu Processowhich a user has no securityhave access to the process,

I can’t enter data into a field on a screen.

or

Data doesn’t show for a field; all I see are asterisks.

Insufficient Field Security Rights.

Check the Field Security defiSCDF. The security class assthe user’s security classes onaccess to the data in the fieldthe secured field.

When I enter an application, a screen runs and then I exit from the application without seeing a menu.

Initial application mnemonic is a screen process, not a menu.

If the user should have accesthe initial menu mnemonic onoperator definition for the curdefinition in the next higher amenu mnemonic for the user

I made changes to (Record Security User Characteristics, Record Security Criteria, Transaction Logging). When I run another process, the changes don’t show up.

Changes to some Runtime screens do not take effect until Envision is re-initialized.

Re-initialize Envision. A userenvironment by:

• leaving the database en

• logging off the system anagain

• returning to the databasethe Envision initialization

Table 12: Problems With System Setup or Security (cont’d)

Problem Cause S

Page 256: Envision Runtime Administration

Trou

blesh

oo

ting

: Pro

blem

s in E

nvisio

n A

pp

lication

s

256R

untime A

dministration, M

arch 10, 2010©

2010 Datatel, Inc.

as a lapsed time specified. The user n password defined on SOD.

vision. A user can re-initialize the :

e environment entirely and returning

m and starting the login procedure over

base environment prompt and executing ation program ENVINIT.

ROWSEing a COMO file, you may UFD& directory file from the BROWSE TFA.

Table 12: Problems With System Setup or Security (cont’d)

Solution

I left my terminal for a while and now the system prompts me for a password.

Envision has “timed out” the terminal.

The operator definition hmust re-enter his Envisio

I had a COMO running while executing a screen. I tried to view the COMO record using BROWSE and I was blown out.

The BROWSE utility cannot process terminal display characters.

You must re-initialize EnEnvision environment by

• leaving the databas

• logging off the systeagain

• returning to the datathe Envision initializ

To prevent a user from Bconsider removing the &file authorization list on U

Problem Cause

Page 257: Envision Runtime Administration

Ru

ntim

e Erro

r Messag

es

Runtim

e Adm

inistration, March 10, 2010

257©

2010 Datatel, Inc.

es and solutions.

olution

for each file ENVINIT cannot open. If ke sure you are attached to a valid nvision-based application has been

abase file (one with “&” in its name), . If the bad file is an Envision file CS or UFSPECS), call Datatel if the

in order. There may have been a installation or VOC pointers may be

s control what Envision modules you a problem with your last release y be damaged.

computer. If the message persists,

Runtime Error MessagesTable 13 lists common Envision initialization error messages with their caus

Table 13: Envision Initialization Error Messages

Message Cause S

“FATAL: bad.file is not present” One of the following trans-application files is missing:

• SYSDEFS

• DEVICES

• VOC

• SAVEDLISTS

• REFSPECS

• UPSPECS

• UFD

• HOLD

• PH

Check the VOC file definitions the VOC file is the bad file, madatabase account in which an Einstalled. If the bad file is a datcreate the file on your account(SYSDEFS, DEVICES, RFSPEVOC record for the file seems problem with your last release damaged.

“FATAL security fault: Missing Renewal Code Record”

Missing or invalid renewal codes detected.

Call Datatel. The renewal codecan run. There may have beeninstallation or VOC pointers ma

“SYSTEM DATE current.date precedes previous login date”

“Envision not initialized”

The date stored as the last login date precedes the system date on your computer. Since the stored last login date is based on the current system date, the system date on your computer is incorrect.

Reset the system date for yourcall Datatel.

Page 258: Envision Runtime Administration

Trou

blesh

oo

ting

: Pro

blem

s in E

nvisio

n A

pp

lication

s

258R

untime A

dministration, M

arch 10, 2010©

2010 Datatel, Inc.

here may have been a problem with your you may need to install a new release.

here may have been a problem with your you may need to install a new release.

he renewal codes control what Envision re may have been a problem with your VOC pointers may be damaged.

r the SYSDEFS file. It should be pointing unt. If this record is damaged or missing, both the SYSDEFS VOC record and the EFS are in order, call Datatel. There may your last release installation or VOC .

elled, enter the correct spelling. If the d, you may think the password is one it is another. Check the device definition DD) form and make sure the device

Table 13: Envision Initialization Error Messages (cont’d)

Solution

“Lease for module expired date. module not operable.”

The current date is past the date defined as the expiration date for the specified module.

Call Datatel immediately. Tlast release installation or

“Warning: Lease to module expired date (n days grace)”

“Please contact Datatel”

The date on which your software lease expires has passed.

Call Datatel immediately. Tlast release installation or

“FATAL security fault: Bad Customer Number in

Renewal Code Record“

Damaged or missing renewal code record.

Call Datatel immediately. Tmodules you can run. Thelast release installation or

“FATAL: Network definitions not present.” Envision cannot read the TASKLIST record in the SYSDEFS file.

Check the VOC pointer foto the current release accocall Datatel immediately. IfTASKLIST record in SYSDhave been a problem withpointers may be damaged

“Unauthorized access to secured terminal.” Incorrect password entered for a secured terminal.

If the password was missppassword is not misspellething while Envision thinkson the Device Definition (Spassword is correct.

Message Cause

Page 259: Envision Runtime Administration

Ru

ntim

e Erro

r Messag

es

Runtim

e Adm

inistration, March 10, 2010

259©

2010 Datatel, Inc.

uses and solutions.

olution

ach of the application files for the k (*) means is subject to tree reads):

PPROCESS*

PRCS.CTL*

PRCS.DEF

PRCS.GEN*

PRINTERS*

QBEDEF*

SECLASS*

SOURCE

SUBROUTINES

VALCODES*

VOC

ord. Start with the application the application and run the SOD form. If ot in the current application, rd is in an application higher up in ly access the current application, through SOD.

ata.

the OPERS record is invalid.

Table 14 lists common application initialization error messages with their ca

Table 14: Application Initialization Error Messages

Message Cause S

“Missing file: appl.bad.applfile

All base application files must be present.”

“Session not established.”

Missing or invalid application file.

Check the VOC pointers for ecurrent application (an asteris

• CDD •

• DOC •

• ENV* •

• ERROR* •

• FILE.SPECS* •

• HELP* •

• HELP.LONG* •

• INSERTS •

• MENU* •

• OBJ •

• OPERS* •

• PARMS*

“Improperly set up user: login. See your system administrator.”

Missing or invalid OPERS record.

Check the user’s OPERS recuser is trying to run. Enter thethe user’s OPERS record is ndetermine if the OPERS recothe tree. If the user should oncreate a new OPERS record

Be sure the Name field has d

If there is no data in the field,

Page 260: Envision Runtime Administration

Trou

blesh

oo

ting

: Pro

blem

s in E

nvisio

n A

pp

lication

s

260R

untime A

dministration, M

arch 10, 2010©

2010 Datatel, Inc.

entered mnemonic. If spelled incorrectly, . If the user has insufficient security rights the user is supposed to use that process lass definition on SCD for the secured ould have access to the process, check

for the current application on the SOD ecific operator definition for the current e operator definition includes the ured mnemonic. If the user does not n for the current application, either add a n for the current application or check the next higher application in the tree.

ess your system has ended, delete the . If the user should still have access to n, check the password expiration date on

e application should end on the date user will be unable to enter the

at date. If the user should continue to cation, change the password expiration

alone, the user has entered an incorrect password was misspelled, have the assword. If the user has typed in what he password, check the Envision password

essage appears with another message, essage.

Table 14: Application Initialization Error Messages (cont’d)

Solution

“Invalid startup menu of bad.menu. See your system administrator“

Mnemonic defined for the initial menu mnemonic on SOD is invalid.

Check the spelling of theenter the correct spellingfor a mnemonic, check ifand check the security cmnemonic. If the user shthe user’s security classform. If the user has a spapplication, make sure thsecurity class for the sechave an operator definitiospecific operator definitiooperator definition for the

“Password expired on date” The user’s password has expired.

If the user’s need to accuser’s operator definitionthe application in questiothe SOD form.

“WARNING: Your password expires on date.

See your security administrator“

The user’s access to the application is near its end.

If the user’s access to thspecified, do nothing: theapplication on or after thhave access to the applidate on the SOD form.

“Access to appl has been denied” Invalid operator definition or incorrect Envision password.

If this message appears Envision password. If theuser type in the correct pthought was the correct on the SOD form. If this msee above for the other m

Message Cause

Page 261: Envision Runtime Administration

Troubleshooting

Envision Diagnostics

In This ChapterThis chapter provides information that helps explain and demonstrate the various diagnostic systems available in Envision. Table 15 lists the topics covered in this chapter.

Table 15: Topics in this Chapter

Topic Page

Overview of the GRDS System 262

System Integrity Checking 263

Envision On-demand Diagnostic Systems 264

On-demand Diagnostics Using GRDS 266

Automatically Generated Services 279

Programmer-Specified Services 285

Accessing GRDS 286

On-demand Diagnostics Using the UTDB Form 288

GRDS and UTDB: Do They Interact? 292

Runtime Administration, March 10, 2010 261© 2010 Datatel, Inc.

Page 262: Envision Runtime Administration

Troubleshooting: Envision Diagnostics

Overview of the GRDS SystemThe Generated Runtime Diagnostic Services (GRDS) system encompasses two different runtime functionalities:

1. System Integrity Checking. This enables the system to continually perform integrity checks as it runs. This functionality runs continuously and does not require anyone to manually activate it. Among other things, this functionality employs:

The following Envision-Based Software Language (EBSL) statements: CONFIRM and THROW_ERROR.

The following forms: • Set Session Confirm Level (SSCL)• Thrown Errors – List (TELI)• Thrown Errors – Detail (TEDT)• Thrown Errors – Purge (TEPU)

2. Diagnostic Logging. This enables logging of runtime diagnostic output. This is an on-demand feature. It must be manually turned on and off by a developer or support staff whenever they need such information for training, development, or troubleshooting. Among other things, this functionality employs:

The following EBSL statements: SHOWA and SHOWC

The following forms:• Turn GRDS Logging On (GRS1) • Turn GRDS Logging Off (GRS0)• GRDS Services Set (GRSS)• GRDS Service Detail (GRSD)• Process Group Definition (PRGR)• Monitor tail end of OS file (TAIL)

262 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 263: Envision Runtime Administration

System Integrity Checking

System Integrity CheckingThe GRDS system facilitates the embedding of self-diagnostic code into Envision processes. This code tests for required (expected) conditions and values, and displays and logs an error if the test fails. (The display is suppressed when running in background mode or in WebAdvisor). These types of errors are usually an indication of either a bug or data corruption.

The errors are logged to the UT.THROWN.ERRORS file. The contents of the UT.THROWN.ERRORS file can be examined by using the Thrown Errors – List (TELI) form and purged with the Thrown Errors – Purge (TEPU) form.

System administrators have control over the amount of system resources that the system devotes to self-diagnosis. By adding a "SET.CONFIRM.LEVEL" statement to the LOGIN paragraph, they can increase or decrease this for a given environment. System administrators should use

SET.CONFIRM.LEVEL 2

for the greatest amount of checking, and use

SET.CONFIRM.LEVEL 0

for the least amount of checking. (Deleting the command from the LOGIN paragraph is equivalent to setting the level to 0.)

Datatel highly recommends that the level be set to the highest number in every test and development environment.

It is also possible to temporarily change the level for just the login session, without affecting other users. The Set Session Confirm Level (SSCL) form can be used to do this. The online help for the SSCL form provides more information.

See the statements CONFIRM and THROW_ERROR in the Envision Basic Commands Reference manual for more information on how developers add integrity checks to their processes.

Runtime Administration, March 10, 2010 263© 2010 Datatel, Inc.

Page 264: Envision Runtime Administration

Troubleshooting: Envision Diagnostics

Envision On-demand Diagnostic Systems

There are two on-demand diagnostic systems for Envision: the Generated Runtime Diagnostic Services (GRDS) system and the older UT Process Debug Activation (UTDB) form.

The Generated Runtime Diagnostic Services (GRDS) is a subsystem of Envision that uses the generator to embed diagnostic code into processes. The GRDS system is designed to make it easier and quicker to debug and analyze Envision-generated processes.

You can also still use the UT Process Debug Activation (UTDB) form to trigger diagnostic code that predates the GRDS system, but it is important to understand that the GRDS system is backward compatible with the UTDB process. By requesting any numeric GRDS service, all diagnostic codes that predate the GRDS system will also be triggered. There is no need to use the UTDB form for non-WebAdvisor debugging.

Both systems can help you determine possible sources of problems, however, the GRDS system is the newer, improved system for debugging Envision. Although you can still use the UTDB form to help you determine possible sources of problems, the GRDS system is significantly more powerful and easier to use.

Advantages of Using the GRDS System

Auto-generated Logging Services

GRDS provides services that are not available using the UTDB form. Among these are automatically generated (thus universally available) services. For more information see “Automatically Generated Services” on page 279.

264 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 265: Envision Runtime Administration

Envision On-demand Diagnostic Systems

Self-Diagnostic Services

GRDS supports Triggered Assertion Checking. The IT industry also refers to this concept as “Embedded Self-diagnostics”, “Enforced Design by Contract”, or similar terminology. For more information, see “System Integrity Checking” on page 263.

Log Saved to Disk

The UTDB process does not save its diagnostics. The text is displayed, one piece of information at a time, and then disappears. You cannot easily collect the diagnostics into a seamless, cross-process picture of the entire session.

GRDS collects an entire session’s diagnostics into a single chronological view, and into a log file. The log file is written to disk, which allows you to review the log later, or transmit the log via e-mail. For more information, see the “Sample GRDS Log” beginning on page 267.

Easy to Use, Efficient, and Consistent

GRDS diagnostics do not interfere with (corrupt or hide) your currently displayed screen. You (or someone at another work station) can view the diagnostics in real time in a separate window.

It is easier to embed additional diagnostics into your processes using GRDS, because the generator takes over as much of the work as possible. See “Automatically Generated Services” on page 279 and “Programmer-Specified Services” on page 285.

The code generated for GRDS tends to be more efficient than what was hand-coded for the UTDB form. This is true when debugging is inactive, and often true even when it is active.

Because GRDS is generated code, it provides more consistency. For example, various inserts and macros have been developed to initialize DATATEL.DEBUG in the UTDB process. GRDS is implemented the same way in all processes.

GRDS enforces using the process ID as the trigger string. To access GRDS diagnostics for process X, then X is the process for which you request services without exception.

Runtime Administration, March 10, 2010 265© 2010 Datatel, Inc.

Page 266: Envision Runtime Administration

Troubleshooting: Envision Diagnostics

On-demand Diagnostics Using GRDSThe main components of the Generated Runtime Diagnostic Services (GRDS) system are:

Dormant blocks of code embedded in Envision-generated source code files. Many types of diagnostic services are available, each associated with its own service code.• These blocks of code provide GRDS “services.”• Each block of code is wrapped in a conditional statement that allows it to

execute only when its related service code is requested for a process. • The generator creates most of this code. However, GRDS allows you to

create additional service code blocks manually.

Envision-Based Software Language (EBSL) statements that allow you to manually add GRDS service code blocks to a process with minimal effort.

A trigger mechanism for requesting GRDS services. • You specify the service(s) you want to activate for each process or

collections of processes. • You can see a list of available service codes by accessing validation code

GRDS.SERVICES on the Validation Codes (VAL) form. You can request these services using the Runtime Analytic Services ON (GRS1) form.

Figure 43: View Service Codes on VAL

266 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 267: Envision Runtime Administration

On-demand Diagnostics Using GRDS

GRDS allows you to activate a specified set of diagnostic services. These services produce diagnostic text at runtime. All of the text is collected in chronological order into a single log file. You can request services for all processes, selected groups of processes, or specific processes.

GRDS log services can be classified into two types: automatically generated and programmer-specified.

“Automatically Generated Services” beginning on page 279 are those that are automatically embedded into a process by the generator. You do not need to do anything in order for these services to be available. They are universally available for every Envision-generated process except external (EGP) processes.

“Programmer-Specified Services” beginning on page 285 are available only if you have added supporting code to a process. Although these services require you to embed code into a process, the GRDS system introduces two keywords that make this easy to do: SHOWA and SHOWC. See the Envision Basic Commands Reference manual for more information.

Sample GRDS Log

This section explains the features of a GRDS log.

Part 1: Runtime Environment Information

The top of a GRDS log shows runtime environment information, as shown in the following example.

Log ID.....: SAMPLEStarted....: 00:04:16 Aug 23 2006User.......: jgvServer.....: SDW2K3APPEnvironment: D:\dev\etk48devOS.........: Windows NTUniData....: 6.1 Build: (5150)UDT.OPTIONS ON: 41 U_UDT_SERVER ON 46 U_UNFLUSHDATA ON 88 U_CALLC_CDECL ON

Runtime Administration, March 10, 2010 267© 2010 Datatel, Inc.

Page 268: Envision Runtime Administration

Troubleshooting: Envision Diagnostics

Part 2: Services Requested

The next section shows what was requested.

---------------------------------------------------------------GRAS.REQUEST.SET record used: SAMPLE--------------------------------------------------------------- Service Requests ================ 1) * / 1,PE,KS,CC,GS,AE,PX,AD,ET,NK,HE,HX,HS,SD 2) S.DEBUG.INIT / 3) S.CHECK.PROCESS.LEVEL /---------------------------------------------------------------

Part 3: Diagnostic Text

The snippets below are selected segments of a single log file. See “How to Read a GRDS Log” on page 270 for more information about the diagnostic text portion of the log.

2_\ 2_3| pe} * MENU_PRCSR (from MENU.INIT @1710) 2_3| cc} 1=UT.INIT@52 2=MENU.INIT@1710 3=MENU_PRCSR@15 2_3| gs} GEN V4.8.1 / 02:08:38 Aug 22 2006 / SDW2K3APP / jgv / etk48grds 2_3| ks} No active select lists 2_3| ae} Arg 1: MENU.ID =UT 2_3| ae} Arg 2: POP.MENU = 2_3| ae} -------------<>------------- 2_3_\ 2_3_4| pe} * ACCEPT_DATA (from MENU_PRCSR @1814) 2_3_4| cc} 1=UT.INIT@52 2=MENU.INIT@1710 3=MENU_PRCSR@1814 4=ACCEPT_DATA@15 2_3_4| gs} GEN V4.8.1 / 02:08:00 Aug 22 2006 / SDW2K3APP / jgv / etk48grds 2_3_4| ks} No active select lists 2_3_4| ae} Arg 1: PROCESS.ID =UT 2_3_4| ae} Arg 2: AR.VWVAR: MAT(25) 2_3_4| ae} (1) =1 2_3_4| ae} (12) =0010001111111011110011 2_3_4| ae} Arg 3: MAX.PRMPT =1 2_3_4| ae} Arg 4: V.BASE.LINE has 2 fields 2_3_4| ae} Arg 5: AR.CWVAR: MAT(50,25) 2_3_4| ae} (1,1) =MENU_PRCSR 2_3_4| ae} (1,7) =10 2_3_4| ae} (1,8) =10 2_3_4| ae} (1,9) =10 2_3_4| ae} (1,10) =20 2_3_4| ae} (1,20) has 2 fields 2_3_4| ae} <2> =1 2_3_4| ae} (1,21) =Enter Mnemonic or Selection Number, or press FINISH 2_3_4| ae} Arg 6: R.CWSTATE has 2 fields 2_3_4| ae} <1> =1 2_3_4| ae} <2> =1 2_3_4| ae} -------------<>-------------

268 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 269: Envision Runtime Administration

On-demand Diagnostics Using GRDS

2_3_4| ad} Arg 2: AR.VWVAR: MAT(25)2_3_4| ad} (2) =XGUS2_3_4| ad} (12) =0010001111111011110011001000111111101111001110111101110000002_3_4| ad} (16) =02_3_4| ad} Arg 5: AR.CWVAR: MAT(50,25)2_3_4| ad} AR.CWVAR: <no change>2_3_4| ks} No active select lists2_3_4| et} ACTUAL=2063 CPU=16 (milliseconds)2_3_/ px} * RETURN to MENU_PRCSR @1814 (from ACCEPT_DATA)2_3| ad} <no change>2_3| ks} No active select lists2_3| et} ACTUAL=2078 CPU=16 (milliseconds)

...

2_3| 1} @60: X.TEST.STRING has 10 fields:2_3| 1} <1> =THIS2_3| 1} <2> =IS2_3| 1} <3> =A} 2 {TEST} 3 {OF}2_3| 1} <4> =MULTI-FIELD2_3| 1} <5> =SHOWA2_3| 1} <6> =WITH2_3| 1} <7> =3rd2_3| 1} <8> =fld2_3| 1} <9> =having2_3| 1} <10> =3values

...

2_3| hs} -->Enter FLD_ENTRY hook of F5 (GUS.FILE.ID)2_3| hx} <- Leave FLD_ENTRY hook of F5 (GUS.FILE.ID)2_3| hs} -->Enter FLD_ACCEPT hook of F5 (GUS.FILE.ID)2_3_\2_3_4| pe} * ACCEPT_DATA (from S_GUS @1916)2_3_4| cc} 1=UT.INIT@52 2=MENU.INIT@2045 3=S_GUS@1916 4=ACCEPT_DATA@152_3_4| gs} GEN V4.8.1 / 02:08:00 Aug 22 2006 / SDW2K3APP / jgv / etk48grds2_3_4| ks} No active select lists2_3_4| ae} Arg 1: PROCESS.ID =S_GUS

...

2_3_4| 1} @123: XTEST1 =THIS HAS~A CONTROL CHARACTER IN IT !Contains non-printing characters!2_3_4| 2} @124: XTEST2 =This has 200 trailing blanks<- +200 trailing spaces!

...

2_3| 1} @542: SHOWA $TABLE(GUSV.A1,GUSV.A2,GUSV.A3)2_3| 1} GUSV.A1 GUSV.A2 GUSV.A32_3| 1} ======= ======= =======2_3| 1} 1) F G H2_3| 1} 2) I J K

...

2_3| --------------------------------------------------------------2_3| Closing GRDS session log "SAMPLE" at 00:04:31 Aug 23 2006

Runtime Administration, March 10, 2010 269© 2010 Datatel, Inc.

Page 270: Envision Runtime Administration

Troubleshooting: Envision Diagnostics

How to Read a GRDS Log

Chain Prefix

Every line begins with the call chain prefix. This is a series of integers that represents the current call chain.

To reduce the size of the log (and because it never changes), process 1 is omitted. Each integer stands for one process currently active in the chain.

2_3_4| ad} Arg 2: AR.VWVAR: MAT(25)

Outliner

After the chain prefix is either a "\", "/" or "|"

A "\" indicates that the call chain is getting larger.

A "/" indicates that the call chain is getting smaller.

Service Code

Next, there is usually a space, the service code that caused that line to be logged, a right brace "}", and the diagnostic text.

2_3_4| ad} Arg 2: AR.VWVAR: MAT(25)

Process Entry

The process entry (pe) line is always preceded by a blank line. This makes it easier to locate where a process started up.

2_3| ks} No active select lists2_3_\2_3_4| pe} * ACCEPT_DATA (from MENU_PRCSR @1814)

A process entry line shows the ID of the process starting up, and how it was invoked. In the example above, it shows that ACCEPT_DATA was called from line 1814 of process MENU_PRCSR.

270 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 271: Envision Runtime Administration

On-demand Diagnostics Using GRDS

Process Exit

A process exit (px) line shows a process terminating, and shows where the returned-to process resumes.

In the example below, it shows ACCEPT_DATA terminating and MENU_PRCSR resuming at line 1814.

2_/ px} * RETURN to MENU_PRCSR @1814 (from ACCEPT_DATA)

Call Chain Service

A line produced by the call chain (cc) service maps each of the integers in the line’s prefix to a process ID.

In the example below, it shows:

Currently at line 15 of MENU_PRCSR, the third and last piece of the call chain.

MENU.INIT is waiting for MENU_PRCSR to finish, at which time it will resume at line 1710.

UT.INIT is waiting for MENU.INIT to finish, at which time it will resume at line 52.

2_3| cc} 1=UT.INIT@52 2=MENU.INIT@1710 3=MENU_PRCSR@15

Arguments

Process arguments are shown with the abbreviation "Arg". In the following example, the process’ third argument’s name is MAX.PRMPT and its value is "1".

2_3_4| ae} Arg 3: MAX.PRMPT =1

Field Counters

Field counters are shown inside angle brackets. The following two lines show that field 6 of R.CWSTATE has a value of "Bob".

2_3_4| ae} Arg 6: R.CWSTATE has 10 fields2_3_4| ae} <6> =Bob

Runtime Administration, March 10, 2010 271© 2010 Datatel, Inc.

Page 272: Envision Runtime Administration

Troubleshooting: Envision Diagnostics

Null Fields

Fields with no data are skipped (to minimize log size). In the previous example, because field 6 was the first field shown, the first five fields of R.CWSTATE were null.

Matrix Dimensions

Matrix dimensions are shown in parentheses, as are cell indexes.

The following two lines show that the process’ second argument is AR.VWVAR, that it is a one-dimensional matrix of 25 cells, and that the third cell contains the value “MD”:

2_3_4| ae} Arg 2: AR.VWVAR: MAT(25)2_3_4| ae} (3) =MD

Null Matrix Cells

In order to minimize the size of the log, matrix cells with no data are skipped.

In the previous example, AR.VWVAR(1) and AR.VWVAR(2) are both null because they were skipped (cell number 3 was the first one shown)

Null Value

A null value is shown with nothing after the equal sign.

2_3| ae} Arg2: POP.MENU =

Leading Spaces

The presence of leading spaces can be seen following the equal sign.

In the following example, it is evident that there are three leading spaces:

2_3| ae} Arg2: POP.MENU = CSEG^^^

272 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 273: Envision Runtime Administration

On-demand Diagnostics Using GRDS

Trailing Spaces

Trailing blanks are not printed, but their presence is indicated:

Strings with Embedded Field Marks

A string (simple variable or individual matrix cell) that contains field marks is identified as a multi-field entity. The field count is given, but null (empty) fields are not shown.

Some of the many things that can be determined from the following example are:

Neither of the two fields in the fourth argument have data.

AR.CWVAR(1,2) is null (as are (1,3), (1,4), (1,6), (1,7)...

The first field of AR.CWVAR(1,20) has no data.

Argument 6 contains three characters (an "X", a field mark, and a "Y").

AE/AD separator

The last line produced by the "ae" (Arguments at Entry) service is a line of dashes. This serves to visually separate it from lines produced by the "ad" (Argument Differences) service.

2_3_4| ae} ARG 1: A.TYPECODE =C22_3_4| ae} -------------<>-------------2_3_4| ad} ARG 1: A.TYPECODE =

2_3_4| 2} @124) XTEST2 =This has 200 trailing blanks<- +200 trailing spaces!

2_3_4| ae} Arg 4: V.BASE.LINE has 2 fields2_3_4| ae} Arg 5: AR.CWVAR: MAT(50,25)2_3_4| ae} (1,1) =MENU_PRCSR2_3_4| ae} (1,5) =102_3_4| ae} (1,8) =102_3_4| ae} (1,9) =102_3_4| ae} (1,10) =202_3_4| ae} (1,20) has 2 fields2_3_4| ae} <2> =12_3_4| ae} (1,21) =Enter Mnemonic or Selection Number, or press FINISH2_3_4| ae} Arg 6: R.CWSTATE has 2 fields2_3_4| ae} <1> =X2_3_4| ae} <2> =Y

Runtime Administration, March 10, 2010 273© 2010 Datatel, Inc.

Page 274: Envision Runtime Administration

Troubleshooting: Envision Diagnostics

Current Location

Lines produced by SHOWA or SHOWC log their current location (the line number in the generated source).

The example below shows a diagnostic line that was produced by line 60 of the process.

2_3| 1} @60: X.TEST.STRING has 10 fields

Multi-valued Data

Fields are shown one per line, but multiple values of the same field are shown on the same line.

In the example below, the third field of X.TEST.STRING contains three values:

The first is "A"

The second is "TEST"

The third is "OF"

2_3| 1} @60: X.TEST.STRING has 10 fields2_3| 1} <1> =THIS2_3| 1} <2> =IS2_3| 1} <3> =A} 2 {TEST} 3 {OF}

^ ^^^^ ^^

Screen Hooks

Screen hook startups and shutdowns are shown with arrows:

"-->Enter ... hook" indicates a screen hook starting.

"<-Leave ... hook" indicates a screen hook finishing.

2_3| hs} -->Enter FLD_ENTRY hook of F5 (GUS.FILE.ID)2_3| hx} <- Leave FLD_ENTRY hook of F5 (GUS.FILE.ID)2_3| hs} -->Enter FLD_ACCEPT hook of F5 (GUS.FILE.ID)

274 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 275: Envision Runtime Administration

On-demand Diagnostics Using GRDS

Control Characters

Non-printing characters are replaced by the tilde character, and a warning is issued:

$TABLE

The effect of the $TABLE function of the SHOWA statement is shown below.

The developer specified the following:

SHOWA $TABLE(GUSV.A1)

And the system logged the following:

2_3| 1} @542: SHOWA $TABLE(GUSV.A1,GUSV.A2,GUSV.A3)2_3| 1} GUSV.A1 GUSV.A2 GUSV.A32_3| 1} ======= ======= =======2_3| 1} 1) F G H2_3| 1} 2) I J K

The system added GUSV.A2 and GUSV.A3, because it knew that GUSV.A1 was part of a subfile that also contained GUSV.A2 and GUSV.A3.

The net result was that it behaved as if

$TABLE(GUSV.A1,GUSV.A2,GUSV.A3)

had been specified.

2_3_4| 1} @123: XTEST1 =THIS HAS~A CONTROL CHARACTER IN IT !Contains non-printing characters! ^ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Runtime Administration, March 10, 2010 275© 2010 Datatel, Inc.

Page 276: Envision Runtime Administration

Troubleshooting: Envision Diagnostics

Context Markers

In order to provide points of references in the log, the system will add Context Markers whenever you select a mnemonic or enter data. These context markers are designed to stand out in the log.

The lines shown below that start with "*" are a context marker. It shows that the SOD mnemonic was selected at this point.

The context marker below shows that "JGV..." was entered into the SOD form’s LookUp prompt.

2_3_\2_3_/ px} * RETURN to MENU_PRCSR @1732 (from S_MIO_READ)*_3|*_3| !!} ================================================================*_3| !!} MNEMONIC: UT-SOD*_3| !!} ================================================================*_3|2_/ px} * RETURN to MENU.INIT @2094 (from MENU_PRCSR)

2_3_/ px} * RETURN to UTOPRS @2990 (from S_MIO_READ)*_3|*_3| !!} ===================================================================*_3| !!} INPUT.DATA: --> JGV... <-*_3| !!} ===================================================================*_3|2_3_\ pe} * S.GET.RESOLUTN (from UTOPRS @3072)

276 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 277: Envision Runtime Administration

On-demand Diagnostics Using GRDS

Gap Detection

When the system detects a gap in the call chain, it inserts extra lines as needed in order to provide context to the diagnostic text being logged.

For example, suppose you had requested just the following:

UTOPRS / PE, CC, PX S_MIO_READ / PE, CC, PX

(The PE, CC, and PX services for processes UTOPRS and S_MIO_READ only.)

You might end up with something like the following (line numbers 397-417 added for instructional purposes):

Note that the only service lines you actually requested were the ones marked with a square bracket. The rest were filled in by the system when it detected gaps.

... 397] 2_3_4_\ 398] 2_3_4_5| pe} * S_MIO_READ (from S.GET.RESOLUTN @145) 399] 2_3_4_5| cc} 1=UT.INIT@49 2=MENU.INIT@1981 3=UTOPRS@3072 ... 5=S_MIO_READ 400] 2_3_4_/ px} * RETURN to S.GET.RESOLUTN @145 (from S_MIO_READ) 401. 2_3_/ --} * RETURN to UTOPRS @12 (from S.GET.RESOLUTN) 402. 2_3_\ ++} * S.INPT.SEL.ID.LKUP (from UTOPRS @3072) 403. 2_3_4_\ ++} * S.LKUP.ID.PARSE (from S.INPT.SEL.ID.LKUP @335) 404. 2_3_4_5_\ ++} * S.SELECT.LISTS (from S.LKUP.ID.PARSE @154) 405. 2_3_4_5_6_\ ++} * S_MIO_EXECUTE (from S.SELECT.LISTS @594) 406. 2_3_4_5_6_7_\ ++} * S_MIO_SEL (from S_MIO_EXECUTE @473) 407] 2_3_4_5_6_7_8_\ 408] 2_3_4_5_6_7_8_9| pe} * S_MIO_READ (from S_MIO_SEL @784) 409] 2_3_4_5_6_7_8_9| cc} 1=UT.INIT@49 2=MENU.INIT@1981 3=UTOPRS@3072 ... 9=S_MIO_READ 410] 2_3_4_5_6_7_8_/ px} * RETURN to S_MIO_SEL @784 (from S_MIO_READ) 411. 2_3_4_5_6_7_/ --} * RETURN to S_MIO_EXECUTE @473 (from S_MIO_SEL) 412. 2_3_4_5_6_/ --} * RETURN to S.SELECT.LISTS @594 (from S_MIO_EXECUTE) 413. 2_3_4_5_/ --} * RETURN to S.LKUP.ID.PARSE @154 (from S.SELECT.LISTS) 414. 2_3_4_5_\ ++} * UTRESO (from S.LKUP.ID.PARSE @565) 415] 2_3_4_5_6_\ 416] 2_3_4_5_6_7| pe} * S_MIO_READ (from UTRESO @21) 417] 2_3_4_5_6_7| cc} 1=UT.INIT@49 2=MENU.INIT@1981 3=UTOPRS@3072 ... 7=S_MIO_READ ...

Runtime Administration, March 10, 2010 277© 2010 Datatel, Inc.

Page 278: Envision Runtime Administration

Troubleshooting: Envision Diagnostics

For example, after logging line 400 (RETURN to S.GET.RESOLUTN), the next line it needed to log was the startup of S_MIO_READ by S_MIO_SEL. The system detected a gap in the call chain, so it filled in that gap with "--}" and "++}" lines. This allows you to see how you got from one process to the next.

278 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 279: Envision Runtime Administration

Automatically Generated Services

Automatically Generated ServicesAn automatically generated service is embedded into a process by the generator. You do not need to do anything in order for these services to be available. They are universally available for every Envision-generated process except external (EGP) processes. Table 16 lists automatically generated services by the code used to trigger them.

Table 16: Automatically Generated Services

Code Description

At Process Entry

PE PROCESS ENTRY: Log the ID of the process as it starts up.

NS NUMBER SELECTED: Log size of select lists active at process start.

KS KEYS SELECTED: List keys in select list active at process start.

CC CALL CHAIN: Log how process was invoked (show full call chain).

GS GEN STAMP: Log last GEN date/time/version/who.

AE ARGUMENTS at ENTRY: Log initial value of process arguments.

In Mid-Process

NK NEXT KEY: Log each key value as it is processed by FOR_...SELECTED...

HE HOOK ENTRY: Log and identify screen hooks starting up.

HX HOOK EXIT: Log that a screen hook is done.

HS HOOK SEQUENCE: Log order in which screen hooks are (or would be) executed.

SD SHOW DEMANDED: Show V., VL., KV., and KEY. vars when change detected.

At Process Exit

NS NUMBER SELECTED: Log size of select lists active at process start.

KS KEYS SELECTED: (Behaves like NS at process exit)

AX ARGUMENTS at EXIT: Log final value of process arguments.

AD ARGUMENT DIFFERENCES: Like AX, but log only changed arguments.

ET ELAPSED TIME: Log actual and CPU milliseconds.

PX PROCESS EXIT: Log process ending.

Runtime Administration, March 10, 2010 279© 2010 Datatel, Inc.

Page 280: Envision Runtime Administration

Troubleshooting: Envision Diagnostics

AE, AX & AD (Process Argument Services: Entry, Exit, Difference)

These services show the value of the process arguments.

AE shows them at the start of the process.

AX shows them at the end of the process.

AD does the same as AX, but shows only those that were changed by the process.

If both AX and AD are requested, then only one is honored, depending on whether or not AE was also requested. This is done to avoid showing redundant information:

Requesting all three results in only AE and AD being honored.

Requesting AX and AD, but not AE, results in only AD being honored.

Note that AE, AX, and AD can also be associated with the SHOWA or SHOWC statements. Often a process will pass data in or out via COMMON rather than arguments defined to Envision. In that case, requesting the "AE" (Arguments at Entry) service for that process will show you an incomplete picture of the data flowing in and out of that routine. By allowing "@AE" as part of the syntax of the SHOWA statement, you can add those "undefined to Envision" arguments to be logged whenever the AE service is requested (similarly for AX and AD).

PE & PX (Process Entry & Process Exit)

The PE service increases the logs indentation level, then logs a line showing:

The ID of the process.

The fact that it is starting up.

The ID of the process that invoked it (its parent process).

The current line number of the parent process.

280 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 281: Envision Runtime Administration

Automatically Generated Services

The PX service decreases the logs indentation level, first logging a line showing:

The ID of the process.

The fact that it is ending.

The ID of the process to which control is being returned (its parent process).

The current line number of the parent process (line number where execution resumes).

CC (Call Chain)

The CC service logs a single line showing the complete call chain, complete with process IDs and line numbers.

GS (GEN Stamp)

The GS service logs a line showing information about the last time the process was generated:

Date

Time

Who (Login ID of user)

Account name

Server name

NK (Next Key)

The NK service provides diagnostics for processes that use the "FOR_... SELECTED..." syntax. With each iteration of the loop, immediately after the key is obtained from the active select list, its value is logged to the GRDS buffer and the buffer is forced to flush (even if not yet full).

Runtime Administration, March 10, 2010 281© 2010 Datatel, Inc.

Page 282: Envision Runtime Administration

Troubleshooting: Envision Diagnostics

The NK service is useful in determining the cause of a process abort. Because it forces the GRDS buffer to flush to disk (to the log file), the value of the key is written to the log before the system reads the record. If the process aborts, determining which key was being processed at the time of the abort is just a matter of looking at the last line of the log.

NS & KS (Number Selected & Keys Selected)

At process exit, NS and KS behave the same. If both were requested, only KS is done.

If none of UniData’s ten possible active select lists (numbered 0-9) are active, then at process entry, both NS and KS log the same message "No active select lists." (If both were requested, only KS is done.) At process exit, neither NS nor KS add anything to the log.

If at least one of the select lists is active, then NS behaves the same way at process entry and process exit. It logs the count of keys active in each of the ten lists that are active. KS behaves differently at process entry than at process exit: • At process exit, KS behaves exactly like NS (if both are requested, only KS

is done at process exit). • At process entry it logs not only the key count, but also the actual keys

themselves (but only for list #0, the default list). For lists 1-9, KS provides only a count of the number of active keys – it does not log the actual keys themselves.

If there are more than 75 keys active then, in the interest of keeping the log from becoming too large, the keys are copied to a savedlist, and the name of the savedlist is provided in the log.

282 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 283: Envision Runtime Administration

Automatically Generated Services

HS, HE, & HX (Hook Services: Sequence, Entry, Exit)

All three hook services will log at least one line of text per screen hook. They provide context information (“now at this hook”). The same context information is shown by all three services.

Hook Name

Point of processing (is hook about to start or just ended?)

Field name and number (if a field hook)

Window row (if field hook and field is a window)

Value of active variable (only for the three hooks listed below) • Input Source hook: INPUT.DATA • Input Edit hook: EDITED.DATA • Output Edit hook: OUTPUT.DATA

They differ only in when they execute:

HE (Hook Entry). When the hook is about to start (but only if the hook has any code specification for it).

HX (Hook eXit). When the hook has ended (but only if the hook had any code specification for it).

HS (Hook Sequence) is like a combination of both HE and HS, logging both a "hook X is starting" line and a "hook X has ended" line. It therefore overrides the other two services (the others are ignored if HS is requested).

It differs from HE and HX in that it provides these context lines even if there is no code specification for the hook.

The HS service is useful when you are not certain of what the order of hook processing is within an Envision form. It makes the timing and sequence of the hooks clear.

SD (Show Demanded)

The SD service checks the value of all V., VL., KV., KEY., and .ADD.MODE variables for all demanded files and fields, and logs their value whenever they have been changed. In both form and batch processes, the check is performed after records are parsed (that is, after READ and after return from CALL_SCREEN and CALL_SUBR). In form processes the check is also performed at the start and end of every process and field hook.

Runtime Administration, March 10, 2010 283© 2010 Datatel, Inc.

Page 284: Envision Runtime Administration

Troubleshooting: Envision Diagnostics

One use for this service is to reveal invisible data (process data not shown on screen):

The value of phantom fields.

The value of additional (non-displayed) demand fields, such as system parameters.

The actual value behind a field (as opposed to the displayed value).

The service also helps clarify when these variables are assigned (for a form process, try combining the HS and SD services).

ET (Elapsed Time)

This provides a line indicating how many milliseconds the process took.

284 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 285: Envision Runtime Administration

Programmer-Specified Services

Programmer-Specified ServicesProgrammer-specified services are available only if you added supporting code to your process.

The GRDS system keywords SHOWA and SHOWC allow you to easily embed code into processes as required by these manual services.

The services that use one-character codes (1, 2, 3, 4, 5, 6, 7, 8, 9, A through Z) produce diagnostic text only if you manually added either SHOWA or SHOWC statements to your process. See the Envision Basic Commands Reference manual for more information.

The numeric codes are cumulative. Requesting one automatically requests all lower-numbered services as well. Services A through Z are independent of one other. They are not cumulative.

Table 17: Programmer-specified Services

Code Description

1 Show manually added level 1 diagnostics

2 Show manually added diagnostics Levels 1-2

3 Show manually added diagnostics Levels 1-3

4 Show manually added diagnostics Levels 1-4

5 Show manually added diagnostics Levels 1-5

6 Show manually added diagnostics Levels 1-6

7 Show manually added diagnostics Levels 1-7

8 Show manually added diagnostics Levels 1-8

9 Show manually added diagnostics Levels 1-9

A through Z Show manually added diagnostics for only the letter selected

Runtime Administration, March 10, 2010 285© 2010 Datatel, Inc.

Page 286: Envision Runtime Administration

Troubleshooting: Envision Diagnostics

Accessing GRDSAccess the Envision Diagnostic Tools (EDT) menu in UT under the System User (SU) menu.

Figure 44: Envision Diagnostic Tools Menu

Set Session Confirm Level (SSCL)

The SSCL form allows you to set the session CONFIRM level.

GRDS Services Set (GRSS)

The GRSS form allows you to define named sets of service requests.

Turn GRDS Logging On (GRS1)

The GRS1 form allows you to turn GRDS logging on.

Turn GRDS Logging Off (GRS0)

The GRS0 form allows you to turn GRDS logging off.

286 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 287: Envision Runtime Administration

Accessing GRDS

Monitor tail end of OS file (TAIL)

The TAIL form mimics UNIX's tail command in that it allows you to monitor an OS-level file as it grows. It does so in a platform-independent way. The TAIL form can be used by person A to monitor person B’s GRDS diagnostic log.

Thrown Errors – Detail (TEDT)

The TEDT form displays all information about one specific entry in the UT.THROWN.ERRORS file.

Thrown Errors – List (TELI)

The TELI form displays a list of entries in the UT.THROWN.ERRORS file.

Thrown Errors – Purge (TEPU)

The TEPU form allows you to purge entries from the UT.THROWN.ERRORS file.

Process Group Definition (PRGR)

The PRGR form allows you to define named groups of Envision process IDs. These groups can then be referenced on the GRDS service request forms (GRSS and its detail form GRSD) to quickly request the same set of services for a collection of processes.

Runtime Administration, March 10, 2010 287© 2010 Datatel, Inc.

Page 288: Envision Runtime Administration

Troubleshooting: Envision Diagnostics

On-demand Diagnostics Using the UTDB Form

This section describes how to use the UT Process Debug Activation (UTDB) form. Activating debug mode for a process consists of the following steps:

1. Research the name of the debug string embedded in the program.

2. Enter the debug string on the UTDB form.

3. Run the Envision program you want to debug.

Research the Debug String

To make it possible for a program to run in debug mode, programmers embed a debug string (usually a process ID or form mnemonic) in the code of that program. The debug string is a unique name that identifies the program for the Envision debug processing. The first step in using the UTDB form to debug a process is to examine the code to determine this name. Programmers also create debug messages within the code. Envision displays these messages whenever you run the program in debug mode.

Programmers generally place Envision debug messages within a statement that checks the value of the special variables DATATEL.DEBUG and DATATEL.DEBUG.LEVEL.

Example

IF DATATEL.DEBUG THEN XL.DEBUG.MSG<-1> = "entering special process, v.id =":V.ID XL.DEBUG.MSG<-1> = "v.last.name =":V.LAST.NAME $INSERT I_DEBUGEND

288 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 289: Envision Runtime Administration

On-demand Diagnostics Using the UTDB Form

Specify UT Process Debug Activation (UTDB) Parameters

To turn on the Envision debug mode for a process, enter the process’s unique debug name into the appropriate fields on the UTDB form. The information you enter on this form is appended to special variable UT.DEBUG.STRING. The process continues to run in Envision debug mode for as long as you are logged into the current session, or until you use the Clear String fields to clear the debug string.

Use the UTDB form shown in Figure 45 to activate debug mode.

Figure 45: UT Process Debug Activation (UTDB) Form

Step 1. To quickly remove all current debug strings for UI Desktop/web, enter Y in the Clear String field. The entire string is reset to Null. This field does not clear the WebAdvisor debug strings.

Technical Tip: Use the fields in the upper part of this form for debugging UI Desktop/web processes. The fields in the lower part of the form are used to debug WebAdvisor processes. Information about debugging WebAdvisor processes is available in WebAdvisor documentation and online help for the UTDB form.

Runtime Administration, March 10, 2010 289© 2010 Datatel, Inc.

Page 290: Envision Runtime Administration

Troubleshooting: Envision Diagnostics

Step 2. Enter a process debug name for the process that you want to debug in the Modify String field. When you enter text, the Debug String field is updated. You may add multiple debug strings. Spaces in the text are ignored by the debug string.

Step 3. For processes with a large amount of debug information, you may want to see only certain levels of output. You can set the level of debug information from 1 to 99; 1 showing the least amount of information, and 99 showing the most. Envision defaults to 1.

Step 4. Enter Y to clear the read cache log that is generated when read-cache logging is on. If your read cache size is a negative number, MIO logs all read requests into the HOLD file under a key name of USERID.READ.CACHE, (where USERID is an upper case version of your login id).

Step 5. Enter Y to turn on MIO (Main Input/Output) debugging. After entering Y, saving from this form, and accessing a form that runs MIO functions, you begin to receive MIO debug messages.

Step 6. Override the default cache size for this session by entering a number between -1000 and 1000. The default read cache size is taken from the Read Cache Size field on the Envision Parameters Edit (EPED) form (for Envision 4.7). (If no value exists on the EPED form, then 100 is used as the default.)

Enter zero to turn the cache off. Enter a negative number to turn a read log to on. A record is written to the HOLD file, which is named USERID.READ.CACHE (where USERID is an upper case version of your login name). The log file notes each file and record read, along with the number of times a cache hit occurred, and the number of physical reads that occurred.

WebAdvisor debug mode remains active as long as the fields on this form contain data.

Step 7. Enter the name of the process and ID of the WebAdvisor user you want to debug. As it runs, debug messages are written to the WWW.SCREEN.DEBUG files, which are keyed by SenderControlID*counter*SecurityToken*[processID].

Note: You can also remove a string that already exists in the Debug String field by entering that string in the Modify String field

290 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 291: Envision Runtime Administration

On-demand Diagnostics Using the UTDB Form

Refer to the WebAdvisor Debug Information (WADB) form to view a report of records in the WWW.SCREEN.DEBUG file that were written during WebAdvisor debugging.

Run the Debugged Form

When you enter a process’s debug name on the UTDB form, and then run the process needing debugging, the process runs in Envision debug mode. Envision debug mode displays the messages entered by the programmers to help you determine possible sources of problems with the software or data.

Runtime Administration, March 10, 2010 291© 2010 Datatel, Inc.

Page 292: Envision Runtime Administration

Troubleshooting: Envision Diagnostics

GRDS and UTDB: Do They Interact?The GRDS system was designed to be backward compatible with the UTDB form. Therefore it is possible to use GRDS to trigger both old-style (UTDB-style) diagnostics and diagnostics generated from the SHOWA and SHOWC commands. Both types of diagnostics will be collected in the same log.

It is not necessary to visit both the UTDB and GRS1 forms to do this. Everything can be done from within the GRS1 form (and its detail form GRSS).

Whenever you use the GRS1 form to request any of the numeric services for a process, the system automatically adds that process’ “ID” to the same system common variable that the UTDB form maintains.

In other words, the system behaves as if, in addition to entering the GRS1/GRSS forms, you had also gone to the UTDB form, entered the process ID into the “debug string” field, and saved out of the UTDB form.

Note: If a legacy process uses something other than its process ID for its debug string, you can still use the GRS1 form to trigger those old-style diagnostics. Just pretend that debug string actually was a process ID and request a numeric service for that "process". The GRSS form will warn you that it is not a valid process ID, but you can ignore the warning – it will still add the string to UTDB's system common variable.

292 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 293: Envision Runtime Administration

Runtime Administration

Appendices

Page 294: Envision Runtime Administration
Page 295: Envision Runtime Administration

Appendices

System Setup Worksheets

Worksheet for Device Definition (SDD)Device Name Display Table Keyboard

Runtime Administration, March 10, 2010 295© 2010 Datatel, Inc.

Page 296: Envision Runtime Administration

Appendices: System Setup Worksheets

Worksheet for System Operator Definition (SOD)

Application:

Login ID Initial Menu Security Class(es)Envision

Password

Password Expiration

Date

296 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 297: Envision Runtime Administration

Worksheet for Security Classes

Worksheet for Security ClassesClass Name:

Do Only These Never Do These Inquiry Only Privileged

Runtime Administration, March 10, 2010 297© 2010 Datatel, Inc.

Page 298: Envision Runtime Administration

Appendices: System Setup Worksheets

Worksheet for Function Keys (SKB1)Keyboard Name:

Envision Function Key AssignmentASCII Sequence for the Function

Key

Next Field

Previous Field

Jump to Field

Next Group

Previous Group

Jump to Group

Go to First Group

Go to Last Group

Scroll toward 1st

Scroll toward last

Scroll to Page #

Insert new Group

Next Element

Previous Element

Exit

Finish

Update

Cancel

Delete Record

Detail

Direct Access

Process Help

Field Help

Function Key Help

Refresh Screen

298 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 299: Envision Runtime Administration

Worksheet for Cursor Keys (SKB2)

Worksheet for Cursor Keys (SKB2)Keyboard Name

Envision Function Key AssignmentASCII Sequence for the

Cursor Key

Escape Start

Function Start

Attention Characters

Cursor HOME

Cursor UP

Cursor RIGHT

Cursor DOWN

Cursor LEFT

TAB Cursor

Backspace

Delete Character

Insert Character

Erase to Line’s End

Erase Whole Line

RETURN of ENTER

Delete Item/Line

In-line Edit Toggle

Runtime Administration, March 10, 2010 299© 2010 Datatel, Inc.

Page 300: Envision Runtime Administration

Appendices: System Setup Worksheets

Worksheet for Graphic CharactersDisplay Type Name

Graphic Abbreviation

Graphic Description

Character Set to Display Graphic

Decimal Equivalent of Graphic

Line Character Line Decimal

TT Top T 1 17

LLB Lower Left Brace 2 18

ULB Upper Left Brace 3 19

URB Upper Right Brace 4 20

LT Left T 5 21

LRB Lower Right Brace 6 22

VL Vertical Line 7 23

NB Normal Block 8 24

C Cross 9 25

RT Right T 10 26

HL Horizontal Line 11 27

LB Light Block 12 28

DHL Double Horizontal Line 13 29

BT Bottom T 14 30

DVL Double Vertical Line 15 31

DB Dark Block 16 32

300 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 301: Envision Runtime Administration

Worksheet For Special Purpose Characters

Worksheet For Special Purpose Characters

Display Type Name:

Character Abbreviation

Character DescriptionSpecial Purpose

Character DefinitionLine Character

ST Graphic Mode Start: the character sequence that will turn on the graphic display.

33

EN Graphic Mode End: the character sequence that will turn off the graphic display.

34

NORMAL Normal: the normal video intensity 35

REVERSE Reverse video 36

DIM Dim video: less intense than normal 37

UNDERSCORE Underscore Character 38

BLINK Blinking video display 39

DIM.REV Reverse video that is dim 40

Hidden Video attributes occupying a space

Enter a [[1]] for hidden video attributes. Enter a [[0]] if attributes occupy a space.

41

Type of fill characters Enter a [[1]] for character attributes. Enter a [[2]] for line attributes.

42

Upper case prompts Enter a [[1]] to convert all template and lookup prompts to uppercase. Enter a [[0]] for all lookup prompts to appear as upper and lower case.

43

Menu Display Enter a [[1]] to group menus in to the four quadrants. Enter a [[0]] to divide menus into one or two columns

44

Runtime Administration, March 10, 2010 301© 2010 Datatel, Inc.

Page 302: Envision Runtime Administration

Appendices: System Setup Worksheets

302 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 303: Envision Runtime Administration

Appendices

Form Reference

This appendix provides a reference for all of the forms in Envision Runtime. The forms are presented in alphabetical order by mnemonic. For each form, the following is provided:

A process overview, which describes the general purpose of the form

A sample form

For data entry and inquiry forms, a query language table that lists the file and data element names you use to create your own query reports. The table provides information about the field and file names to use when you create queries to retrieve data shown or entered on a form.

Runtime Administration, March 10, 2010 303© 2010 Datatel, Inc.

Page 304: Envision Runtime Administration

Appendices: Form Reference

Action Checked Out Studio Object (ACSO)

Use the Action Checked Out Studio Obj (ACSO) form to shelve or cancel the checkout of a resource that is currently checked out in Colleague Studio.

The ACSO form should be highly secured. Normally, a Colleague Studio user would shelve or cancel the checkout of their own checked out resources from within Colleague Studio. However, the ACSO form allows an authorized user to perform those actions from Envision when the Colleague Studio user who checked out the resource is not available.

Figure 46: Action Checked Out Studio Obj (ACSO) Form

304 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 305: Envision Runtime Administration

Refresh RFSPECS (BTRR)

Refresh RFSPECS (BTRR)Use the Refresh RFSPECS (BTRR) form to rebuild RFSPECS information from the current appl.FILE.SPECS. RFSPECS (runtime file specs) contains information on various functions that need to be performed on a file when writes occur. This information includes such things as date/operator stamping, indexing, and history logging (among others). This information in the file is generated from the appl.FILE.SPECS file and from UFSPECS. This process allows batch rebuilds of the former. You can specify one of three ways to define which files to process:

1. A saved list name that contains the file names.

2. A manual list of files to process.

3. All files in the current application (leave both fields blank).

Figure 47: Refresh RFSPECS (BTRR) Form

Runtime Administration, March 10, 2010 305© 2010 Datatel, Inc.

Page 306: Envision Runtime Administration

Appendices: Form Reference

Computed Column Library Dply (CCLD) Use the Computed Column Library Dply (CCLD) form to deploy the computed column library of functions to Oracle or SQL Server (depending on your database) to support computed column usage in Colleague.

Figure 48: Computed Column Library Dply (CCLD) Form

306 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 307: Envision Runtime Administration

Computed Columns Not Deployed (CCND)

Computed Columns Not Deployed (CCND)

Use the Computed Columns Not Deployed (CCND) form to view all computed column components that are not currently deployed to the database. This inquiry-only form displays information about computed columns in their environment: the name of the computed column item, the type (Computed Column, IS-type subroutine, or Multi-part Key), and the application where the item is defined.

The CCND form allows you to determine whether a particular computed column should be available for database query. If a computed column is displayed that you want to make available on the database, ensure that the Skip database generation checkbox is not checked in Colleague Studio, and then attempt to generate it.

Figure 49: Computed Columns Not Deployed (CCND) Form

Runtime Administration, March 10, 2010 307© 2010 Datatel, Inc.

Page 308: Envision Runtime Administration

Appendices: Form Reference

CC Reset for SQL Server (CCRS)

For a SQL Server environment only, use the CC Reset for SQL Server (CCRS) form to recreate all computed column functions.

To run this process, verify the path to the C# compiler on the application server. This field will display the path information specified on the Computed Column Parameters form in SA Valet. Next, enter Y in the Remove and Re-deploy Computed Column Objects field to:

Remove all C# computed column support objects from the SQL Server database.

Start a re-deploy of the Datatelx and Colleague assemblies.

Recreate all computed column functions in the SQL Server database.

When you save from this form, you see a warning message that reminds you that all users should be logged out of the environment and that a backup of the environment should be made. Click OK to continue and recreate all computed column functions, or click Cancel. You can review the CCRS report at the end of this process for any errors or warnings that were generated.

ALERT! Datatel suggests that you make a backup of your environment before running this process. Also, all users must be logged out of this environment.

308 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 309: Envision Runtime Administration

CC Reset for SQL Server (CCRS)

Figure 50: CC Reset for SQL Server (CCRS) Form

Runtime Administration, March 10, 2010 309© 2010 Datatel, Inc.

Page 310: Envision Runtime Administration

Appendices: Form Reference

Custom Scanner Report (CCSR) Use the Custom Scanner Report (CCSR) process to produce a report with the results of the Custom Code Scanner (CUSC) process.

The CCSR process will populate the SCAN.CODE.RESULTS file. This file contains the problems found during the CUSC process on all custom processes scanned. Each record in the SCAN.CODE.RESULTS file corresponds to a process that was scanned. Whereas the CUSC process scans selected or specific processes from within the application, the CCSR process reports on only those particular scanned processes (and not all processes from within the application). For example, if the CUSC process scanned only twenty processes from within an application, then the CCSR process will report only on those twenty processes, or a subset of those twenty, depending on the selection criteria.

The CCSR report provides the following categories of information:

Processes that are compatible for columnar I/O.

R-dots and their location in the code.

Direct calls to @MIO.READ and @MIO.WRITE and their location.

UniData I/O in the code (flat reads and writes).

Number of processes that call each specific process being scanned.

Whether processes are classified as Pre-Process Code or Pre-Process Subroutine.

For information about the Custom Code Scanner (CUSC) process, see its process help.

Note: Before you run the CCSR process, you must first run the CUSC process.

310 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 311: Envision Runtime Administration

Custom Scanner Report (CCSR)

Figure 51: Custom Scanner Report (CCSR) Form

Runtime Administration, March 10, 2010 311© 2010 Datatel, Inc.

Page 312: Envision Runtime Administration

Appendices: Form Reference

Custom Declaration (CDEC)Use the Custom Declaration (CDEC) form to define items in the current application that you want to declare as customized. Items include Envision processes, files, and menus, as well as individual items that can be derived from these. You can specify any combination of item types. For example, you can specify only one process or file, or you can specify an entire list of processes, files, and menus.

As you specify the items you want to declare, a list of all derived items is built in the File/Record window, available when you detail to the Custom Packaging Detail (CDED) form. This list is built by scanning the pieces you specified and identifying all associated items. This list contains the computed columns, records in any files that you specify in the Records From File group, the File Specifications group, and all processes, files, and menus that you specify.

The information you enter using this process is stored in a record in the MOVEINFO file. If the Action field is set to CO (Save Custom Declaration and Check Out Items), each item is marked for custom development in the product repository. After you declare and check out custom items, you can use the Custom Release Package Build (CPKG) form to create custom release packages. You must check out a custom declaration before using it on the CPKG form. The CPKG process builds the custom release package while also checking in the custom declaration.

Before checking items out, the CDEC process verifies that an item is not already checked out on another custom declaration in this or a sister environment (other application environments connected to the same local product repository as this application environment).

If items on your custom declaration are already checked out on another custom declaration in this environment, an error is displayed. The error prevents you from proceeding until you take one of the following steps:

Drop the conflicting items off of this custom declaration.

Remove the conflicting items from the other custom declaration.

Cancel the check out of the other custom declaration.

Run the CPKG process to deliver the other custom declaration.

If items on your custom declaration are already checked out on another custom declaration in a sister environment, a warning is displayed. Datatel recommends that you take one of the preceding steps. However, you may choose to continue with parallel development.

312 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 313: Envision Runtime Administration

Custom Declaration (CDEC)

Figure 52: Custom Declaration (CDEC) Form

Runtime Administration, March 10, 2010 313© 2010 Datatel, Inc.

Page 314: Envision Runtime Administration

Appendices: Form Reference

Custom Packaging Detail (CDED)Use the Custom Packaging Detail (CDED) form to view or modify an expanded list of items declared as custom.

When populated from Colleague Studio custom code management, this form is inquiry only.

When populated from the Custom Declaration (CDEC) form, entries are automatically added to this list for each piece specified in the Computed Columns, Records From File, File Specifications, Processes, and Menus windows.

When populated from the Custom Declaration Objects (CDOB) form, entries are automatically added to this list for each piece specified in the Entities and ELF Spec Processes window.

A link is maintained automatically between each piece and the items derived from it. However, you can choose whether to maintain this link by using the Auto field. The codes in the Auto field also specify how items will be handled on a rescan. In addition, you can use the Include field to choose whether to prevent an item from being released. For further details, see field help.

314 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 315: Envision Runtime Administration

Custom Packaging Detail (CDED)

Figure 53: Custom Packaging Detail (CDED) Form

Runtime Administration, March 10, 2010 315© 2010 Datatel, Inc.

Page 316: Envision Runtime Administration

Appendices: Form Reference

Custom Declaration Objects (CDOB)Use the Custom Declaration Objects (CDOB) form to define objects in the current application that you want to declare as customized.

Only objects that cannot be maintained in Colleague Studio can be specified on this form. See the online help for the Entity field for details.

The information you enter using this process is stored in a record in the MOVEINFO file. Note that this record can only hold items from the application currently being worked on. To make changes to an existing MOVEINFO record, you must access the CDOB form from the application where the MOVEINFO record was created. Rules and ELF processes are always created in the CORE application.

If you set the Action field to CO (Save Custom Declaration and Check Out Items), each item is marked for custom development in the product repository. After you declare and check out custom items, you can use the Custom Release Package Build (CPKG) form to create custom release packages. You must check out a custom declaration from the CDOB form before using it on the CPKG form. The CPKG process builds the custom release package while also checking in the custom declaration.

Before checking items out, the CDOB process verifies that an item is not already checked out on another custom declaration in this or a sister environment (another environment associated with the same local product repository).

If items on your custom declaration are already checked out on another custom declaration in this environment, an error is displayed. The error prevents you from proceeding until you take one of the following steps:

Drop the conflicting items off of this custom declaration.

Remove the conflicting items from the other custom declaration.

Cancel the check out of the other custom declaration.

Run the CPKG process to deliver the other custom declaration.

If items on your custom declaration are already checked out on another custom declaration in a sister environment, a warning is displayed. Datatel recommends that you take one of the preceding steps. However, you may choose to continue with parallel development.

316 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 317: Envision Runtime Administration

Custom Declaration Objects (CDOB)

Figure 54: Custom Declaration Objects (CDOB) Form

Runtime Administration, March 10, 2010 317© 2010 Datatel, Inc.

Page 318: Envision Runtime Administration

Appendices: Form Reference

Custom Development in Progress (CDPI)

Use the Custom Development in Progress (CDPI) form to display all active custom declarations from the current application environment, as well as any sister environments (other application environments connected to the same local product repository as this application environment). The CDPI form identifies all custom declarations that are checked out for development from the local product repository. Active custom declarations from the current application environment are displayed in the top window.

You can detail to the Custom Declaration (CDEC) form (and then to the Custom Packaging Detail [CDED] form) to view all items on the custom declaration and their details. The bottom window on the CDPI form displays any active custom declarations from sister environments. The CDPI form displays all Colleague Studio objects that are currently Checked out, Shelved, or Ready for build.

Figure 55: Custom Development in Progress (CDPI)

318 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 319: Envision Runtime Administration

Chain Usage Report (CHUS)

Chain Usage Report (CHUS)Use the Chain Usage Report (CHUS) form to obtain reports on screen chains and the screens they contain. Screen chains are defined on the Screen Chaining Specification (SCSP) form.

The following are the chain usage reports:

Screen Usage by Chain. This report lists each chain defined in the application in which you are working and shows which screens are included in each.

Chain Usage by Screen. This report lists each screen found in any chain that is defined in the application in which you are working and shows the chains in which each is included.

These reports can help you administer security for screen chains.

Figure 56: Sample Chain Usage Report (CHUS) Form

Runtime Administration, March 10, 2010 319© 2010 Datatel, Inc.

Page 320: Envision Runtime Administration

Appendices: Form Reference

Change Peripheral Defaults (CPDE)The Change Peripheral Defaults (CPDE) form allows you to modify the peripheral settings specified by the Analyst for this execution of the procedure. By answering “Yes” to the peripheral modify specification, the Analyst designing this procedure has given you the option to modify the default settings of the peripheral device needed for a procedure step during each generation of this procedure. You may change the peripheral device to be used (from a printer to the HOLD file for example), change the number of copies produced, or even the width of the form. This last option is not useful, unless the procedure step uses a Query Language that checks these parameters before execution or the program checks and reacts to this change.

For output to the HOLD file, besides the name of the record specified via the banner option, you are able to specify the output security of the created record:

PB Public, in the HOLD file itself, with wide open security.

PR Private, in a subdirectory of the HOLD file keyed by the user name, secured so only the file creator can see it.

SH Shared, assigned to a group that one or more people are put into. Only members of the group can see the output. Groups have to be predefined on the OSGD form, and then the group can be entered on this form. The record will be put into a subdirectory by the name of the group.

320 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 321: Envision Runtime Administration

Change Peripheral Defaults (CPDE)

Figure 57: Sample Change Peripheral Defaults (CPDE) Form

Runtime Administration, March 10, 2010 321© 2010 Datatel, Inc.

Page 322: Envision Runtime Administration

Appendices: Form Reference

Custom Package Import/Export (CPIE)The Custom Package Import/Export (CPIE) form allows you to either import custom release packages into your Local Product Repository from an outside source or export custom release packages from your Local Product Repository for the purpose of sharing them with other institutions. If your institution uses Oracle or SQL Server, you must have administrative privileges in the LPR database to import a custom release package. If your institution uses UniData, you must have full access to all directories in the LPR UniData environment.

Package import and export is valid across environments on different databases, and also across platforms.

For a custom release package containing computed columns, the computed columns will deploy automatically to the target database if you are using:

The same type of database as the source.

A different type of database from the source, and you successfully generated the source computed columns for alternate databases using the Batch Generation (BNGN) form.

If you are using another type of database from the source, you may need to generate the computed columns manually after importing and installing custom release packages.

322 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 323: Envision Runtime Administration

Custom Package Import/Export (CPIE)

Figure 58: Custom Package Import/Export (CPIE) Form

Runtime Administration, March 10, 2010 323© 2010 Datatel, Inc.

Page 324: Envision Runtime Administration

Appendices: Form Reference

Custom Release Package Build (CPKG)Use the Custom Release Package Build (CPKG) process to create a custom release package. You can use this process to maintain the contents and attributes of a release package. Enter "Yes" in the Execute Build field to build the release package and to publish to your local product repository. After the build is in the product repository, you can install to other application environments.

When you save the CPKG form with the Execute Build field set to “Yes” and the WorkGroups window populated, you can view:

Built Objects That May be Added. A list of Colleague Studio objects that were previously Built in one of the WorkGroups.

Objects Excluded Due to Status. A list of Colleague Studio objects that are Checked Out or Shelved in one of the WorkGroups.

New Objects on this Build. A list of Colleague Studio objects that are Ready for Build in one of the WorkGroups that were not on a previous build of this same custom release package.

If any of these lists contain Colleague Studio objects, the Custom Package Rebuild Detail (CPKR) form appears where you can:

Specify whether or not to include previously Built Colleague Studio objects in the rebuild.

View Colleague Studio objects that will be excluded from the rebuild.

View newly added Colleague Studio objects that will be included in the rebuild.

Note: You can run the CPKG process for any Colleague application, regardless of the application that is currently opened.

324 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 325: Envision Runtime Administration

Custom Release Package Build (CPKG)

Figure 59: Custom Release Package Build (CPKG) Form

Runtime Administration, March 10, 2010 325© 2010 Datatel, Inc.

Page 326: Envision Runtime Administration

Appendices: Form Reference

Custom Release Package Build (CPKP)Use the Custom Release Package Build (CPKP) form to prepare a custom release package for rebuild in this environment. This process is necessary when:

A custom release package includes objects that were maintained through Colleague Studio and it was built in a different environment originally.

An object on the custom release package has never been modified through Colleague Studio in this environment.

If you attempt to rebuild using the Custom Release Package Build (CPKG) form while in this state, a message will direct you to run the custom release package through the CPKP process first.

This process creates missing MOVEINFO records for objects in a release package where MOVEINFO records are missing because original development or a build was performed elsewhere. This process also updates MOVEINFO records for objects that have undergone parallel or subsequent development in this environment.

The CPKP process also produces a report of the MOVEINFO records created, updated, or left unchanged.Newly created or updated MOVEINFO records are saved only if you enter “Yes” in the Update Mode field.

326 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 327: Envision Runtime Administration

Custom Release Package Build (CPKP)

Figure 60: Custom Release Package Build (CPKP) Form

Runtime Administration, March 10, 2010 327© 2010 Datatel, Inc.

Page 328: Envision Runtime Administration

Appendices: Form Reference

Custom Package Rebuild Detail (CPKR) Use the Custom Package Rebuild Detail (CPKR) form to specify which previously Built Colleague Studio objects to include on a custom release package rebuild.

When saving from the Custom Release Package Build (CPKG) form, the CPKR form appears if there is any data to display on the form. This information includes the following:

Built Objects That May be Added. A list of Colleague Studio objects that were previously Built in one of the WorkGroups.

Objects Excluded Due to Status. A list of Colleague Studio objects that are Checked Out or Shelved in one of the WorkGroups.

New Objects on this Build. A list of Colleague Studio objects that are Ready for Build in one of the WorkGroups that were not on a previous build of this same custom release package.

If a Colleague Studio object was included on a previous build of this custom release package, but was not newly changed after the build, then it is still in a Built state. You can use this form to automatically include these objects on a rebuild. You can also use this form to view Colleague Studio objects that will be:

Excluded on the rebuild due to their status (either Checked out or Shelved).

Included on the rebuild because they were newly added to the custom release package.

328 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 329: Envision Runtime Administration

Custom Package Rebuild Detail (CPKR)

Figure 61: Custom Package Rebuild Detail (CPKR) Form

Runtime Administration, March 10, 2010 329© 2010 Datatel, Inc.

Page 330: Envision Runtime Administration

Appendices: Form Reference

Create Printer Control Record (CPRC)Use the Create Printer Control Record (CPRP) form to create printer control records in the SYSDEFS file to enable printing Colleague Envision reports. The printer control record is configured based on the machine on which you installed Colleague and whether your print server is local or networked.

You can find detailed steps to set up the VALID.PRINTERS valcode in Answernet document 196.848.

Figure 62: Sample Create Printer Control Record (CPRC) Form

Note: If you run on a networked print server, you need to create a UT valcode called VALID.PRINTERS after running this process. This valcode contains the printer names that your institution uses.

330 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 331: Envision Runtime Administration

Custom Code Scanner (CUSC)

Custom Code Scanner (CUSC)Use the Custom Code Scanner (CUSC) process to scan your custom code before migrating from R17 to R18. Scanning your custom code before you actually migrate to R18 lets you plan the time and resources necessary to modify your code.

Primarily, the CUSC process identifies custom code that has non-columnar I/O issues. However, code with such issues will still function in any database in Release 18 and higher, with a few exceptions as noted below. You will increase performance of your code by modifying it to comply with columnar I/O. However, you must decide if the performance benefits are greater than the cost of changing some of the code.

You can also choose to scan non-Envision processes by specifying a directory name that contains non-Envision code in the Directory for Non-Envision Code field.

The CUSC process looks for the following items in your custom code's specifications (appl.PRCS.DEF, .INSERTS, and so on):

The use of R-dots. These are variables such as R.VOUCHERS or R.PERSON that contain the entire record for which they are named. For instance, R.PERSON will have a person’s first name, last name, birth date, and all other fields from the PERSON file. It is easy to understand why this is not a best practice: multiple tables need to be opened in order to get all the information, and it is possible and likely that only a few elements are really needed. You should change these R-dots to use standard Envision V-dots. R18 will still work with R-dots, but these processes cannot be flagged to use columnar I/O.

Direct calls to @MIO, more specifically, calls to @MIO.READ.RECORD and @MIO.WRITE.RECORD. Whenever one of these two calls is used, the entire record is read. You should to change them to use Envision as noted for R-dots above.

UDT IO - "Flat" reads and writes. Custom code that uses flat reads and writes will not work in SQL Server or Oracle databases in R18. They will also not work in R18 in a UniData database with distributed deployment. These include calls to READ, WRITE, READV, WRITEV, OPEN, and a few others. You should replace them with EBSL or, if not possible, @MIO.READ.RECORD and @MIO.WRITE.RECORD.

Pre-Process Code and Subroutines. Routines that are specified as Pre-Process Code or Pre-Process Subroutines (on the Batch Global Parameters [BGP] form) cannot use Columnar I/O. You should change them to Main and Subroutine types, respectively.

Runtime Administration, March 10, 2010 331© 2010 Datatel, Inc.

Page 332: Envision Runtime Administration

Appendices: Form Reference

When the CUSC process has completed its scan, it will populate the SCAN.CODE.RESULTS file. This file will contain all the problems for the processes being scanned, one record per process. To produce a report for the problems found, use the Custom Code Scanner Report (CCSR) process.

Figure 63: Custom Code Scanner (CUSC) Form

332 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 333: Envision Runtime Administration

Dictionary Date Convert (DDCV)

Dictionary Date Convert (DDCV)Use the Dictionary Date Convert (DDCV) form to change the data dictionary formats for date fields so that they are consistent with the date formats specified on the International Parameters (INTL) form. You should complete the International Parameters form before you use this form.

Dictionaries are updated on an application-by-application basis. Once you specify the application, all of the files listed in the application’s VOC file (appl.VOC) are examined. Any dictionary items for any of those files that contain ICONV (Input Conversion) or OCONV (Output Conversion) statements in the LOC (Location or Formula) field or that have a date conversion in the CONV (Conversion) field are examined and updated as appropriate.

For example, if you specify the Core System (CORE) as the application you wish to update, then all of the records in the CORE.VOC file with a type of “F” (for File) are examined, and any dictionary items in any of those files that have an ICONV or OCONV in the LOC field or a date format in the CONV field are updated.

Running the Process in Background Mode

After you complete the Dictionary Date Convert form, the Process Submission form is displayed. If you choose to run this process in the foreground (that is, you enter “No” in the Execute in Background Mode field), you will see the list of files that are examined along with the dictionary items that are updated for each file as processing occurs.

Since processing can occur fairly quickly, however, you may wish to obtain a printout of this information. To obtain such a printout, enter C in the Execute in Background Mode field to capture a record of the processing in a COMO (command output) file. The output is captured in a record in the PH file under the job statistics ID that is displayed on the Process Submission form, prefaced by “O_”; for example, O_DDCV_EJR_40741_9733. After processing is complete, exit and spool the COMO file to the printer.

Runtime Administration, March 10, 2010 333© 2010 Datatel, Inc.

Page 334: Envision Runtime Administration

Appendices: Form Reference

Figure 64: Sample Dictionary Date Convert (DDCV) Form

334 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 335: Envision Runtime Administration

Define Field History (DHST)

Define Field History (DHST)Use the Define Field History (DHST) form when you want to track changes that users make to the values in specific fields in a file. Changes are logged at runtime and are stored in the file.HIST.LOG file and the file.HIST files.

Using the Envision Tool Kit, programmers can also specify fields to be tracked using the Field History (FLDH) form. Using the DHST form, you may be able to delete fields that a progammer has added to the list on the FLDH form, depending on whether the programmer allowed deletions.

Figure 65: Sample Define Field History (DHST) Form

Note: The FLDH form is available only through the Envision Tool Kit.

Runtime Administration, March 10, 2010 335© 2010 Datatel, Inc.

Page 336: Envision Runtime Administration

Appendices: Form Reference

Difference Engine (DIFF)

Figure 66: Sample Difference Engine (DIFF) Form

336 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 337: Envision Runtime Administration

Edit Record (EDRC)

Edit Record (EDRC)

Use the Edit Record (EDRC) form to enter an existing file name from which you can then choose a record you want to edit. If you detail on the record, you can use a text editor window to make your changes. You can also delete a record.

Figure 67: Edit Record (EDRC) Form

ALERT! Datatel strongly recommends that you secure this form using the subroutine shown below. The EDRC form allows a user to edit and delete any record in a file.

Runtime Administration, March 10, 2010 337© 2010 Datatel, Inc.

Page 338: Envision Runtime Administration

Appendices: Form Reference

Overview of Security for the EDRC Form

Access to the EDRC form can be controlled using the standard Envision Security class setup to determine whether or not the user has access rights to the EDRC form. A user can be granted either full access, inquiry only, or no access. If the user has either full or inquiry-only access rights, the user is prompted for the file name and ID of the record to be edited. If a user is given full access to the form, the user has the right to create, modify, or delete any record.

However, you can create a subroutine named XS.GET.RECORD.ACCESS.RIGHTS in an environment, which can be used to define precise security controls over the EDRC form. If you create this subroutine, then when a user specifies a file name and a record ID, the system will call the XS.GET.RECORD.ACCESS.RIGHTS subroutine.

Based on the information passed into the subroutine (see Table 18), the subroutine must determine the current user’s access rights to the requested record:

Full access

Modify-only access

Inquiry-only access

No access

Table 18: Information Passed into the Subroutine

Current record information: Current user information:

• The name of the file

• The ID of the record

• Login ID

• PERSON ID

• List of ORG.ROLEs associated with the user

• List of security classes associated with the user

Note: The XS.GET.RECORD.ACCESS.RIGHTS subroutine will not grant the user greater access rights than given to the user by security on the EDRC form itself. For example, suppose the user's security class setup grants the user inquiry-only access to the EDRC form. However, for a particular record the XS.GET.RECORD.ACCESS.RIGHTS subroutine grants the user full access. The user will still have just inquiry-only access to the record.

338 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 339: Envision Runtime Administration

Edit Record (EDRC)

Technical Details about the XS.GET.RECORD.ACCESS.RIGHTS Subroutine

If you create the XS.GET.RECORD.ACCESS.RIGHTS subroutine in an environment, you must create it as follows. The subroutine must:

Be a regular SUBROUTINE-type process.

Define exactly 6 arguments, which you must use as follows:

1. Argument 1: Input only. Passes in the file name specified at the EDRC file name LookUp.

2. Argument 2: Input only. Passes in the record ID specified at the EDRC record ID LookUp.

3. Argument 3: Input only. Passes in a Boolean flag that indicates whether the record already exists.

• A true value means that it already exists. • A false value means it will be created (if this subroutine grants the user the

right to do so – see Argument 6).

4. Argument 4: Input only. Passes in two strings that identify the current user. The two strings are separated (delimited) by a field mark (@FM).

• Field 1: The current user’s PERSON ID.• Field 2: The current user’s login ID.

5. Argument 5: Input only. Passes in other lists of information about the user to determine the rights the user should be given. Two lists are passed in. The first list is separated from the second by a field mark (@FM).

• Field 1: An @VM-delimited list of the user’s ORG.ROLEs.• Field 2: An @VM-delimited list of the user’s SECLASSes.

6. Argument 6: Output only. Must pass back information that defines this user’s access rights.

If this is a new record (see Argument 3), then argument 6 must return a boolean flag:• A true value (1) means the user is allowed to create it.• A false value (0) means the user is not allowed to create it.

If the record already exists, argument 6 must return one of the following to specify this user’s access rights to the record.• Null. No access rights (that is, cannot look at the data).• Code “V” (View-only). Can view the data (but not modify or delete).• Code “M” (Modify). Can view and modify the data, but cannot delete the

record.• Code “A” (All). Can view, modify, and delete the data (full access).

Runtime Administration, March 10, 2010 339© 2010 Datatel, Inc.

Page 340: Envision Runtime Administration

Appendices: Form Reference

Field History Detail (FHDT)Detail to the Field History Detail (FHDT) form from the Rebuild File History (RBFD) form when you want to use field history to view a record as it existed at an earlier time. You can detail down to the field history level in order to view the value that a particular field had on a specific date and the value that it was changed to on that date.

Figure 68: Sample Field History Detail (FHDT) Form

The FHDT form is inquiry-only. You cannot use it to change a record or revert it to an earlier state.

340 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 341: Envision Runtime Administration

Field History Detail (FHDT)

Table 19: Query Lang Retrieval Help for Field History Detail (FHDT) Form

Where Field History Detail (FHDT) Data Is StoredTo retrieve data from use this file and this field

Field HIST HIST.FIELD.NAME

Date HIST.LOG HL.DATE

Time HIST.LOG HL.TIME

Operator HIST.LOG HL.CHGOPR

Reason HIST.LOG HL.CHG.REASON

Old Values HIST HIST.OLD.VALUES

New Values HIST HIST.NEW.VALUES

Runtime Administration, March 10, 2010 341© 2010 Datatel, Inc.

Page 342: Envision Runtime Administration

Appendices: Form Reference

GUI Function Button (GUIF)

Figure 69: Sample GUI Function Button (GUIF) Form

Table 20: Query Lang Retrieval Help for GUI Function Button (GUIF) Form

Where GUI Function Button (GUIF) Data Is StoredTo retrieve data from use this file and this field

GUI Function Button Template GUI.FUNCTION GUIF.ID

GUI Function Button Rows GUI.FUNCTION GUIF.ROWS

GUI Function Button columns GUI.FUNCTION GUIF.COLS

GUI Function Button Mode GUI.FUNCTION GUIF.MODE

GUI Function Button Command GUI.FUNCTION GUIF.COMMAND

GUI Function Button Text GUI.FUNCTION GUIF.BUTTON

342 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 343: Envision Runtime Administration

International Parameters (INTL)

International Parameters (INTL)Use the International Parameters (INTL) form to specify the country whose spelling and wording alternatives you wish to use and to modify the date format that is used on Envision-based and Classic Colleague forms and reports.

After you complete the International Parameters form, use the Dictionary Date Convert (DDCV) form to change your data dictionary formats for date fields to reflect the date formats you indicate on this form. This will ensure that query reports also display dates in the chosen format.

Figure 70: Sample International Parameters (INTL) Form

Note: The format for dates used in query report headings (the “D” option) is independently controlled by the database management system’s DATE.FORMAT command.

Runtime Administration, March 10, 2010 343© 2010 Datatel, Inc.

Page 344: Envision Runtime Administration

Appendices: Form Reference

Table 21: Query Lang Retrieval Help for International Parameters (INTL) Form

Where International Parameters (INTL) Data Is StoredTo retrieve data from use this file and this field

Country Code INTL.PARMS HOST.COUNTRY

Short Date Format INTL.PARMS HOST.SHORT.DATE.FORMAT

Short Date Pad INTL.PARMS HOST.SHORT.DATE.PAD

Date Delimiter INTL.PARMS HOST.DATE.DELIMITER

Long Date Format INTL.PARMS HOST.LONG.DATE.FORMAT

Long Date Pad INTL.PARMS HOST.LONG.DATE.PAD

Long Month INTL.PARMS HOST.LONG.MONTH

Long Year INTL.PARMS HOST.LONG.YEAR

344 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 345: Envision Runtime Administration

Procedure Specification (JDEF)

Procedure Specification (JDEF)Use the Procedure Specifications (JDEF) form to modify an existing procedure or to create a new one.

When an end user runs a procedure, Envision creates and runs commands stored as a paragraph in the command language of your host computer. Most of the parameters that govern a procedure are defined using other Envision forms, but a procedure can accept arguments and prompt for input from an end user. Based on this input, Envision can build the procedure differently each time end users run it. Envision uses branching logic, which determines the next step of the procedure from the results of previous steps.

End users may direct output data to a printer or other peripheral device. They may also transfer data to a form process or batch program. Envision checks each end user’s right to access data at the menu level, record level, and field level. Envision only produces output for end users that are within their security rights.

Envision checks each step to make sure it is a valid process or form before it can be used within the procedure. User forms and batch processes must be generated by the Process Generator (GEN) in the Envision Tool Kit before Envision can use them at runtime.

User form step types are assigned to form processes that ask end users how to run the procedure. These forms are used to specify options and to collect data and selection criteria from an end user. End users indicate which steps of the procedure to run and which data to select for processing.

Job step types are assigned to Batch, IF, STMT, and all other processes. Envision uses batch processes to create reports and to provide special processing needs. The procedure runs these processes if they are part of the execution path. IF processes provide conditional statements to direct the execution path. STMT processes provide a way to insert a database command into the procedure.

Note: A procedure is made up of steps listed in sequential order. The steps consist of processes, commands, list specifications, and conditional branching. A procedure definition includes the procedure name, class, purpose, status, and modules for inclusion.

Note: A procedure consists of three types of steps: user forms, jobs, and list specifications. Each step of a procedure must already exist before it can be used within a procedure.

Runtime Administration, March 10, 2010 345© 2010 Datatel, Inc.

Page 346: Envision Runtime Administration

Appendices: Form Reference

List specification step types are either included within the application or are created using the Procedure List Specification (JSEL) form. A list specification creates a SSELECT command within a procedure to produce a list of records based on the end user’s input entered from a user form.

Envision runs the steps of the procedure in sequential order. When a procedure runs a form process that asks for end user input, this input directs the procedure to the next appropriate step to run. Labels can also affect the direction of the procedure. GOTO statements within a step can direct the procedure to a process that contains the specified label.

Each time an end user runs a procedure, Envision creates a new paragraph to run for that procedure. Envision includes in the paragraph only those steps that are within the execution path.

Procedures created from within an application generate two records, a PRCS.GEN record and a PRCS.CTL record. If you create a procedure from the Envision Tool Kit for an application, Envision generates a third record in the PRCS.DEF file that adds an additional level of security to the procedure. This third record is the only difference between the two ways that Envision generates procedures.

All functions and features operate identically, and there are no limitations to the types of procedures that Envision can generate. If a procedure is created through the Envision Tool Kit, you or your end users usually can not modify it from the Envision Runtime application. However, you can modify some procedures when you need additional functionality for a particular application. When a procedure is created in the Envision Tool Kit, analysts set the option of whether to allow modifications to the procedure during runtime.

346 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 347: Envision Runtime Administration

Procedure Specification (JDEF)

Figure 71: Sample Procedure Specification (JDEF) Form

Table 22: Query Lang Retrieval Help for Procedure Specification (JDEF) Form

Where Procedure Specification (JDEF) Data Is StoredTo retrieve data from use this file and this field

Procedure ID LookUp PRCS.CTL PROCESS.MNEMONIC

Description PRCS.CTL PROCESS.DESCRIPTION

Menu Class PRCS.CTL PROCESS.CLASS

Remember Responses? PRCS.GEN JS.IGNORE.USPARAMS

Procedure Securable? PRCS.GEN PGEN.SECURE.FLAG

Executable as a Phantom? PRCS.GEN JS.PHANTOM.ALLOWED

Prcs Name PRCS.GEN JS.MNEMONIC

Label PRCS.GEN JS.LABEL

Device PRCS.GEN JS.OUTPUT.DEVICE

Default PRCS.GEN JS.OUTPUT.DEFAULT

Modify PRCS.GEN JS.OUTPUT.MODIFY

Runtime Administration, March 10, 2010 347© 2010 Datatel, Inc.

Page 348: Envision Runtime Administration

Appendices: Form Reference

Procedure Step Detail (JDET)Use the Procedure Step Detail (JDET) form to enter operating specifications for each procedure step. The step type that you assign on this form indicates whether the step is a user form, a list, or a job. The step type determines how Envision runs the procedure at runtime. This form automatically appears when you enter a procedure step ID in field 6 of the Procedure Specification (JDEF) form.

The types of specifications and commands include the following:

Step labels. Used for conditional branching within the procedure. Envision uses a label associated with a particular step as the target for a branching operation by another step. There is one special label generated automatically for all procedures: the END.PROCESS label. This label runs a step that resets the workstation and printers to the settings that existed before you ran the procedure.

Arguments. Used to pass variable or constant arguments from one procedure step to another. Use procedure arguments just as you would use batch or form process arguments.

IF commands. Used to direct processing to run another step after the current one, based on a conditional value. Enter the pieces of the statement into separate fields; Envision evaluates them as an expression at runtime. If the condition is true, Envision directs the procedure to the step associated with the label specified. If the condition is false, the procedure continues with the next sequential step.

Peripheral device. Used to specify a device for accepting and displaying any output that this step may produce. Enter a default device; depending on the requirements of the procedure, end users may be able to change this default.

Lists. Used to call an existing list into use or to save a list to disk. The specifications require that you enter a valid list name. The procedure can issue GETLIST and SAVEDLIST commands using the list name(s) provided.

348 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 349: Envision Runtime Administration

Procedure Step Detail (JDET)

Figure 72: Sample Procedure Step Detail (JDET) Form

Table 23: Query Lang Retrieval Help for Procedure Step Detail (JDET) Form

Where Procedure Step Detail (JDET) Data Is StoredTo retrieve data from use this file and this field

Procedure Description PRCS.CTL PROCESS.DESCRIPTION

Runtime Administration, March 10, 2010 349© 2010 Datatel, Inc.

Page 350: Envision Runtime Administration

Appendices: Form Reference

Procedure Rules Documentation (JPRT)

The Procedure Rules Documentation (PGDP) procedure provides you with current documentation for any or all procedures defined for this application. Use this form to identify the names of procedures for which you want documentation printed. If you want to access documentation for all procedures for the application, enter A at the first selection prompt. To print documentation for a selected subset of procedures, enter a list of procedure names.

The resulting documentation provides procedure definition information and procedure generation information. The procedure definition information includes items such as the mnemonic, process status, modules, process class, and execution type. The procedure generation information includes items such as the procedure class, all of the procedure steps, whether the procedure can be secured, whether it can be modified in the field, and whether a background process is allowed.

Specifying Output Options

When you complete the entries on the first form, the Change Peripheral Defaults form appears. Use that form to select a destination for the output. You can direct output to any of the following:

Printer

Hold file for browsing at a terminal

Tape (not available on all platforms)

Serial line or MPC printer (not available on all platforms)

Running the Process in Background Mode

The last form displayed when you run this process is the Process Submission form. Use the Process Submission form to specify whether you want to run the process in background mode.

350 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 351: Envision Runtime Administration

Procedure Rules Documentation (JPRT)

Figure 73: Sample Procedure Rules Documentation (JPRT) Form

Runtime Administration, March 10, 2010 351© 2010 Datatel, Inc.

Page 352: Envision Runtime Administration

Appendices: Form Reference

Procedure List Specification (JSEL)Use the Procedure List Specification (JSEL) form to define the fundamental parameters for a new list process. This form is the only Envision Runtime process needed to define a list used within a procedure. You can also use JSEL to establish the selection and sort criteria.

A list specification is a convenient way to identify specific groups of records needed when a procedure is running. Use the JSEL form to specify a file and the selection criteria for selecting records. The field names that you use for the selection criteria must be part of the specified file. At runtime, Envision evaluates the selection criteria, selects the records, and stores them in the list.

You can also use the JSEL form to specify the sort and break criteria. Depending on the list specifications you enter, end users may have the option of altering the selection, sort, and break criteria.

Figure 74: Sample Procedure List Specification (JSEL) Form

352 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 353: Envision Runtime Administration

Procedure List Specification (JSEL)

Table 24: Query Lang Retrieval Help for Procedure List Specification (JSEL) Form

Where Procedure List Specification (JSEL) Data Is StoredTo retrieve data from use this file and this field

Procedure List LookUp PRCS.CTL PROCESS.MNEMONIC

Dictionary Name PRCS.GEN LS.FNAME

R/T File Variable PRCS.GEN LS.FILEVAR

List Description PRCS.CTL PROCESS.DESCRIPTION

Connective PRCS.GEN LS.SELECT.CONNECTIVE

Field Name PRCS.GEN LS.SELECT.FIELD

Relation PRCS.GEN LS.SELECT.REL.OPCODE

Value PRCS.GEN LS.SELECT.VALUE

Saving Field Name PRCS.GEN LS.SAVING.FIELD

Option PRCS.GEN LS.SAVING.OPTION

Modify Runtime Criteria? PRCS.GEN LS.OTHER.SELECT.FLAG

Sort Field Name PRCS.GEN LS.SORT.FIELD

Sort Sequence PRCS.GEN LS.SORT.ORDER

Break PRCS.GEN LS.BREAK.FLAG

Runtime Administration, March 10, 2010 353© 2010 Datatel, Inc.

Page 354: Envision Runtime Administration

Appendices: Form Reference

Procedure Sort Specification (JSRT)Use the Procedure Sort Specification (JSRT) form to define the list of possible sort and break fields and the default criteria. The list of available sort fields identifies the set of fields that end users can use to specify the list at runtime. The available break fields and the default criteria are subsets of this list. Only fields entered in the available sort fields list can be used to define the available break fields and the default criteria.

You can also use the JSRT form to make certain fields mandatory for inclusion in the sort and break sequence for the list and to specify whether end users can modify the default criteria at runtime.

You can access this form by detailing in field 7 of the Procedure List Specification (JSEL) form.

Figure 75: Sample Procedure Sort Specification (JSRT) Form

354 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 355: Envision Runtime Administration

Procedure Sort Specification (JSRT)

Table 25: Query Lang Retrieval Help for Procedure Sort Specification (JSRT) Form

Where Procedure Sort Specification (JSRT) Data Is StoredTo retrieve data from use this file and this field

Procedure List LookUp PRCS.CTL PROCESS.MNEMONIC

[List Step Description] PRCS.CTL PROCESS.DESCRIPTION

Dictionary Name PRCS.GEN LS.FNAME

Available Sort Fields PRCS.GEN LS.SORTABLE.FIELDS

Required PRCS.GEN LS.SORT.REQUIRED

Available Break Fields PRCS.GEN LS.BREAKABLE.FIELDS

Required PRCS.GEN LS.BREAK.REQUIRED

Modify Runtime Criteria? PRCS.GEN LS.SORT.MODIFY

Sort Field Name PRCS.GEN LS.SORT.FIELD

Sort Sequence PRCS.GEN LS.SORT.ORDER

Break PRCS.GEN LS.BREAK.FLAG

Runtime Administration, March 10, 2010 355© 2010 Datatel, Inc.

Page 356: Envision Runtime Administration

Appendices: Form Reference

LKUP: Resolution Specs (LPRT)Use the LKUP: Resolution Specifications (LPRT) procedure to create current documentation for any or all LookUp Resolution forms defined in this application. You can create these specifications through the LookUp Resolution Specs (UTRD) form.

Use this form to specify the LookUp Resolution forms in this application for which you want to create documentation.

For more information about the LookUp Resolution Specs (UTRD) form, refer to “LookUp Resolution Specs (UTRD)” beginning on page 452.

Figure 76: Sample LKUP: Resolution Specs (LPRT) Form

356 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 357: Envision Runtime Administration

Migrate Computed Columns (MGCC)

Migrate Computed Columns (MGCC)Use the Migrate Computed Columns (MGCC) form to perform the following steps for migration:

Convert your computed columns to the new R18 computed column language.

Create a record in the CC.ITEMS file for each computed column.

Move all computed columns into the appl.CDD file. (Some computed columns may have existed only in the RT.FIELDS file in R17.)

Run this process from each application (CORE, ST, etc.) in which you have custom computed columns.

Figure 77: Migrate Computed Columns (MGCC) Form

ALERT! This form is available in Release 18.0 for Envision 4.8 only.

Runtime Administration, March 10, 2010 357© 2010 Datatel, Inc.

Page 358: Envision Runtime Administration

Appendices: Form Reference

Migrate IS-Type Subroutines (MGIS)Use this process to convert your computed column subroutines so they can be used in R18. This process does the following:

Creates a record in the CC.ITEMS file for each computed column subroutine.

Assigns the computed column subroutines to the USER bundle, in preparation for later migration steps.

You only need to run this process one time, from the Envision Tool Kit for any application.

Figure 78: Sample Migrate IS-Type Subroutines (MGIS) Form

ALERT! This form is available in Release 18.0 for Envision 4.8 only.

358 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 359: Envision Runtime Administration

Other Technical Documentation (ODOC)

Other Technical Documentation (ODOC)

Use the Other Technical Documentation (ODOC) form to create or maintain miscellaneous technical documentation related to your process. This may include overview, workflow, or test plan documentation, or documentation of a complex algorithm or calculation.

Figure 79: Other Technical Documentation (ODOC) Form

Runtime Administration, March 10, 2010 359© 2010 Datatel, Inc.

Page 360: Envision Runtime Administration

Appendices: Form Reference

PRCS.CTL Security Inquiry (PCSI)Use this form to inquire about the security classes that currently affect this process. If a security class restricts a process, end users in that class cannot see that process on a menu or run it. An end user can only run the processes that his security class allows.

Figure 80: Sample PRCS.CTL Security Inquiry (PCSI) Form

360 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 361: Envision Runtime Administration

PRCS.CTL Security Inquiry (PCSI)

Table 26: Query Lang Retrieval Help for PRCS.CTL Security Inquiry (PCSI) Form

Where PRCS.CTL Security Inquiry (PCSI) Data Is StoredTo retrieve data from use this file and this field

Process Control PRCS.CTL PROCESS.MNEMONIC

Securable PRCS.CTL PRCS.SECURABLE.FLAG

Denial Classes PRCS.CTL PROCESS.DENIAL.CLASS.LIST

Access Only Classes PRCS.CTL ACCESS.ONLY.CLASS.LIST

Inquiry Only Classes PRCS.CTL INQUIRY.ONLY.CLASS.LIST

Process Secure Fields PRCS.CTL PROCESS.SECURE.FIELDS

Denial Field Classes PRCS.CTL PRCS.DENIAL.FLD.CLASSES

Access Field Classes PRCS.CTL PRCS.ACCESS.FLD.CLASSES

Inquiry Field Classes PRCS.CTL PRCS.INQUIRY.FLD.CLASSES

No Change Field Classes PRCS.CTL PRCS.NOCHANGE.FLD.CLASSES

No Delete Field Classes PRCS.CTL PRCS.NODELETE.FLD.CLASSES

Runtime Administration, March 10, 2010 361© 2010 Datatel, Inc.

Page 362: Envision Runtime Administration

Appendices: Form Reference

Peripheral Option Defaults (PDEF)Use the Peripheral Option Defaults (PDEF) form to define a peripheral specification for Envision procedures. When Envision generates a procedure, it uses these definitions to generate peripheral assignment, unassignment, and current setting commands. PDEF lets you customize printer defaults for standard reports that do not give you the option of making these types of changes at runtime. In addition to defining system printer devices, you can use PDEF to define output to asynchronous lines and dedicated printers.

For added security when you choose either Hold/Browse File Output or PDF Output (in the Output Device field), you can specify the storage location of the output file. The following options are available:

Enter PB (public) if you want the output file to be written to the public hold directory.

Enter PR (private) if you want the output file to be written to your own private hold directory.

Enter SH (shared) if you want the output file to be written to a group hold directory, then enter the group name into the security group field.

Figure 81: Sample Peripheral Option Defaults (PDEF) Form

362 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 363: Envision Runtime Administration

Peripheral Option Defaults (PDEF)

Table 27: Query Lang Retrieval Help for Peripheral Option Defaults (PDEF) Form

Where Peripheral Option Defaults (PDEF) Data Is StoredTo retrieve data from use this file and this field

Peripheral ID LookUp PRINTERS PRINTERS.ID

Description PRINTERS PTR.DESCRIPTION

Width PRINTERS PTR.WIDTH

Length PRINTERS PTR.LENGTH

Top Margin PRINTERS PTR.TMARGIN

Bottom Margin PRINTERS PTR.BMARGIN

Route Output to PRINTERS PTR.MODE

Banner PRINTERS PTR.BANNER

Copies PRINTERS PTR.COPIES

Form Name PRINTERS PTR.FORM.NAME

Location PRINTERS PTR.LOCATION

Defer Time PRINTERS PTR.DEFER

Other Options PRINTERS PTR.OPTIONS

Runtime Administration, March 10, 2010 363© 2010 Datatel, Inc.

Page 364: Envision Runtime Administration

Appendices: Form Reference

PDF Defaults (PDFD)Use the PDF Defaults (PDFD) form to define parameters for Colleague report processes that create PDF output. Specify the DMI listener with the application role to handle the PDF file creation. Also, define the default maximum number of pages for a particular PDF file.

Figure 82: Sample PDF Defaults (PDFD) Form

ALERT! PDF files up to 100,000 pages are supported. However, the larger the PDF file, the more memory is consumed for the DMI listener you specify in the PDF Application Listener field. To avoid this, set the Max Pages per PDF field accordingly. This will separate PDF output into multiple files to decrease the size of the PDF file stored in memory during creation. As an alternative, you can define a separate application listener in the PDF Application Listener field to which PDF requests can be routed, in order to lessen the memory usage of your Colleague environment's application listener. Datatel recommends a memory size of at least one gigabyte for the PDF application listener if a report process will produce a single PDF file with 100,000 pages.

364 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 365: Envision Runtime Administration

PDF Retrieval (PDFR)

PDF Retrieval (PDFR)Use the PDF Retrieval (PDFR) form to view or delete PDF files in either the private or shared HOLD directories. The PDF files stored in these directories are created from Colleague report processes capable of producing PDF output.

When browsing, the PDF files will be downloaded to your computer and displayed automatically. The data transfer performance is affected by the settings on the UI Administration Parameters (UIPR) form. If FTP is enabled for the environment, then file transfers will be faster. Otherwise, the default telnet data transfer is used, which can result in slower performance for large PDF files. When browsing files using any interface other than UI desktop, the UI Web Admin Parameters (UWPR) form must be filled in to transfer the files to your computer.

Figure 83: Sample PDF Retrieval (PDFR) Form

Note: Shared HOLD directories are defined using the Output Security Groups (OSGD) form and are accessible only by a specific operating system group of users.

Runtime Administration, March 10, 2010 365© 2010 Datatel, Inc.

Page 366: Envision Runtime Administration

Appendices: Form Reference

Point to Full Release Copy (PRTF)Once you have tested a point release and are ready to make it available to your live account then you should run the Point to Full Release Copy (PRTF) process. The PRTF process copies all information on the point release to the full release this account is designed to combine with. It is strongly recommended that a full install is backed up before performing this step, and that there is no activity in any of the remote accounts that point to the full install.

Figure 84: Sample Point to Full Release Copy (PRTF) Form

Note: The Point to Full Release Copy (PRTF) form is not used for Envision 4.8 because of changes to the Envision architecture.

366 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 367: Envision Runtime Administration

Proc Gen to Screen Proc Conv (PTSC)

Proc Gen to Screen Proc Conv (PTSC)Use the Proc Gen to Screen Proc Conv (PTSC) form to select an existing procedure that has been defined through the Procedure Specification (JDEF) form and related forms. The procedure specifications for the procedure will be generated into hook code that is put into the target form you specify. The form that you specify will have its dedicated hook for procedures filled (and possibly replaced) by generated hook code that is derived from the old-style procedure generator specifications. If you are running this process with a target form that already has hook code in it for form procedures, then that code will be displayed for your viewing. Make sure that you want to proceed to replace the existing code.

Figure 85: Proc Gen to Screen Proc Conv (PTSC) Form

Runtime Administration, March 10, 2010 367© 2010 Datatel, Inc.

Page 368: Envision Runtime Administration

Appendices: Form Reference

Rebuild Field History (RBFD)Detail to the Rebuild Field History (RBFD) form from the Rebuild File History (RBFH) form when you want to view a record as it previously existed from a history value. You can detail to this form in order to view the actual values for a specific field.

Figure 86: Sample Rebuild Field History (RBFD) Form

Note: The RBFD form is inquiry-only. You cannot use it to change a record or revert it to an earlier state.

368 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 369: Envision Runtime Administration

Rebuild File History (RBFH)

Rebuild File History (RBFH)Use the Rebuild File History (RBFH) form to view a record in a file as it previously existed on a certain date. Envision then retrieves the contents of that record as of the specified date, using the field history.

To retrieve the history, Envision selects the file.HIST.LOG file by HL.RECORD.ID. You can improve the performance of this select if you index file.HIST.LOG by HL.RECORD.ID. The RBFH form is inquiry-only. You cannot use it to change a record or revert it to an earlier state

Figure 87: Sample Rebuild File History (RBFH) Form

Note: If you do not have field history set up for a file, you will not be able to retrieve the history for that file, since there is no history stored. Define the fields whose history you want to track using the Define Field History (DHST) form.

Table 28: Query Lang Retrieval Help for Rebuild File History (RBFH) Form

Where Rebuild File History (RBFH) Data Is StoredTo retrieve data from use this file and this field

Field PRCS.CTL PROCESS.FIELD.LIST

Runtime Administration, March 10, 2010 369© 2010 Datatel, Inc.

Page 370: Envision Runtime Administration

Appendices: Form Reference

Record Security: List Specs (RPRT)Use the Record Security: List Specifications (RPRT) report to get a list of all the record-level security specifications set up for the selected files. You can create these specifications through the Record Security Specification (UTMR) process.

You can print the record security specifications for a subset of the stored data. This form provides a way to create selection criteria for identifying the files for which you want information printed.

For more information about the Record Security Specification (UTMR) form, see page “Record Security Specification (UTMR)” beginning on page 448.

Figure 88: Sample Record Security: List Specs (RPRT) Form

370 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 371: Envision Runtime Administration

Define Key Functions (RS2)

Define Key Functions (RS2)Use the Define Key Functions (RS2) form to define or modify key derivation functions. This form is only accessed by detailing from field 1 on the Record Security User Characteristics (RSUC) form.

Figure 89: Sample Define Key Functions (RS2) Form

ALERT! You cannot access this form from the RSUC form if the key derivation is not a function.

Runtime Administration, March 10, 2010 371© 2010 Datatel, Inc.

Page 372: Envision Runtime Administration

Appendices: Form Reference

Rec Sec User Characteristics (RSUC)Use the Record Security User Characteristics (RSUC) form to define values against which to test an end user’s access to records defined in the Record Security Specification (UTMR) form. The fields define where and how to set up a group of end user parameters that Envision evaluates when an end user enters an application.

The following list of valid keywords defined in RSUC can be used in UTMR:

DEVICE.NAME. The end user’s current device type

USERID. The end user’s login ID

APPL.NAME. The current application

STARTUP.PROCESS. The menu or process that the end user first accesses when entering the current application

TERMINAL.USER. Whether the current end user is a terminal end user (1) or a background process (0)

You can also view these keywords and values for the current end user when you detail at field 2 on the RSUC form.

If you change existing characteristics or add new characteristics, the end user must reinitialize Envision Runtime before those changes or additions take effect. There are two ways to initialize Envision Run- time:

Exit the database management system and reenter it, or

Run the program ENVINIT (by entering ENVINIT) from the database management system prompt.

372 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 373: Envision Runtime Administration

Rec Sec User Characteristics (RSUC)

Figure 90: Sample Rec Sec User Characteristics (RSUC) Form

Table 29: Query Lang Retrieval Help for Rec Sec User Characteristics (RSUC) Form

Where Rec Sec User Characteristics (RSUC) Data Is StoredTo retrieve data from use this file and this field

Parameter Name RSPARAMS RS.PARMS.DEF.NAME

Source File RSPARAMS RS.PARMS.FILE

Field Name RSPARAMS RS.PARMS.ATTR.NAME

Number RSPARAMS RS.PARMS.ATTR

Key Derivation RSPARAMS RS.PARMS.KEY.DERIV

Runtime Administration, March 10, 2010 373© 2010 Datatel, Inc.

Page 374: Envision Runtime Administration

Appendices: Form Reference

Security Parameter Values (RSV)Use the Security Parameter Values (RSV) form to do the following:

View the parameters and characteristics evaluated for the current end user

View the predefined keywords of the record security characteristics

You may only access this form by detailing from field 2 on the Record Security User Characteristics (RSUC) form.

Figure 91: Sample Security Parameter Values (RSV) Form

374 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 375: Envision Runtime Administration

Record Security: Test Specs (RTST)

Record Security: Test Specs (RTST)Record security as defined on the UTMR forms controls access to file records based on one or more select criteria. This report produces a listing of all the criteria that are defined for a specific file. It will also optionally display the internal compiled format of the select criteria as well, possibly for debugging purposes.

Figure 92: Sample Record Security: Test Specs (RTST) Form

Runtime Administration, March 10, 2010 375© 2010 Datatel, Inc.

Page 376: Envision Runtime Administration

Appendices: Form Reference

Security Class Definition (SCD)Use the Security Class Definition (SCD) form to establish security classes, the foundation of the process-level security system. The classes identify the processes available to the end users on your system within an application. If a security class restricts a process, end users in that class cannot see that process on a menu or run it. An end user can only run the processes that his security class allows.

A security class ID code identifies each security class. You can assign this code to operator and device records, which means you can assign security by operator or by device. Use the Operator Definition (SOD) and Device Definition (SDD) forms to define operator and device records. For switch-based systems, Envision assigns security according to an end user’s login ID. For port-based systems, Envision assigns security classes according to a terminal’s port number. Device security works only with port-based systems.

Four windows are available on the SCD form for establishing the appropriate security. To create security classes, enter process or menu mnemonics in one or more of the following windows, as appropriate:

1. Do Only These. End users in this security class have access only to the items listed in this window. For information on how detail forms function for the items you list, see “Restricting User Access for Detail Forms” on page 150. Be sure to include all process/menu mnemonics, and EX (Exit) or LO (Logoff) if you want these end users to have access to these options. Remember that EX takes end users out of Envision and places them at the database management system level.

2. Never Do These. End users in this security class never have access to the items listed in this window. End users automatically have rights to all processes except those listed in this window (and any listed as privileged in another class; see below).

3. Inquiry Only. End users in this security class may only view field data for the processes listed in this window. They cannot change, delete, or add field data for these processes.

4. Privileged. End users in this security class have exclusive rights to the items listed in this window. End users not assigned to this class cannot access these items unless they are assigned as privileged in another class. You can identify the same item as privileged in more than one security class.

Remember that end users can have access to more than one security class. If so, Envision merges the security settings of each class. See the description of each window for an explanation of how Envision merges the settings for multiple security classes.

376 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 377: Envision Runtime Administration

Security Class Definition (SCD)

Also remember that when you define security classes, you can only list mnemonics in these windows that you have already marked as ones that are subject to process-level security checks using the Menu Definition (SMD) form. You cannot apply process-level security to a mnemonic that does not already appear on a menu or to a mnemonic that is not subject to process-level security checks.

For more information about Operator Definition (SOD), refer to page 409. See page 388 for details on the Device Definition (SDD) form. For more information about the Menu Definition (SMD) form, refer to page 401.

Figure 93: Sample Security Class Definition (SCD) Form

Runtime Administration, March 10, 2010 377© 2010 Datatel, Inc.

Page 378: Envision Runtime Administration

Appendices: Form Reference

Table 30: Query Lang Retrieval Help for Security Class Definition (SCD) Form

Where Security Class Definition (SCD) Data Is StoredTo retrieve data from use this file and this field

Security Class ID SECLASS SYS.CLASS.ID

Menu Timeout SECLASS SECLASS.MENU.TIMEOUT

Description SECLASS SYS.CLASS.DESCRIPTION

Do Only These SECLASS LIMITED.TO.PROCESS.LIST

Never Do These SECLASS PROHIBITED.PROCESS.LIST

Inquiry Only SECLASS INQUIRY.ONLY.PROCESS.LIST

Privileged SECLASS DENY.ACCESS.EXCEPT.TO.CLASS

378 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 379: Envision Runtime Administration

Field Security Definition (SCDF)

Field Security Definition (SCDF)Use the Field Security Definition (SCDF) form to define field-level security for data elements in the current application. You can define a new security class or use an existing class as defined on the Security Class Definition (SCD) form. Field-level security can be separate from process-level security, or they can be used together.

Field-level security allows you to secure data elements across entire files. For example, if you want only the end users in the payroll office to see salary figures, you can define a security class for those end users in the Payroll Office that gives them exclusive access to the salary field. If any other users attempt to access data from that field, regardless of the Envision form they use, they see only asterisks in that field.

Figure 94: Sample Field Security Definition (SCDF) Form

Runtime Administration, March 10, 2010 379© 2010 Datatel, Inc.

Page 380: Envision Runtime Administration

Appendices: Form Reference

Table 31: Query Lang Retrieval Help for Field Security Definition (SCDF) Form

Where Field Security Definition (SCDF) Data Is StoredTo retrieve data from use this file and this field

Security Class ID SECLASS SYS.CLASS.ID

Description SECLASS SYS.CLASS.DESCRIPTION

Field to be Secured SECLASS CLASS.SECURED.ELEMENTS

Security Level SECLASS CLASS.ELEMENT.SECURITY.LEVEL

380 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 381: Envision Runtime Administration

Record Security Setup (SCDR)

Record Security Setup (SCDR)Use the Record Security Setup (SCDR) form to assign the security keys used in an application or a module to one or more security classes defined on the Security Class Definition (SCD) form. The security keys control access to specific records within an application. End users without the appropriate security keys in their security class(es) cannot access those records.

Use the security parameters form within an application or module to define the security keys for that application or module. For example, use the General Ledger Account Parameters (GLAP) form to define the security keys for General Ledger. You should define security classes and the application’s security keys before using SCDR to assign those keys to specific security classes.

SCDR works only with the General Ledger (GL) module.

Figure 95: Sample Record Security Setup (SCDR) Form

Runtime Administration, March 10, 2010 381© 2010 Datatel, Inc.

Page 382: Envision Runtime Administration

Appendices: Form Reference

Table 32: Query Lang Retrieval Help for Record Security Setup (SCDR) Form

Where Record Security Setup (SCDR) Data Is StoredTo retrieve data from use this file and this field

Security Class ID SECLASS SYS.CLASS.ID

Description SECLASS SYS.CLASS.DESCRIPTION

Characteristics SECLASS CLASS.CHARACTERISTICS

Record Security Exception Processes

SECLASS SECLASS.RECSEC.EXCEPTIONS

382 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 383: Envision Runtime Administration

Operator Security Report (SCOR)

Operator Security Report (SCOR)The Operator Security Report will report on the secured processes that each selected operator may access. Operators may be selected individually, or all operators may be selected (this is the default).

The scope of the report may be narrowed by selecting specific modules and/or applications that processes may belong to.

Figure 96: Sample Operator Security Report (SCOR) Form

Runtime Administration, March 10, 2010 383© 2010 Datatel, Inc.

Page 384: Envision Runtime Administration

Appendices: Form Reference

Process Security Report (SCPR) The Process Security Report will report on the Operators who have access to any given process. Processes may be specified individually, or may be selected by the applications and/or modules to which they belong.

Figure 97: Sample Process Security Report (SCPR) Form

384 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 385: Envision Runtime Administration

Screen Chaining Specification (SCSP)

Screen Chaining Specification (SCSP)Use the Screen Chaining Specification (SCSP) form to group otherwise independent screens together so that they are presented to the user as a set, one after the other.

The most seamless chain of screens is one where each screen would otherwise prompt the user for the same thing. For example, in the Demographics module in the Core System, the following forms all prompt the user for a person ID:

Name and Address Maintenance (NAE)

Relation Information (REL)

Emergency Information (EMER)

Suppose you chained these screens in the order shown above. When a user accessed the chain, the Name and Address Maintenance form would be displayed, and the user would be prompted to enter a person ID. When the user finished the Name and Address Maintenance form, the Relation Information form would be displayed for the same person with no further prompt. When the user finished from the Relation Information form, the Emergency Information form would be displayed for the same person with no further prompt.

If you chain screens that would otherwise prompt the user for different things, then the appropriate prompts are displayed when each screen is displayed. You can chain screens that are totally unrelated.

You can define a screen chain from within any application. The screens you include in a chain must be accessible from the application in which you are working or from an application above it in the hierarchy. The chain itself will be available to users of the application in which it is defined as well as to users of applications that are below it in the hierarchy. For example, if you define a screen chain in the Core System, you can include only screens that are in the Core System or in Runtime. That same chain, once defined, is then available to users in the Core System and to users in the Financial System and its peer applications.

Runtime Administration, March 10, 2010 385© 2010 Datatel, Inc.

Page 386: Envision Runtime Administration

Appendices: Form Reference

All screens within a chain take on the security rights specified for the chain. If the security rights you specify for a screen differ from the security rights you specify for a chain to which that screen belongs, the chain’s security rights take precedence.

Use the Chain Usage Report (CHUS) to obtain reports on chains and the screens they contain. These reports can help you administer security for screen chains.

There are three function keys available to support movement among chained screens: Screen FWD, Screen BACK, and Screen JUMP. In addition, some of the existing function keys work differently for chained screens. See “Grouping Screens” beginning on page 121for further information on this topic.

Figure 98: Sample Screen Chaining Specification (SCSP) Form

ALERT! It is important to ensure that access to the Form Chaining Specification form is limited. Otherwise, someone could use the Screen Chaining Specification form to add an otherwise inaccessible screen to an accessible chain.

386 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 387: Envision Runtime Administration

Screen Chaining Specification (SCSP)

Table 33: Query Lang Retrieval Help for Screen Chaining Specification (SCSP) Form

Where Form Chaining Specification (SCSP) Data Is StoredTo retrieve data from use this file and this field

Chain Process LookUp PRCS.CTL PROCESS.MNEMONIC

Description PRCS.CTL PROCESS.DESCRIPTION

PROCESS.GROUP.POST.COMMIT

PRCS.CTL PROCESS.GROUP.POST.COMMIT

Short Help SHRTHELP SHORT.HELP.MESSAGE

Mnemonic PRCS.CTL PROCESS.GROUP.FORMS

Require PRCS.CTL PROCESS.GROUP.REQUIRED

Runtime Administration, March 10, 2010 387© 2010 Datatel, Inc.

Page 388: Envision Runtime Administration

Appendices: Form Reference

Device Definition (SDD)Use the Device Definition (SDD) form to identify the terminals, printers, and other devices used for all Envision-based applications on your system. Currently, this form lets you identify only terminal devices (displays and keyboards). Because all applications share the DEVICES file, you only need to have one device record for your system, regardless of the number of Envision-based applications.

On this form, you can specify the following device characteristics:

Device-level password

Keyboard definition

Display definition

Default security classes for the device

Computer Access Strategies

Access to most computer systems follows one of two strategies:

Switch-based system

Port-based system

A switch-based computer system has an external switching computer or an external network computer that assigns the first available port to an end user trying to access the computer. Usually, the end user logs on to a different port for each session. For these systems, Envision assigns devices according to the end user’s operating system login ID to ensure that the end user always has the same device definition, regardless of the port assigned by the switch.

On a port-based computer system, end users get the same port from the same device every time they log on, regardless of their login IDs. On port-based systems, Envision assigns devices according to the port number of the device, as specified on the Network Definition (SND) form. This ensures that the Envision display and keyboard tables are compatible with the hardware associated with the device.

388 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 389: Envision Runtime Administration

Device Definition (SDD)

Assigning Devices on a Switch-based System

Device IDs for a switch-based system correspond to end users’ login IDs—one device record for each end user. Each end user can have distinct passwords, keyboard tables, and display tables. An end user has the same device definition regardless of the port assigned by the switch.

Assigning Devices on a Port-based System

The device ID for a port-based device relates to the type of device attached to the port and any special characteristics of its location. For example, to define a device record for a generic Wyse 50 terminal, use WYSE50 as the device ID. Define only one device record for generic terminal types. These device definitions can be shared among several ports. If you want to add additional security to a specific terminal on a specific port, define a separate device record for that terminal (for example, SYSADM).

Combining Features of Switch-Based and Port-Based Systems

If your computer is a switch-based system with certain ports hard-wired, you can combine the features of both device assignment methods. The port-definition window on the Network Definition (SND) form lets you assign a hard port for a switch-based system. You can assign the hard-wired ports on your computer to specific device definitions that are active for any end user logging into that port. For that port alone, Envision assigns device characteristics just as it would if the whole system were port-based.

Device Security

You can assign process-level security--in the form of security classes--to each device. Assign security classes to device records only for port-based devices. You can then secure specific terminals from running certain processes, regardless of the operator. If you are using switch-based devices, assign security classes to each individual end user instead of to a terminal.

Runtime Administration, March 10, 2010 389© 2010 Datatel, Inc.

Page 390: Envision Runtime Administration

Appendices: Form Reference

Remember that all applications share the same device definitions, so if you assign a security class to a device, you must define it in all applications using that device. Use the Security Class Definition (SCD) form to define security classes.

When you make changes to an end user’s device definition, that end user must log out and log back into the system before the changes take effect.

For more information on defining the access method for your computer, refer to page 407. For more information on defining security classes, refer to page 376.

Figure 99: Sample Device Definition (SDD) Form

Technical Tip: For switch-based devices, the system ignores the security classes defined in the device record.

390 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 391: Envision Runtime Administration

Device Definition (SDD)

Table 34: Query Lang Retrieval Help for Device Definition (SDD) Form

Where Device Definition (SDD) Data Is StoredTo retrieve data from use this file and this field

Device ID DEVICES SYS.DEVICE.ID

Security Classes DEVICES SYS.DEVICE.CLASSES

Display type DEVICES SYS.DEVICE.TYPE

Keyboard type DEVICES SYS.KEYBOARD.SPECS

Device Password DEVICES SYS.DEVICE.PASSWORD

Max Attempts DEVICES SYS.DEVICE.TRIES

Location DEVICES SYS.DEVICE.LOCATION

Sessions since DEVICES SYS.DEVICE.COUNT.BASE.DATE

[Number of sessions] DEVICES SYS.DEVICE.SESSION.COUNT

Most recent session on DEVICES SYS.DEVICE.LAST.SESSION.DATE

at DEVICES SYS.DEVICE.LAST.LOGIN.TIME

using line DEVICES SYS.DEVICE.LINE

by operator DEVICES SYS.DEVICE.LAST.USER

Runtime Administration, March 10, 2010 391© 2010 Datatel, Inc.

Page 392: Envision Runtime Administration

Appendices: Form Reference

Define Terminal Keyboard (SKB)Use the Define Terminal Keyboard (SKB) form to create and edit tables for terminal keyboards. A terminal table for each terminal keyboard consists of a list of Envision function keys and editing keys and the corresponding values sent by the terminal when end users press the associated keys. When you define a keyboard, you must then assign it to one or more devices through the Device Definition (SDD) form.

Defining a Keyboard

If a terminal table is not available for one or more of your terminals, use the SKB forms to create one. First, decide on the keyboard layout. Determine which function key or key sequence on the terminal keyboard you want to use to perform each Envision function. Usually, the keyboard’s function keys and editing keys perform the Envision functions. If the terminal does not have function keys, however, you can use the Ctrl and Esc key sequences. When you have established the keyboard layout, consult the reference documentation for the terminal to find out the command sequence that each key sends when pressed. Use this information to define the terminal table through the SKB forms. After defining the table, create a template to match the key sequence for the terminal.

392 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 393: Envision Runtime Administration

Define Terminal Keyboard (SKB)

Figure 100: Sample Define Terminal Keyboard (SKB) Form

Table 35: Query Lang Retrieval Help for Define Terminal Keyboard (SKB) Form

Where Define Terminal Keyboard (SKB) Data Is StoredTo retrieve data from use this file and this field

Keyboard Definition ID KEYDEFS KEYBOARD.ID

Terminal KEYDEFS KBD.TARGET.TERMINAL

Description KEYDEFS KBD.DESCRIPTION

Layout Style KEYDEFS KBD.LAYOUT.STYLE

Runtime Administration, March 10, 2010 393© 2010 Datatel, Inc.

Page 394: Envision Runtime Administration

Appendices: Form Reference

Define Function Keys (SKB1)Use the Define Function Keys (SKB1) form to define which key sequence on the terminal keyboard you want to use to perform each Envision function. ANSI terminals send commands to the host computer using escape sequences, while non-ANSI terminals may send commands through function key sequences.

When end users press a key to perform a function, most terminals prefix, or start, the command for the function by sending a special sequence to let the host computer know that the next sequence it receives corresponds to a function. For each Envision function, you must include this special sequence as part of the key sequence.

Since this special sequence is usually the same for most keys, you may choose to specify this special sequence on the Define Cursor Keys (SKB2) form. Envision then automatically prefixes each command with this special sequence for every Envision function. If the terminal sends commands using escape sequences and you specify the special sequence using SKB2, prefix each Envision key definition on this form with ESC. ESC is normally defined on SKB2 as CTL [ . If the terminal sends commands through function key sequences and you specify the special sequence using SKB2, prefix each Envision key definition on this form with FKY. FKY is normally defined on SKB2 as CTL A.

394 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 395: Envision Runtime Administration

Define Function Keys (SKB1)

Figure 101: Sample Define Function Keys (SKB1) Form

Table 36: Query Lang Retrieval Help for Define Function Keys (SKB1) Form

Where Define Function Keys (SKB1) Data Is StoredTo retrieve data from use this file and this field

Keyboard Definition ID KEYDEFS KEYBOARD.ID

Next Field KEYDEFS KBD.FIELD.FWD

Previous Field KEYDEFS KBD.FIELD.BACK

Jump to Field # KEYDEFS KBD.FIELD.JUMP

Next Group KEYDEFS KBD.WINDOW.FWD

Previous Group KEYDEFS KBD.WINDOW.BACK

Jump to Group # KEYDEFS KBD.WINDOW.JUMP

Go to First Group KEYDEFS KBD.PAGE.HOME

Go to Last Group KEYDEFS KBD.PAGE.END

Scroll toward 1st KEYDEFS KBD.PAGE.BACK

Scroll toward last KEYDEFS KBD.PAGE.FWD

Scroll to Page # KEYDEFS KBD.PAGE.JUMP

Insert New Group KEYDEFS KBD.WINDOW.INSERT

Runtime Administration, March 10, 2010 395© 2010 Datatel, Inc.

Page 396: Envision Runtime Administration

Appendices: Form Reference

Next Element KEYDEFS KBD.ELEMENT.FWD

Previous Element KEYDEFS KBD.ELEMENT.BACK

Exit KEYDEFS KBD.EXIT

Finish KEYDEFS KBD.FINISH

Update KEYDEFS KBD.UPDATE

Cancel KEYDEFS KBD.CANCEL

Delete Record KEYDEFS KBD.RECORD.DELETE

Detail KEYDEFS KBD.DETAIL

Direct Access KEYDEFS KBD.DIRECT.ACCESS

Form Fwd KEYDEFS KBD.FORM.FWD

Form Back KEYDEFS KBD.FORM.BACK

Form Jump KEYDEFS KBD.FORM.JUMP

Process Help KEYDEFS KBD.PROCESS.HELP

Field Help KEYDEFS KBD.FIELD.HELP

Function Key Help KEYDEFS KBD.FUNCTION.HELP

Refresh Form KEYDEFS KBD.REFRESH.FORM

Table 36: Query Lang Retrieval Help for Define Function Keys (SKB1) Form (cont’d)

Where Define Function Keys (SKB1) Data Is StoredTo retrieve data from use this file and this field

396 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 397: Envision Runtime Administration

Define Cursor Keys (SKB2)

Define Cursor Keys (SKB2)Use the Define Cursor Keys (SKB2) form to define the cursor and editing keys for the Envision line editing features.

Figure 102: Sample Define Cursor Keys (SKB2) Form

Runtime Administration, March 10, 2010 397© 2010 Datatel, Inc.

Page 398: Envision Runtime Administration

Appendices: Form Reference

Table 37: Query Lang Retrieval Help for Define Cursor Keys (SKB2) Form

Where Define Cursor Keys (SKB2) Data Is StoredTo retrieve data from use this file and this field

Keyboard Definition ID KEYDEFS KEYBOARD.ID

[ASCII Sequence] KEYDEFS KBD.ESCAPE

[ASCII Sequence] KEYDEFS KBD.FUNCTION.START

Attention Characters KEYDEFS KBD.DWT.CHARS

Cursor HOME KEYDEFS KBD.HOME

Cursor UP KEYDEFS KBD.CURSOR.UP

Cursor RIGHT KEYDEFS KBD.CURSOR.RIGHT

Cursor DOWN KEYDEFS KBD.CURSOR.DOWN

Cursor LEFT KEYDEFS KBD.CURSOR.LEFT

TAB Cursor KEYDEFS KBD.TAB

Backspace KEYDEFS KBD.BACKSPACE

Delete Character KEYDEFS KBD.CHARACTER.DELETE

Insert Character KEYDEFS KBD.CHARACTER.INSERT

Erase to Line’s End KEYDEFS KBD.ERASE.END.OF.LINE

Erase Whole Line KEYDEFS KBD.ERASE.LINE

<ENTER> or <RETURN> KEYDEFS KBD.RETURN

Delete item/Line KEYDEFS KBD.FIELD.DELETE

In-line Edit Toggle KEYDEFS KBD.EDIT.TOGGLE

398 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 399: Envision Runtime Administration

Savedlist Creation (SLCR)

Savedlist Creation (SLCR)Use the Savedlist Creation (SLCR) form to create a saved list that you can subsequently use with various functions in Colleague and Envision. The data entered on the SLCR form constitute a saved list specification record. When this record is executed, the results are stored in a saved list.

If your native database is SQL-based, then you may specify the record selection criteria using either UniQuery or SQL syntax. If your native database is UniData, then only UniQuery syntax is allowed.

The saved list is created when you save from this form. If you do not want to run the query and create the saved list, then you must cancel from this form.

Figure 103: Sample Savedlist Creation (SLCR) Form

ALERT! This form is available in Release 18.0 for Envision 4.8 only.

Runtime Administration, March 10, 2010 399© 2010 Datatel, Inc.

Page 400: Envision Runtime Administration

Appendices: Form Reference

Savedlist Edit Contents (SLED)Use the Savedlist Edit Contents (SLED) form to edit the contents of a saved list. You can access this form directly from the menu or from the Savedlist Creation (SLCR) form.

When you access this form from the menu, you are prompted for the ID of the saved list record that you want to modify. When you enter the name of an existing saved list, the current contents of that saved list are loaded into the form. You can then modify the information as needed. When you finish out of the form, the new contents are saved.

When you access this form from the SLCR form, Colleague displays the records selected by the select list you entered on that form. When you enter the name of an existing saved list, the current contents of that saved list are loaded into the form. You can modify the form as needed. When you finish out of the form, the new contents are saved into the saved list record using the name specified on the SLCR form. If you do not want to save the results of the select statement, cancel out of the form.

Figure 104: Sample Savedlist Edit Contents (SLED) Form

ALERT! This form is available in Release 18.0 for Envision 4.8 only.

400 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 401: Envision Runtime Administration

Menu Definition (SMD)

Menu Definition (SMD)Use the Menu Definition (SMD) form to customize existing menus and to create new ones. You can add any process to any menu, as long as the process and the menu are both in the same application. The same processes can appear on more than one menu. You may also delete any process from any menu.

Defining a New Menu

When you define a new menu, you must first select a mnemonic for the menu. This mnemonic is the same mnemonic that end users enter to access the menu. To prevent your new menu from being overwritten during a subsequent release of the software, the letter "X" should be the first letter of your mnemonic. Datatel guarantees that a menu or process mnemonic shipped with a general release will never begin with the letter "X."

When you decide on the mnemonic, enter it at the LookUp prompt on the SMD form. Then give the menu a title. Finally, specify the processes that should appear on the menu.

After creating a new menu, you should add its mnemonic to another menu using SMD. Remember that end users can enter any mnemonic from any menu provided they have the appropriate security rights.

Adding a Process to a Menu

To add a process to an existing menu, enter the mnemonic for the menu at the LookUp prompt on the SMD form. To add an existing process, enter it in the window in field 3. To add a new process, position the cursor in the window in field 3 and detail to access the Process Control Maintenance (SMD2) form. Enter the new process on the SMD2 form rather than entering it from SMD.

Note: You should not modify the standard menus that are provided with your Datatel software, because they may be overwritten with future releases. To included Datatel processes on a menu, either create your own menus and add Datatel processes to them, or use security classes to restrict the processes to which a group of users has access.

Runtime Administration, March 10, 2010 401© 2010 Datatel, Inc.

Page 402: Envision Runtime Administration

Appendices: Form Reference

Removing a Process from a Menu

To keep a process from displaying on a menu, you should restrict its use through the Security Class Definition (SCD) form rather than deleting it through the SMD form.

Datatel recommends that you change the default menu setup only after a great deal of planning. You should leave the original setup intact and create new menus that reflect any changes. By defining a new menu containing your changes, you preserve its contents from one release to another.

If you need to remove a process from a menu, enter the mnemonic for the menu at the LookUp prompt on the SMD form. At the window in field 3, position the cursor on the item that you want to delete and press DEL twice.

Adding a Custom Program to a Menu

To add a custom program to a menu, follow the steps below:

Decide on a mnemonic for your custom program. Remember to begin your mnemonic with the letter "X" to prevent it from being overwritten with a future software release.

Using the editor, create a paragraph VOC entry named mnemonic for your custom program, as follows:

001: PA

002: RESET.TERM

003: CUSTOM.PROGRAM.NAME

Line three of the entry should be the name of your custom program. The RESET.TERM command makes sure that your cursor and backspace keys work properly.

Use SMD to add your custom program mnemonic’s VOC entry to a menu as a database management system query language statement (type I).

See page 376 for details on the Security Class Definition (SCD) form.

402 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 403: Envision Runtime Administration

Menu Definition (SMD)

Figure 105: Sample Menu Definition (SMD) Form

Table 38: Query Lang Retrieval Help for Menu Definition (SMD) Form

Where Menu Definition (SMD) Data Is StoredTo retrieve data from use this file and this field

Menu ID MENU MENU.MNEMONIC

Menu Title MENU MENU.TITLE

Menu Split MENU MENU.SPLIT

Modules MENU MENU.MODULES

Item MENU MENU.MEMBERS

Description PRCS.CTL PROCESS.DESCRIPTION

Type PRCS.CTL PROCESS.EXECUTION.TYPE

Process Name PRCS.CTL PROCESS.TO.EXECUTE

Securable PRCS.CTL PRCS.SECURABLE.FLAG

Group PRCS.CTL PROCESS.CLASS

Runtime Administration, March 10, 2010 403© 2010 Datatel, Inc.

Page 404: Envision Runtime Administration

Appendices: Form Reference

Process Control Maintenance (SMD2)Use the Process Control Maintenance (SMD2) form to view all of the information stored in an application’s PRCS.CTL file about a process or procedure. Every Envision-based application has its own Process Control file (application.PRCS.CTL). You should maintain the information shown on this form using either the Menu Definition (SMD) form or forms available in the Envision Tool Kit.

Records in the PRCS.CTL file do the following:

Define the mnemonic for a process

Determine the action to take when an end user enters that mnemonic

Control how the process appears on a menu

Provide various cross-references to other files

Records in this file are keyed in one of the following ways:

1. Processes that end users can run from a menu are keyed by their menu mnemonics. These records also have cross-reference records keyed by the process name.

2. Procedures that end users can run from a menu are keyed by their mnemonics.

3. Processes and procedures that end users can only run from other processes or from procedures are keyed by their process names. These records have no cross-reference records and no mnemonics.

4. VOC records are keyed by the name of the VOC item.

Note: You should NOT modify the process control records provided with your application. If you need to modify them, consult with Datatel before doing so. Release procedures overwrite any changed records with the default version when you load a new release of Datatel software. If you use field-level security, you may also use this form to view the fields that are secured in a particular file. If so, the files are keyed by the name of the file.

404 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 405: Envision Runtime Administration

Process Control Maintenance (SMD2)

Figure 106: Sample Process Control Maintenance (SMD2) Form

Runtime Administration, March 10, 2010 405© 2010 Datatel, Inc.

Page 406: Envision Runtime Administration

Appendices: Form Reference

Table 39: Query Lang Retrieval Help for Process Control Maintenance (SMD2) Form

Where Process Control Maintenance (SMD2) Data Is StoredTo retrieve data from use this file and this field

Process Control LookUp PRCS.CTL PROCESS.MNEMONIC

Description PRCS.CTL PROCESS.DESCRIPTION

Mnemonic Cross-Reference PRCS.CTL PROCESS.DIRECT.ACCESS.NAME

Executed Process PRCS.CTL PROCESS.TO.EXECUTE

Execute Type PRCS.CTL PROCESS.EXECUTION.TYPE

Class PRCS.CTL PROCESS.CLASS

Process Securable PRCS.CTL PRCS.SECURABLE.FLAG

Included on Menu(s) PRCS.CTL MENUS.USING.THIS.PROCESS

Module List PRCS.CTL PRCS.CTL.MODULES

Field List PRCS.CTL PROCESS.FIELD.LIST

Process Support Forms PRCS.CTL TEMP.DOC.FORM.LIST

Documentation Intro List PRCS.CTL PRCS.INTRO.LIST

Documentation Appendices PRCS.CTL PRCS.APPENDIX.LIST

Menu Tree(s) PRCS.CTL PRCS.MENU.TREE

406 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 407: Envision Runtime Administration

Network Definition (SND)

Network Definition (SND)Use the Network Definition (SND) form to assign a device ID to the appropriate port. Device IDs are defined on the Device Definition (SDD) form. The device ID identifies the terminal and keyboard type used for the port, any special security class(es) authorizing access to the system, an optional password associated with the device, and notes about the location(s) of the device.

Identifying the terminal and keyboard type is critical to properly defining function keys and ensuring accurate form display. Therefore, each device ID must be correctly defined for the corresponding port. More than one port number can have the same device ID, and all information about the device applies to each port number with that device ID. To assign each device to its correct port, you need a listing or diagram of your setup.

Figure 107: Sample Network Definition (SND) Form

Technical Tip: Use this process only with host systems that are port-dependent or host systems that run on a network.

Runtime Administration, March 10, 2010 407© 2010 Datatel, Inc.

Page 408: Envision Runtime Administration

Appendices: Form Reference

Table 40: Query Lang Retrieval Help for Network Definition (SND) Form

Where Network Definition (SND) Data Is StoredTo retrieve data from use this file and this field

Data Switch Terminal Routing? NETDEFS NETDEFS.SYSTEM.TYPE

Disable Device Security? NETDEFS NETDEFS.DEVICE.SECURITY

Default Record Security? NETDEFS NETDEFS.BASE.RECSEC.STATE

Device Name NETDEFS NETDEFS.PORTS

Hard-Wired NETDEFS NETDEFS.HARD.PORT

408 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 409: Envision Runtime Administration

Operator Definition (SOD)

Operator Definition (SOD)Use the Operator Definition (SOD) form to define operator records for all individuals who are allowed access to Envision-based applications.

You may define operator records from within any application in the hierarchy; however, Datatel strongly recommends that you define all operator records from within Runtime (UT). Maintaining all operator records at the UT level makes it easier for you to keep track of your operator definitions and reduces the likelihood of users having problems accessing certain applications.

Before you define your operator records, you should first define your security classes in each application (Security Class Definition [SCD] form).

Figure 108: Sample Operator Definition (SOD) Form

Runtime Administration, March 10, 2010 409© 2010 Datatel, Inc.

Page 410: Envision Runtime Administration

Appendices: Form Reference

Table 41: Query Lang Retrieval Help for Operator Definition (SOD) Form

Where Operator Definition (SOD) Data Is StoredTo retrieve data from use this file and this field

User ID OPERS SYS.USER.ID

Name OPERS SYS.USER.NAME

Envision Password OPERS SYS.USER.PASSWORD

Password Expiration Date OPERS SYS.PASSWORD.EXPIRATION.DATE

Security Classes OPERS SYS.USER.CLASSES

Initial Menu OPERS SYS.STARTUP.PROCESS

Maximum Login Retries OPERS SYS.MAX.USER.PW.RETRIES

SYS.USER.EDITOR OPERS SYS.USER.EDITOR

Sessions Since Date SYS.USER.COUNT.BASE.DATE

[Number of sessions] OPERS SYS.USER.SESSION.COUNT

Most Recent Session On OPERS SYS.USER.LAST.SESSION.DATE

at OPERS SYS.USER.LAST.LOGIN.TIME

using device OPERS SYS.USER.LAST.DEVICE.USED

410 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 411: Envision Runtime Administration

Studio Object Status Inquiry (SOSI)

Studio Object Status Inquiry (SOSI)Use the Studio Object Status Inquiry (SOSI) form to view the status history of a Colleague Studio object. You can access this form directly, or by detailing from the Status field on the Studio WorkGroup Inquiry (SWGI) form.

Figure 109: Studio Object Status Inquiry (SOSI) Form

Runtime Administration, March 10, 2010 411© 2010 Datatel, Inc.

Page 412: Envision Runtime Administration

Appendices: Form Reference

Speed Entry Text Definition (SPDE)In order to speed up entry of repetitive strings, Envision allows you to associated a single character to a long string. This string can then be entered by activating speed dial and typing the single character where needed.

Figure 110: Sample Speed Entry Text Definition (SPDE) Form

Table 42: Query Lang Retrieval Help for Speed Entry Text Definition (SPDE) Form

Where Speed Entry Text Definition (SPDE) Data Is StoredTo retrieve data from use this file and this field

User ID OPERS SYS.USER.ID

Name OPERS SYS.USER.NAME

Char OPERS OPERATOR.SPEED.DIAL

Entry Text OPERS OPERATOR.SPEED.TEXT

412 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 413: Envision Runtime Administration

Studio WorkGroup Definition (SWGD)

Studio WorkGroup Definition (SWGD)If you use Colleague Studio to customize Colleague applications or to create new objects, your work must be done within a workgroup to manage your custom changes. The workgroup and custom features help you to package your custom changes properly so they can be moved from one environment to another. Use the Studio WorkGroup Definition (SWGD) form to maintain workgroups.

In Colleague Studio, when you create a new Colleague Studio project against this environment, you are prompted for a workgroup on the Colleague Local Repository Provider form. The list of available workgroups in the Use existing workgroup field includes all that have an Inactive Flag set to "N" or null.

Record delete is available from the SWGD form to remove unnecessary workgroups that were created in Colleague Studio. You can only delete a workgroup that does not contain any Colleague Studio objects whose current status for that workgroup is:

"C"hecked out

"S"helved

"R"eady for build

Figure 111: Studio WorkGroup Definition (SWGD) Form

Runtime Administration, March 10, 2010 413© 2010 Datatel, Inc.

Page 414: Envision Runtime Administration

Appendices: Form Reference

Studio WorkGroup Inquiry (SWGI) Use the Studio WorkGroup Inquiry (SWGI) form to view information about all objects assigned to a Colleague Studio workgroup. You can access this form directly, or by detailing from the WorkGroups field on the Custom Release Package Build (CPKG) form.

You can also access information about these objects from within Colleague Studio. The SWGI form makes this information accessible when you are working with Colleague Studio objects in UI – for example, when building a release package on the CPKG form.

Figure 112: Studio WorkGroup Inquiry (SWGI) Form

414 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 415: Envision Runtime Administration

User Help Maintenance (UHLP)

User Help Maintenance (UHLP)All standard Envision CDD elements, processes and menus have runtime help messages shipped with them. This information is entered during development on the HLP form when in the Envision Toolkit. In some cases it may be desirable to changed the stock help information as shipped to something else desired at runtime.

This form allows the modification of any short and long help that is stored in the currently running application HELP and HELP.LONG files.

In addition, information is provided on how to use a particular help message, such as the field help tied to a field on one or more forms.

Figure 113: Sample User Help Maintenance (UHLP) Form

Runtime Administration, March 10, 2010 415© 2010 Datatel, Inc.

Page 416: Envision Runtime Administration

Appendices: Form Reference

Table 43: Query Lang Retrieval Help for User Help Maintenance (UHLP) Form

Where User Help Maintenance (UHLP) Data Is StoredTo retrieve data from use this file and this field

SHORT.HELP.ID SHRTHELP SHORT.HELP.ID

Dictionary Xref SHRTHELP HELP.DICTIONARY.XREF

Data File Name SHRTHELP HELP.DATA.FILE.NAME

Field Number SHRTHELP HELP.FIELD.NUMBER

Pointer File SHRTHELP HELP.POINTER.FILE

Validation Type SHRTHELP HELP.VALIDATION.TABLE

SHRTHELP.ADD.DATE SHRTHELP SHRTHELP.ADD.DATE

SHRTHELP.ADD.OPERATOR SHRTHELP SHRTHELP.ADD.OPERATOR

SHRTHELP.CHANGE.DATE SHRTHELP SHRTHELP.CHANGE.DATE

SHRTHELP.CHANGE.OPERATOR

SHRTHELP SHRTHELP.CHANGE.OPERATOR

Process SHRTHELP HELP.PROCESS.LIST

Alternate Dict SHRTHELP HELP.ALTERNATE.DICT

Short Help SHRTHELP SHORT.HELP.MESSAGE

416 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 417: Envision Runtime Administration

Update Main Remote Accounts (UMRA)

Update Main Remote Accounts (UMRA)Use the Update Main Remote Accounts (UMRA) form to bring a main account up to the same release level as another account. Like the Update User Remote Accounts (UURA) process, UMRA updates an account’s VOC to point to programs and files associated with the new release.

Because main accounts typically have their own copy of most data files, UURA provides a step that logs any new files to be created and optionally suspends creation of those files until the paths to where those files are to be created have been reviewed and accepted via the Remote Account New Files (UNFR) form. Using UNFR, it is possible to override the default paths derived via rules given in the account’s REMOTES record.

Once the paths are as desired, processing can proceed and new files can be created as requested. This process is primarily intended for updating an existing main account where the volume of new files from a release are small and easy to review file by file. When creating a new main account for Colleague, the volume of new files make it reasonable to accept the normal default paths for new files. You can manage the fine tuning of data distribution at a later date.

For more information about the Update User Remote Accounts (UURA) form, refer to page 471.

For more information about the Remote Account New Files (UNFR) form, refer to page 420.

Note: The Update Main Remote Accounts (UMRA) form is not used for Envision 4.8 because of changes to the Envision architecture.

Note: The UURA and UNFR forms are not used for Envision 4.8 because of changes to the Envision architecture.

Runtime Administration, March 10, 2010 417© 2010 Datatel, Inc.

Page 418: Envision Runtime Administration

Appendices: Form Reference

Figure 114: Sample Update Main Remote Accounts (UMRA) Form

418 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 419: Envision Runtime Administration

Report on New/Obsolete Files (UNFP)

Report on New/Obsolete Files (UNFP)You can run the UMRA process with the option to detect new and obsolete files. These files may be reviewed on the Remote Account New Files (UNFR) form after the scan. This report will produce an output matching what is visible on the UNFR form.

Figure 115: Sample Report on New/Obsolete Files (UNFP) Form

Note: The Remote Account New Files (UNFR) form is not used for Envision 4.8 because of changes to the Envision architecture.

Runtime Administration, March 10, 2010 419© 2010 Datatel, Inc.

Page 420: Envision Runtime Administration

Appendices: Form Reference

Remote Account New Files (UNFR)Use the Remote Account New Files (UNFR) form to review any new files that an account will receive when it is updated to a new release level.

Generally, you would use the Update Main Remote Accounts (UMRA) to update a Main account to a new release level. If you request UMRA to compile a list of any new files that the account will receive as it is updated, then you may review that list using this form. When you run UMRA and request to review this list, the UNFR form appears before Envision creates any files and updates the account in question. If the field for accepting the paths for the new files is not marked Yes, then Envision has not yet created the files. As long as the files have not yet been created, you can override the paths by entering the desired path in the field provided. When you continue or re-run UMRA and have marked the field Yes, Envision creates the files along the paths specified.

Because User remotes do not generally have local copies of true application files, you may update them through the Update User Remote Accounts (UURA) form. UURA does not produce a list of new files that you may view with this form.

For more information about the Update Main Remote Accounts (UMRA) form, refer to page 417.

Note: The Remote Account New Files (UNFR) form is not used for Envision 4.8 because of changes to the Envision architecture.

Note: The UMRA and UURA forms are not used for Envision 4.8 because of changes to the Envision architecture.

420 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 421: Envision Runtime Administration

Remote Account New Files (UNFR)

Figure 116: Sample Remote Account New Files (UNFR) Form

Table 44: Query Lang Retrieval Help for Remote Account New Files (UNFR) Form

Where Remote Account New Files (UNFR) Data Is StoredTo retrieve data from use this file and this field

Account LookUp REMOTES REMOTE.ID

[Account Description] REMOTES REMOTE.NAME

[Account Type] REMOTES REMOTE.TYPE

Account Path REMOTES REMOTE.PATH

New File Name REMOTES REMOTE.NEW.FILENAMES

New File Path REMOTES REMOTE.NEW.FILEPATHS

Obsolete Local Files for DELETION

REMOTES REMOTE.DELETED.FILES

Delete Exception REMOTES REMOTE.DELETED.EXCEPTIONS

Accept Paths as Presented REMOTES REMOTE.NEWFILE.ACCEPTANCE

Runtime Administration, March 10, 2010 421© 2010 Datatel, Inc.

Page 422: Envision Runtime Administration

Appendices: Form Reference

Overwritten & Deleted Records (UODR)Use the Overwritten & Deleted Records (UODR) form to produce a report that shows the lists of records that will be overwritten or deleted when you update an account to a new release level. The information in this report shows the names of the active lists and their contents. You may edit these lists to modify their contents and thus control which records are overwritten or deleted.

When you update a Main account to a new release level, certain obsolete records are targeted for deletion or replacement. A series of select lists controls which records to delete or replace; these select lists are delivered as part of the release package. The contents of these lists represent default modifications for updating the account.

You may modify the contents of these select lists to fit the needs of your institution. After using UODR to produce a report showing the names and default contents of these select lists, you can decide which records to add to or subtract from these lists to fit your institution’s needs. To protect items from deletion or replacement, remove them from the appropriate list using the EDIT.LIST command. To overwrite or delete your own records in User accounts during an update, use EDIT.LIST to add them to the lists.

Two select lists exist for each file or dictionary: one for deletion and one for replacement (overwriting).

Note: The Overwritten & Deleted Records (UODR) form is not used for Envision 4.8 because of changes to the Envision architecture.

422 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 423: Envision Runtime Administration

Overwritten & Deleted Records (UODR)

Figure 117: Sample Overwritten & Deleted Records (UODR) Form

Runtime Administration, March 10, 2010 423© 2010 Datatel, Inc.

Page 424: Envision Runtime Administration

Appendices: Form Reference

Remote Account Report (URRA)

Use the Remote Account Report (URRA) form to produce a report that lists information about your remote account definitions. You may use this report to review the structure of the various accounts defined to Envision.

With URRA, you may produce a report for any type of account:

Main

User

Release

File

Template image

The information provided in the report includes the directory path to an account, the modules it can access (Main, User, and Release accounts only), and other any other accounts that this account references.

Figure 118: Sample Remote Account Report (URRA) Form

Note: The Remote Account Report (URRA) form is not used for Envision 4.8 because of changes to the Envision architecture.

424 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 425: Envision Runtime Administration

Batch Error Report (UTBE)

Batch Error Report (UTBE)Use the Batch Error Report (UTBE) form to print information that Envision automatically collects and stores for a file when it runs a batch process. This information includes statistics, errors, and all records that it could not process. Not all batch jobs automatically print this report. If you need this information about a batch job but did not receive a report, use UTBE to print the needed information.

Envision stores these statistics in the file appl.PPROCESS, where appl is the mnemonic of the current application. This report prints only the information that you select.

When Envision runs a batch job, each step in the batch may produce one or more errors. You can view these error messages while the batch job is running, or use the VBS form to view them after the job runs.

UTBE gives you the option of producing printed copies of this information for one or more batch runs. You can print the Batch Error Report for a subset of the stored data. This form provides a way to create selection criteria for identifying the records you want printed.

Figure 119: Sample Batch Error Report (UTBE) Form

Runtime Administration, March 10, 2010 425© 2010 Datatel, Inc.

Page 426: Envision Runtime Administration

Appendices: Form Reference

Multiple File Indexing (UTBA)Use the Multiple File Indexing (UTBA) form to create and build index structures and to calculate computed index columns for multiple files.

Before you run the UTBA process for a file, the file must already have indexing parameters and specifications defined on either:

The File Index Definition (FIDX) form in the Envision Tool Kit

The User File Index Specification (UTMI) form (the runtime equivalent of FIDX)

As the UTBA process maintains the indexes of each selected file, a bar graph displays. Additionally, a second bar graph displays whenever a calculation of computed index columns occurs.

At the end of the process, UTBA generates a report that lists all executed file indexing operations for each file processed. For example, it will include a list of any index structures that may have been deleted, created, or built for each file.

Oracle Clients

In addition to the alternate key (IX_fieldname) indexes, the UTBA process verifies that the primary key (PK_filename) and unique key (UQ_filename) constraints are also defined using indexes. If the primary key and unique key are missing, the supporting indexes are created. This ensures that the records are unique and the performance of the database is optimal.

426 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 427: Envision Runtime Administration

Multiple File Indexing (UTBA)

Figure 120: Sample Multiple File Indexing (UTBA) Form

Runtime Administration, March 10, 2010 427© 2010 Datatel, Inc.

Page 428: Envision Runtime Administration

Appendices: Form Reference

File Indexing (UTBI)Use the File Indexing (UTBI) form to create and build index structures for a file and/or calculate any computed index columns of a file.

Before you run the UTBI process for a file, the file must already have indexing parameters and specifications defined on either:

The File Index Definition (FIDX) form in the Envision Tool Kit

The User File Index Specification (UTMI) form (the runtime equivalent of FIDX)

A 2-step bar graph displays as UTBI maintains indexes.

Step 1 represents the creation of index structures in Unidata accounts or the creation and build of index structures in Oracle accounts.

Step 2 represents the building of index structures in Unidata accounts. If a calculation of computed index columns occurs, it is represented during the second step with a secondary bar graph.

UTBI generates a report at the end of the process, which lists all of the executed file indexing operations. For example, it will include a list of any index structures that may have been deleted, created, or built.

For more information about the User File Index Specification (UTMI) form, refer to page 444.

Technical Tip: Oracle Clients -- In addition to the alternate key (IX_fieldname) indexes, the UTBI process verifies that the primary key (PK_filename) and unique key (UQ_filename) constraints are also defined using indexes. If the primary key and unique key constraints are missing, their supporting indexes are created. This ensures that the records are unique and that database performance is optimized.

428 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 429: Envision Runtime Administration

File Indexing (UTBI)

Figure 121: Sample File Indexing (UTBI) Form

Envision 4.7 only

Runtime Administration, March 10, 2010 429© 2010 Datatel, Inc.

Page 430: Envision Runtime Administration

Appendices: Form Reference

File Creation Type Defaults (UTCD)Use the File Creation Type Defaults (UTCD) form to set up default parameters to use when creating files. When you use a process that creates files and the information supplied is incomplete, Envision uses the default settings that you specify here to fill in any missing pieces.

The information is keyed by the type of file, and you can specify defaults to use for items such as the modulo or hash type. For more information about file types, see the on-line documentation for your operating system.

If the data on this form is also incomplete, the file creation routines default to hard-coded values. See each field description for these hard-coded default values.

Figure 122: Sample File Creation Type Defaults (UTCD) Form

430 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 431: Envision Runtime Administration

File Creation Type Defaults (UTCD)

Table 45: Query Lang Retrieval Help for File Creation Type Defaults (UTCD) Form

Where File Creation Type Defaults (UTCD) Data Is StoredTo retrieve data from use this file and this field

File Type FILEDFLT FILEDFLT.TYPE

Hashing FILEDFLT FILEDFLT.HASH

Modulo FILEDFLT FILEDFLT.MODULO

FILEDFLT.GRPSIZE FILEDFLT FILEDFLT.GRPSIZE

Unidata Account Group FILEDFLT FILEDFLT.UNIDATA.GROUP

Activate Dynamic FILEDFLT FILEDFLT.ACTIVATE.DYNAMIC

Runtime Administration, March 10, 2010 431© 2010 Datatel, Inc.

Page 432: Envision Runtime Administration

Appendices: Form Reference

File Creation (UTCF)To create a file when in the Envision runtime environment, you may use this form to entered information such as file name and target path, and then the file will be created for you.

Figure 123: Sample File Creation (UTCF) Form

Table 46: Query Lang Retrieval Help for File Creation (UTCF) Form

Where File Creation (UTCF) Data Is StoredTo retrieve data from use this file and this field

User File Specifications LookUp UFSPECS UFSPECS.ID

432 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 433: Envision Runtime Administration

UT Process Debug Activation (UTDB)

UT Process Debug Activation (UTDB)Use the UT Process Debug Activation (UTDB) form to activate or deactivate Envision debugging mode in a process. Activating debug mode for a process consists of the following steps:

1. Research the name of the debug string embedded in the program.

2. Enter the debug string on the UTDB form.

3. Run the Envision program you want to debug.

To make it possible for a program to run in debug mode, programmers embed a debug string (usually a process ID or form mnemonic) in the code of that program. The debug string is a unique name that identifies the program for the Envision debug processing. Programmers also create debug messages within the code. Envision displays these messages whenever you run the program in debug mode.

To determine whether Envision debug mode is active, programmers generally place Envision debug messages within a statement that checks for a value greater than zero in the special variables DATATEL.DEBUG and DATATEL.DEBUG.LEVEL.

ExampleIF DATATEL.DEBUG THEN

X.DB.CTR = X.DB.CTR + 1

XL.DEBUG.MSG<X.DB.CTR> = "entering special process, v.id = ":V.ID

IF DATATEL.DEBUG.LEVEL GE 5 THEN

X.DB.CTR = X.DB.CTR + 1

XL.DEBUG.MSG<X.DB.CTR> = "v.last.name =":V.LAST.NAME

END ;* datatel.debug.level ge 5

$INSERT I_DEBUG

END ;* datatel.debug

To turn on the Envision debug mode for a process, you enter the process's unique debug name into the appropriate fields on this form. The information you enter on this form is appended to special variable UT.DEBUG.STRING. The process continues to run in Envision debug mode for as long as you are logged into the current session, or until you use the Clear String fields to clear the debug string.

Runtime Administration, March 10, 2010 433© 2010 Datatel, Inc.

Page 434: Envision Runtime Administration

Appendices: Form Reference

When you enter a process’s debug name on the UTDB form, and then run the process needing debugging, the process runs in Envision debug mode. Envision Debug mode displays the messages entered by the programmers to help you determine possible sources of problems with the software or data.

Use the fields in the upper part of this form for debugging UI processes. Use the fields in the lower part of the form to debug WebAdvisor processes.

WebAdvisor processes follow the same concepts as Envision debug mode in UI. However, WebAdvisor debug mode remains active as long as the fields on this form contain data.

For WebAdvisor debugging, enter the name of the process and the ID of the WebAdvisor user you want to debug. As it runs, debug messages are written to the WWW.SCREEN.DEBUG files, which are keyed by SenderControlID*counter*SecurityToken*[processID].

Refer to the WebAdvisor Debug Information (WADB) form to view a report of records in the WWW.SCREEN.DEBUG file that were written during WebAdvisor debugging.

Figure 124: Sample UT Process Debug Activation (UTDB) Form

Envision 4.8

434 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 435: Envision Runtime Administration

Edit Comments (UTED)

Edit Comments (UTED)Use this form to view or maintain free-form comments. The type of comments you view or enter is defined by the context in which you are working. Therefore, this form is accessible only as a detail form. For example, if you accessed this form from the Vendor Maintenance (VEND) form in the Accounts Payable or Purchasing modules, you would do so to maintain comments about the vendor. If, on the other hand, you accessed this form from the Fixed Asset Disposal Maintenance (FXDM) form in the Fixed Assets module, you would do so to maintain comments on the disposal of a particular asset.

Figure 125: Sample Edit Comments (UTED) Form

Note: Regardless of the context in which you access this form, its mnemonic is always UTED. Because, however, you do access this form in a variety of contexts, its title changes to reflect the context in which you are working. You will never actually see this form’s formal title (Edit Comments). Instead, when you access this form from the Vendor Maintenance form, its title might be “Vendor Comments,” and when you access this form from the Fixed Asset Disposal Maint form, its title might be “Fixed Asset Disposal Comments.”

Runtime Administration, March 10, 2010 435© 2010 Datatel, Inc.

Page 436: Envision Runtime Administration

Appendices: Form Reference

BROWSE File Authorization (UTFA)Use the BROWSE File Authorization (UTFA) form to enter the names of all directories that end users are allowed to access using the BROWSE utility. End users can BROWSE only those directories that you specify by name on this form.

If you do not list any directories on this form, the only directory that end users can BROWSE is the HOLD directory, which contains generated reports.

End users might want to BROWSE some of the following directories:

Command logs

Documentation directories

Word processing directories

Vocabulary (VOC) records

It is possible for end users to delete the directories they access with BROWSE; therefore, do not allow them to access any directories that contain source code.

Figure 126: Sample Browse File Authorization (UTFA) Form

436 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 437: Envision Runtime Administration

BROWSE File Authorization (UTFA)

Table 47: Query Lang Retrieval Help for BROWSE File Authorization (UTFA) Form

Where BROWSE File Authorization (UTFA) Data Is StoredTo retrieve data from use this file and this field

Authorized Directory File Name UTFBLIST UTFB.AUTH.FILE.LIST

Runtime Administration, March 10, 2010 437© 2010 Datatel, Inc.

Page 438: Envision Runtime Administration

Appendices: Form Reference

Sequential File BROWSE Shell (UTFB)Use the Sequential File BROWSE Shell (UTFB) process to view items in a file directory. In the BROWSE process, the screen acts as a 22-line, 80-character window into a record. Each page of a directory item is 150 characters wide and 66 lines long. Use the BROWSE functions and commands to position your BROWSE window over part of the directory item.

Figure 127: Sample Sequential File BROWSE Shell (UTFB) Form

Note: This version of the form (containing Security Type) is available in Release 18.0 for Envision 4.8 only.

438 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 439: Envision Runtime Administration

Sequential File BROWSE Shell (UTFB)

The BROWSE functions and commands are as follows:

FunctionsWindow Page UP. Backs up one page (goes from page 3 to page 2)

Window Page DOWN.Turns to the next page

Window FWD. Moves down 22 lines or to the bottom of the current page

Window BACK. Moves up 22 lines or to the top of the current page

CLEAR or REFRESH. Repaints the current form

Process HELP. Shows this Help information

CANCEL, EXIT, or FINISH. Stops Browsing.

CommandsLnnn. Moves the BROWSE window to the left nnn columns

L. Moves the BROWSE window to the left 70 columns

Rnnn. Moves the BROWSE window to the right nnn columns

R. Moves the BROWSE window to the right 70 columns

Unnn. Moves the BROWSE window up nnn lines or to the top of the page

U. Moves the BROWSE window up 22 lines or to the top of the page

Dnnn. Moves the BROWSE window down nnn lines or to the bottom of the page

D. Moves the BROWSE window down 22 lines or to the bottom of the page

P. Moves to the next page

PD. Moves down (next) one page

PU. Moves up (prior) one page

Pnnn. Moves to page nnn

@(c,x). Moves the BROWSE window so that the upper left corner is positioned at column c, line x on the current page.

Runtime Administration, March 10, 2010 439© 2010 Datatel, Inc.

Page 440: Envision Runtime Administration

Appendices: Form Reference

Job Statistics Purge (UTJP)Use the Job Statistics Purge (UTJP) procedure to purge data that Envision automatically collects and stores when an end user runs a procedure. These data include the operator’s login ID and the date and time the procedure was run. It also includes the start time, stop time, and status for each process that the procedure runs.

Envision stores these statistics in the file appl.PPROCESS, where appl is the mnemonic for the current application. This purge process clears the file of the selected data.

You can purge either all or only a subset of the statistical data stored for a procedure. The Job Statistics User form provides a way to create selection criteria for identifying the statistics that you want to purge.

Figure 128: Sample Job Statistics Purge (UTJP) Form

Envision 4.8 only

440 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 441: Envision Runtime Administration

Job Statistics Report (UTJR)

Job Statistics Report (UTJR)Use the Job Statistics Report (UTJR) form to print data that Envision automatically collects and stores when an end user runs a procedure. These data include the operator name, date and time the procedure was run, and all records added, changed, or deleted for any files accessed during the process.

Envision stores these statistics in the file appl.PPROCESS, where appl is the mnemonic of the current application. This report prints the selected data for review or documentation.

You may run the Job Statistics Report for a subset of the stored data. You can create the selection criteria for identifying the statistics that you want to print. If you leave the selection options blank, Envision prints all records in the appl.PPROCESS file.

Figure 129: Sample Job Statistics Report (UTJR) Form

Runtime Administration, March 10, 2010 441© 2010 Datatel, Inc.

Page 442: Envision Runtime Administration

Appendices: Form Reference

User File Information (UTMF)Use the User File Information (UTMF) inquiry form to view system and account information about a specific file as identified to the operating system and database management software. Information includes characteristics of this file’s data and dictionary segments.

For more information about file types, see the file structure and file maintenance sections of the reference guide for your operating system.

Figure 130: Sample User File Information (UTMF) Form

442 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 443: Envision Runtime Administration

User File Information (UTMF)

Table 48: Query Lang Retrieval Help for User File Information (UTMF) Form

Where User File Information (UTMF) Data Is StoredTo retrieve data from use this file and this field

File Name LookUp UT.VOC UT.VOC.ID

Description UT.VOC UT.VOC.DESCRIPTION

Accessed by Module(s) UT.VOC UT.VOC.RELEASE.MODULES

Account Access List UT.VOC UT.VOC.REMOTE.XREF

Changed Date UT.VOC UT.VOC.CHANGE.DATE

Operator UT.VOC UT.VOC.CHANGE.OPERATOR

Runtime Administration, March 10, 2010 443© 2010 Datatel, Inc.

Page 444: Envision Runtime Administration

Appendices: Form Reference

User File Index Specification (UTMI)Use the User File Index Specification (UTMI) form to define lists of field associations by which to index a file. These index specifications work in addition to the indexing that the application designer defined through the File Index Definition (FIDX) form in the Envision Tool Kit. UTMI is the runtime equivalent of FIDX.

Indexing speeds up some file operations, such as selecting all records in a file whose field(s) match certain value(s). For example, using LookUp on a file containing only indexed fields is much faster than using it on a file containing unindexed fields.

Envision stores these index specifications as records in an index file (in Envision 4.7 only). In addition to specifying which fields in the primary file you want to index, you can specify which field you want to store as the key for these specifications. By default, this field is the ID of the primary file. You can also specify any key algorithm that you want to use to generate index keys in the index file.

For more information about the File Indexing (UTBI) form, refer to page 428.

Note: After using the UTMI process to specify indexing, use the File Indexing (UTBI) form to build the indexing information for any currently existing data in the file.

444 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 445: Envision Runtime Administration

User File Index Specification (UTMI)

Figure 131: Sample User File Index Definition (UTMI) Form

Table 49: Query Lang Retrieval Help for User File Index Specification (UTMI) Form

Where User File Index Specification (UTMI) Data Is StoredTo retrieve data from use this file and this field

User File Specifications LookUp UFSPECS UFSPECS.ID

Runtime Administration, March 10, 2010 445© 2010 Datatel, Inc.

Page 446: Envision Runtime Administration

Appendices: Form Reference

Transaction Log Specification (UTML)Use the Transaction Log Specification (UTML) form to activate or deactivate transaction logging for a specific file. You can activate transaction logging for a specific period of time by indicating the date to automatically turn the logging feature off.

The transaction log file for a given file is named TXLOG_filename. Envision creates this file in the same directory as the file that is being logged.

Figure 132: Sample Transaction Log Specification (UTML) Form

446 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 447: Envision Runtime Administration

Transaction Log Specification (UTML)

Table 50: Query Lang Retrieval Help for Transaction Log Specification (UTML) Form

Where Transaction Log Specification (UTML) Data Is StoredTo retrieve data from use this file and this field

User File Specifications LookUp UFSPECS UFSPECS.ID

Date to stop Transaction Logging

UFSPECS UFSPECS.TX.LOG.EXP.DATE

Date UFSPECS UFSPECS.TX.LOG.DATE

Time UFSPECS UFSPECS.TX.LOG.TIME

Operator UFSPECS UFSPECS.TX.LOG.OPER

Action UFSPECS UFSPECS.TX.LOG.ACTION

Runtime Administration, March 10, 2010 447© 2010 Datatel, Inc.

Page 448: Envision Runtime Administration

Appendices: Form Reference

Record Security Specification (UTMR)Use the Record Security Specification (UTMR) form to specify the criteria that define access security for records within a specific file. When end users run an application, Envision evaluates their parameter definitions set up in the Record Security User Characteristics (RSUC) form. Envision evaluates the criteria specified on this form during runtime against an end user’s security cha6acteristics to determine if he has access to a certain record for reporting or maintenance.

If you add new record security criteria or change existing criteria for end users, they must re-initialize Envision Runtime before the additions or changes take effect. There are two ways to initialize Envision Runtime:

Leave the database management system and reenter it, or

Enter ENVINIT at the database management system prompt.

For more information about the Record Security User Characteristics (RSUC) form, refer to page 372.

Figure 133: Sample Record Security Specification (UTMR) Form

448 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 449: Envision Runtime Administration

Remote Account Specifications (UTRA)

Remote Account Specifications (UTRA)Use the Remote Account Specifications (UTRA) form to maintain the REMOTES file. Each record in the REMOTES file contains descriptive information about a particular remote account.

The Key IDs of records in the REMOTES file should be the same as their corresponding account names. Each record also contains the full path name that explicitly defines the physical location of the VOC for the remote account it describes.

Table 51: Query Lang Retrieval Help for Record Security Specification (UTMR) Form

Where Record Security Specification (UTMR) Data Is StoredTo retrieve data from use this file and this field

FileName LookUp UFSPECS UFSPECS.ID

Last Changed Date UFSPECS UFSPECS.RS.CHG.DATE

Last Changed By UFSPECS UFSPECS.RS.CHG.OPER

Select FileName UFSPECS UFSPECS.RS.FILENAME

Connective UFSPECS UFSPECS.RS.CONNECTIVE

Field Name UFSPECS UFSPECS.RS.SEL.FIELD

Relation UFSPECS UFSPECS.RS.REL.OPCODE

Conditional Value UFSPECS UFSPECS.RS.SEL.VALUE

Access Class UFSPECS UFSPECS.RS.ACCESS.TYPE

Enforce current security definition?

UFSPECS UFSPECS.RCD.SECURITY

Note: The Remote Account Specifications (UTRA) form is not used for Envision 4.8 because of changes to the Envision architecture.

Runtime Administration, March 10, 2010 449© 2010 Datatel, Inc.

Page 450: Envision Runtime Administration

Appendices: Form Reference

Figure 134: Sample Remote Account Specifications (UTRA) Form

450 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 451: Envision Runtime Administration

Remote Account Specifications (UTRA)

Table 52: Query Lang Retrieval Help for Remote Account Specifications (UTRA) Form

Where Remote Account Specifications (UTRA) Data Is StoredTo retrieve data from use this file and this field

Account LookUp REMOTES REMOTE.ID

Account Type REMOTES REMOTE.TYPE

Account Description REMOTES REMOTE.NAME

Drive Name For VOC REMOTES REMOTE.DRIVE

Full Path For VOC REMOTES REMOTE.PATH

Parent VOC REMOTES REMOTE.REMOTE.LIST

Application REMOTES REMOTE.APPL.LIST

Modules REMOTES REMOTE.MODULE.LIST

User REMOTES REMOTE.MAIN.OVERRIDE

Release REMOTES REMOTE.VERSION.REL

Global REMOTES REMOTE.CATALOG.TYPE

Default DATA Filing Area REMOTES REMOTE.DFLT.FILING.AREA

Default SYSTEM Filing Area REMOTES REMOTE.SYSTEM.FILING.AREA

Runtime Administration, March 10, 2010 451© 2010 Datatel, Inc.

Page 452: Envision Runtime Administration

Appendices: Form Reference

LookUp Resolution Specs (UTRD)A resolution form is where the results of a LookUp are displayed when more than one record in a selected file meets specified selection criteria. The resolution page allows users to search through a list of records and choose one or more, as needed. Use the LookUp Resolution form to specify the content and layout of a resolution form. When you create new specifications or modify existing ones, the changes must be compiled.

Use the LookUp Resolution Specifications (UTRD) form to maintain a LookUp Resolution specification by entering or editing details such as the name of the resolution file, maximum lines for the resolution block, resolution title, resolution details such as the line and column numbers, length, justification, and conversion. In essence, you will supply all of the basic details required to maintain a resolution specification definition.

Figure 135: Sample LookUp Resolution Specs (UTRD) Form

Displays the login ID of the person who most recently changed this resolution form.

452 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 453: Envision Runtime Administration

File Resolution Defaults (UTRE)

File Resolution Defaults (UTRE)Use the File Resolution Defaults (UTRE) form to specify abbreviations to use in place of dictionary item names. If you specify abbreviations here, Envision lets you refer to those fields by their abbreviations when using LookUp. You may also use this form to define the default sort order for the resolution form.

Table 53: Query Lang Retrieval Help for LookUp Resolution Specs (UTRD) Form

Where LookUp Resolution Specs (UTRD) Data Is StoredTo retrieve data from use this file and this field

Resolution LookUp RESOLUTN RESOLUTN.ID

Resolution File RESOLUTN RESOLUTN.FNAME

Maximum Lines RESOLUTN RESOLUTN.MAX.LINES

Description RESOLUTN RESOLUTN.DESCRIPTION

Key Subroutine RESOLUTN RESOLUTN.KEY.SUBR

Line RESOLUTN RESOLUTN.LINE

Column RESOLUTN RESOLUTN.COL

Length RESOLUTN RESOLUTN.LGTH

Justification RESOLUTN RESOLUTN.JST

Block Definition RESOLUTN RESOLUTN.BLK.DATA

Conversion RESOLUTN RESOLUTN.CONV

[Character ID] RESOLUTN RESOLUTN.BLK.ID

Block Header RESOLUTN RESOLUTN.BLK.HEADER

Added [on] RESOLUTN RESOLUTN.ADDED

Added [by] RESOLUTN RESOLUTN.ADDED.BY

Changed [on] RESOLUTN RESOLUTN.CHANGED

Changed [by] RESOLUTN RESOLUTN.CHANGED.BY

Runtime Administration, March 10, 2010 453© 2010 Datatel, Inc.

Page 454: Envision Runtime Administration

Appendices: Form Reference

Figure 136: Sample File Resolution Defaults (UTRE) Form

454 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 455: Envision Runtime Administration

File Resolution Defaults (UTRE)

Table 54: Query Lang Retrieval Help for File Resolution Defaults (UTRE) Form

Where File Resolution Defaults (UTRE) Data Is StoredTo retrieve data from use this file and this field

Resolution LookUp RESOLUTN RESOLUTN.ID

Resolution File RESOLUTN RESOLUTN.FNAME

Maximum Lines RESOLUTN RESOLUTN.MAX.LINES

Description RESOLUTN RESOLUTN.DESCRIPTION

Added [on] RESOLUTN RESOLUTN.ADDED

Added [by] RESOLUTN RESOLUTN.ADDED.BY

Changed [on] RESOLUTN RESOLUTN.CHANGED

Changed [by] RESOLUTN RESOLUTN.CHANGED.BY

Only Allow Table Items RESOLUTN RESOLUTN.LIMIT.ITEMS

Item RESOLUTN RESOLUTN.DICT.MNEMONIC

Dictionary Name RESOLUTN RESOLUTN.DICT.NAME

Sort Field RESOLUTN RESOLUTN.SORT.FIELD

Sort Order RESOLUTN RESOLUTN.SORT.ORDER

Runtime Administration, March 10, 2010 455© 2010 Datatel, Inc.

Page 456: Envision Runtime Administration

Appendices: Form Reference

File Resolve Graphic Display (UTRG)Use the File Resolve Graphic Display (UTRG) form to specify both the main and column headings that appear when Envision evaluates and displays this resolution. This form also lets you review the current format and placement of the display attributes.

For a more accurate definition of headings, especially in the client/server environment, you should also include headings for each field on the UTRD form.

Figure 137: Sample File Resolve Graphic Display (UTRG) Form

456 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 457: Envision Runtime Administration

File Resolve Graphic Display (UTRG)

Table 55: Query Lang Retrieval Help for File Resolve Graphic Display (UTRG) Form

Where File Resolve Graphic Display (UTRG) Data Is StoredTo retrieve data from use this file and this field

Resolution LookUp RESOLUTN RESOLUTN.ID

Resolution File RESOLUTN RESOLUTN.FNAME

Maximum Lines RESOLUTN RESOLUTN.MAX.LINES

Description RESOLUTN RESOLUTN.DESCRIPTION

Added [on] RESOLUTN RESOLUTN.ADDED

Added [by] RESOLUTN RESOLUTN.ADDED.BY

Changed [on] RESOLUTN RESOLUTN.CHANGED

Changed [by] RESOLUTN RESOLUTN.CHANGED.BY

Resolution Title RESOLUTN RESOLUTN.TITLE

[Heading] RESOLUTN RESOLUTN.HEADING

Runtime Administration, March 10, 2010 457© 2010 Datatel, Inc.

Page 458: Envision Runtime Administration

Appendices: Form Reference

LookUp Resolution Options (UTRO)Use the LookUp Resolution Options (UTRO) form to control miscellaneous resolution form options that affect the form’s operation, but not its appearance. These options include controlling when Envision invokes the resolution form and what an end user’s options are at that time.

Use the File Resolve Graphic Display (UTRG) detail form to change the appearance of the resolution data on the resolution form.

For more information about the File Resolve Graphic Display (UTRG) form, refer to page 456.

Figure 138: Sample LookUp Resolution Options (UTRO) Form

458 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 459: Envision Runtime Administration

LookUp Resolution Options (UTRO)

Table 56: Query Lang Retrieval Help for LookUp Resolution Options (UTRO) Form

Where LookUp Resolution Options (UTRO) Data Is StoredTo retrieve data from use this file and this field

Resolution LookUp RESOLUTN RESOLUTN.ID

Added [on] RESOLUTN RESOLUTN.ADDED

Added [by] RESOLUTN RESOLUTN.ADDED.BY

Changed [on] RESOLUTN RESOLUTN.CHANGED

Changed [by] RESOLUTN RESOLUTN.CHANGED.BY

Resolution File RESOLUTN RESOLUTN.FNAME

Maximum Lines RESOLUTN RESOLUTN.MAX.LINES

Description RESOLUTN RESOLUTN.DESCRIPTION

Single Hit Requires Resolution RESOLUTN RESOLUTN.SINGLE.HIT

Key List Conversion Subroutine RESOLUTN RESOLUTN.LIST.SUBR

Issue a Warning on File Selects RESOLUTN RESOLUTN.SELECT.FILE.PROMPT

Resolution Form RESOLUTN RESOLUTN.FORM

Suppress/Override New Key Message

RESOLUTN RESOLUTN.SUPPRESS.NEW.MSG

Runtime Administration, March 10, 2010 459© 2010 Datatel, Inc.

Page 460: Envision Runtime Administration

Appendices: Form Reference

ReRun a Procedure (UTRR)Use the Rerun a Procedure (UTRR) form to retrieve a previously run procedure. When you retrieve a previously run procedure, you can examine the actual statements that Envision created to run it. You may then choose to run the procedure again.

Figure 139: Sample ReRun a Procedure (UTRR) Form

460 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 461: Envision Runtime Administration

User FileSuite Information (UTSF)

User FileSuite Information (UTSF)To display some basic information about a data and dictionary file as viewed through the current account VOC file use this form. After supplying a file name you will be presented with information describing such information as file type and modulo as well as physical path to both the data and dictionary portions of the file.

None of this information may be changed here, it is only for display.

Figure 140: Sample User FileSuite Information (UTSF) Form

Runtime Administration, March 10, 2010 461© 2010 Datatel, Inc.

Page 462: Envision Runtime Administration

Appendices: Form Reference

Table 57: Query Lang Retrieval Help for User FileSuite Information (UTSF) Form

Where User FileSuite Information (UTSF) Data Is StoredTo retrieve data from use this file and this field

User File Specifications LookUp UFSPECS UFSPECS.ID

Physical File Description UFSPECS UFSPECS.DESCRIPTION

Physical Dictionary Name UFSPECS UFSPECS.DICT.NAME

UFSPECS.TS.FLAG UFSPECS UFSPECS.TS.FLAG

Template ID UFSPECS UFSPECS.TEMPLATE.ID

UFSPECS.SUITE.ID.LIST UFSPECS UFSPECS.SUITE.ID.LIST

Changed On UFSPECS CHANGE.DATE

Changed By UFSPECS CHANGE.OPERATOR

462 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 463: Envision Runtime Administration

Set Printer Characteristics (UTSP)

Set Printer Characteristics (UTSP)Use the Set Printer Characteristics (UTSP) form to modify the characteristics of the printer that is associated with your Envision session. It supplies all of the SETPTR command services without having to leave the Envision environment.

Figure 141: Sample Set Printer Characteristics (UTSP) Form

Runtime Administration, March 10, 2010 463© 2010 Datatel, Inc.

Page 464: Envision Runtime Administration

Appendices: Form Reference

TXLOG Purge (UTTP)Use the TXLOG Purge (UTTP) procedure to purge data that is automatically collected and stored for a file that has transaction logging turned on. These data include the operator’s login ID and the date and time the transaction was created. Transaction data include all records added, changed, or deleted within the file. Envision stores transaction data in the log file TX_filename. This purge process clears the transaction log file of the selected data.

Use the Transaction Log Specification (UTML) form to turn transaction logging on and off.

Use this form to purge logged transactions on a subset of the stored data. You can specify selection criteria for identifying the statistics that you want to purge. If you leave the selection options blank, Envision purges all records in the selected file.

For more information about the Transaction Log Specification (UTML) form, refer to page 446.

Figure 142: Sample TXLOG Purge (UTTP) Form

464 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 465: Envision Runtime Administration

Modify Appl VOC Files (UTVF)

Modify Appl VOC Files (UTVF)Use the Modify Application VOC Files (UTVF) form to identify characteristics associated with all files in the current application. Each file contains enough information to build file pointers in remote accounts and create files in new accounts when required.

You only need to use this form if you want the Update Main Remote Accounts (UMRA) or Update User Remote Accounts (UURA) processes to update files that are specific to your institution along with Datatel files during the remote account update process. Normally, UMRA and UURA automatically update Datatel files for a new release.

Figure 143: Sample Modify Appl VOC Files (UTVF) Form

Note: The UMRA and UURA forms are not used for Envision 4.8 because of changes to the Envision architecture.

Runtime Administration, March 10, 2010 465© 2010 Datatel, Inc.

Page 466: Envision Runtime Administration

Appendices: Form Reference

Modify Appl VOC Misc. Items (UTVM)The Modify Application VOC Miscellaneous Items (UTVM) form lets you enter information about a miscellaneous VOC entry used within an application. The record is used to write data to the VOC file on remote accounts or new accounts.

A miscellaneous VOC item is any valid VOC item that is not a program or a file. Valid miscellaneous VOC items include the following types:

K. keywords

M. menus

PA. paragraphs

S. sentences

V. verbs that are not programs

X. user VOC items

Use the Modify Application VOC Programs (UTVP) form to modify program VOC items. Use the Modify Application VOC Files (UTVF) form to modify file VOC items.

For more information about the Modify Application VOC Programs (UTVP) form, refer to page 468.

Table 58: Query Lang Retrieval Help for Modify Appl VOC Files (UTVF) Form

Where Modify Appl VOC Files (UTVF) Data Is StoredTo retrieve data from use this file and this field

Application VOC Key UT.VOC UT.VOC.ID

Alias File Names UT.VOC UT.VOC.SYNONYM.NAMES

Affected Modules UT.VOC UT.VOC.RELEASE.MODULES

Number UT.VOC UT.VOC.RELEASE

Action UT.VOC UT.VOC.RELEASE.ACTION

Purpose UT.VOC UT.VOC.DESCRIPTION

Data Create Area UT.VOC UT.VOC.FILE.CREATE.REMOTE

Data Create Modulo UT.VOC UT.VOC.FILE.MODULO

Dict Create Area UT.VOC UT.VOC.DICT.CREATE.REMOTE

Dict Create Modulo UT.VOC UT.VOC.DICT.MODULO

466 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 467: Envision Runtime Administration

Modify Appl VOC Misc. Items (UTVM)

For more information about the Modify Application VOC Files (UTVF) form, refer to page 465.

Figure 144: Sample Modify Appl VOC Misc. Items (UTVM) Form

Table 59: Query Lang Retrieval Help for Modify Appl VOC Misc. Items (UTVM) Form

Where Modify Appl VOC Misc. Items (UTVM) Data Is StoredTo retrieve data from use this file and this field

Application VOC Key UT.VOC UT.VOC.ID

Purpose UT.VOC UT.VOC.DESCRIPTION

Affected Modules UT.VOC UT.VOC.RELEASE.MODULES

Number UT.VOC UT.VOC.RELEASE

Action UT.VOC UT.VOC.RELEASE.ACTION

Overwrite VOC Item UT.VOC UT.VOC.OVERWRITE

VOC Image Type UT.VOC UT.VOC.IMAGE.TYPE

VOC Record Image UT.VOC UT.VOC.IMAGE

Runtime Administration, March 10, 2010 467© 2010 Datatel, Inc.

Page 468: Envision Runtime Administration

Appendices: Form Reference

Modify Appl VOC Programs (UTVP)Use the Modify Application VOC Programs (UTVP) form to identify any custom programs not included with a Datatel release that you would like to include in automatic updates of remotes from this account. The records are used to build the appropriate VOC entries on remote accounts and new accounts.

Figure 145: Sample Modify Appl VOC Programs (UTVP) Form

468 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 469: Envision Runtime Administration

Modify Appl VOC Programs (UTVP)

Table 60: Query Lang Retrieval Help for Modify Appl VOC Programs (UTVP) Form

Where Modify Appl VOC Programs (UTVP) Data Is StoredTo retrieve data from use this file and this field

Application VOC Key UT.VOC UT.VOC.ID

Purpose UT.VOC UT.VOC.DESCRIPTION

Affected Modules UT.VOC UT.VOC.RELEASE.MODULES

Number UT.VOC UT.VOC.RELEASE

Action UT.VOC UT.VOC.RELEASE.ACTION

Alias Program Name UT.VOC UT.VOC.SYNONYM.NAMES

Source File Name UT.VOC UT.VOC.FILE.NAME

Catalog Disposition UT.VOC UT.VOC.PROGRAM.CATALOG

Catalog Override Stem UT.VOC UT.VOC.CATSTEM.OVERRIDE

Runtime Administration, March 10, 2010 469© 2010 Datatel, Inc.

Page 470: Envision Runtime Administration

Appendices: Form Reference

Audit Trail Report (UTXL)Use the Audit Trail Report (UTXL) procedure to print data automatically collected and stored for a file that has transaction logging turned on. These data include the operator’s login ID and the date and time the transaction was created. Transactions include all records added, changed, or deleted within the file. Envision stores transaction data in the file TX_filename. This print process prints the transaction log file for the selected data.

Use the Transaction Log Specification (UTML) form to turn transaction logging on and off.

For more information about the TXLOG Purge (UTTP) form, refer to page 464.

Note: This form is identical to the TXLOG Purge (UTTP) form. The only difference between the two forms is that UTTP purges transaction data, while UTXL prints transaction data.

470 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 471: Envision Runtime Administration

Update User Remote Accounts (UURA)

Update User Remote Accounts (UURA)Use the Update User Remote Accounts (UURA) form to specify User remote accounts that you want to update to a particular release level. User remote accounts are accounts that point to a Main account for data and point indirectly to the same versions of programs to which the Main account points. On the UURA form, you can enter a list of one or more IDs of REMOTES records for updating. All records are updated in a single run suitable for background mode processing.

You cannot update Main accounts from UURA. Unlike the Update Main Remote Accounts (UMRA) form, UURA does not make a list of new and obsolete files for you to review. It uses the default paths for a given remote account on the assumption that you have few, if any, new local files with non-standard paths. If this is a problem, you can use UMRA. While intended for Main accounts, UMRA may be used to update User accounts as well.

On the Update User Remote Accounts (UURA) form, you may enter a list of one or more REMOTES record IDs for updating. The REMOTES records used in the remote update process define four things:

1. the path to the VOC of a User account that you want to update

2. the source (Release) REMOTES record containing the release in question

3. application and module names to include in the update

4. the path to system and data filing areas (if used)

UURA accepts any User account REMOTES definitions and updates them in the order presented on this form. To define REMOTES records, use the Remote Account Specifications (UTRA) form.

For more information about the Remote Account Specifications (UTRA) form, refer to page 449.

Note: The Update User Remote Accounts (UURA) form is not used for Envision 4.8 because of changes to the Envision architecture.

Runtime Administration, March 10, 2010 471© 2010 Datatel, Inc.

Page 472: Envision Runtime Administration

Appendices: Form Reference

Figure 146: Sample Update User Remote Accounts (UURA) Form

472 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 473: Envision Runtime Administration

Validation Codes (VAL)

Validation Codes (VAL)Use the Validation Code Maintenance (VAL) form to view or modify any validation table for a specific application. Validation tables list the entries that are valid for a specific field, along with a short description for each entry. Envision uses validation tables to ensure data integrity by limiting entries for certain fields to the codes defined in the table. If an end user attempts to enter a code that does not match any of the codes in the validation table for the field, Envision displays an error message.

The file appl.VALCODES contains all of the validation tables for an application. Each table has a unique key, based on the name of the data element with which it is used. However, one validation table can be used to validate many data elements. Each table consists of a set of validation codes, their corresponding descriptions, and other processing parameters.

If you are allowed to update a validation code table, you can use this form to modify your codes. Some validation table files for an application contain tables that you can customize to meet your institution’s unique needs.

Validation tables also serve as translation tables. Translation tables provide standard descriptions for validated data fields. Envision uses the descriptions on this form as standard descriptions for all data fields that reference the associated validation tables.

You can disable some validation tables so that end users may enter anything. To disable a validation table, enter three asterisks (***) as the first code in the code field and delete all of the remaining codes.

Runtime Administration, March 10, 2010 473© 2010 Datatel, Inc.

Page 474: Envision Runtime Administration

Appendices: Form Reference

Figure 147: Sample Validation Codes (VAL) Form

474 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 475: Envision Runtime Administration

Validation Codes (VAL)

Table 61: Query Lang Retrieval Help for Validation Codes (VAL) Form

Where Validation Codes (VAL) Data Is StoredTo retrieve data from use this file and this field

Validation Code ID VALCODES VALCODE.ID

Created On VALCODES VALCODES.ADD.DATE

Created By VALCODES VALCODES.ADD.OPERATOR

Changed On VALCODES VALCODES.CHANGE.DATE

Changed By VALCODES VALCODES.CHANGE.OPERATOR

Code VALCODES VAL.INTERNAL.CODE

Description VALCODES VAL.EXTERNAL.REPRESENTATION

Min Entry VALCODES VAL.MINIMUM.INPUT.STRING

Special Action Code 1 VALCODES VAL.ACTION.CODE.1

Special Action Code 2 VALCODES VAL.ACTION.CODE.2

Purpose VALCODES VAL.PURPOSE

Maximum Code Size VALCODES VAL.CODE.LENGTH

Zero Fill Numbers (Y/N) VALCODES VAL.ZERO.FILL

Runtime Administration, March 10, 2010 475© 2010 Datatel, Inc.

Page 476: Envision Runtime Administration

Appendices: Form Reference

View Batch Process Status (VBS)Use the View Batch Process Status (VBS) form to monitor a batch process run from another port. You may also use it to view the status of a completed batch process. The form shows each stage of the job, the number of records processed and remaining, the elapsed time, the time remaining, and the number of errors. You can review the error text and additional details for each stage of the job on the View Single Batch Job Step (VBSD) form. The detail form also shows you the last record read.

Envision keys a batch process by concatenating the process mnemonic with the end user’s login ID, followed by the time and date that the end user selected the mnemonic. Envision separates each part of this key with an underline character (_).

Figure 148: Sample View Batch Process Status (VBS) Form

476 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 477: Envision Runtime Administration

View Batch Process Status (VBS)

Table 62: Query Lang Retrieval Help for View Batch Process Status (VBS) Form

Where View Batch Process Status (VBS) Data Is StoredTo retrieve data from use this file and this field

Job Start Time JOBSTATS JOB.START.TIME

Process JOBSTATS JOB.STEP.NAMES

Status JOBSTATS STEP.STATUS

Records Done JOBSTATS RECORDS.PROCESSED

Errors JOBSTATS STEP.ERROR.COUNT

Runtime Administration, March 10, 2010 477© 2010 Datatel, Inc.

Page 478: Envision Runtime Administration

Appendices: Form Reference

View Single Batch Job Step (VBSD)The View Single Batch Job Step (VBSD) form is an extension of the View Batch Status (VBS) form. Detail from a specific job step in VBS to view the VBSD form. It gives information on any errors that occurred on that job step. VBSD is an inquiry-only form, and you can access it only as a detail form from the VBS form.

Figure 149: Sample View Single Batch Job Step (VBSD) Form

478 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 479: Envision Runtime Administration

View Single Batch Job Step (VBSD)

Table 63: Query Lang Retrieval Help for View Single Batch Job Step (VBSD) Form

Where View Single Batch Job Step (VBSD) Data Is StoredTo retrieve data from use this file and this field

Process ID JOBSTATS JOB.STEP.NAMES

Status JOBSTATS STEP.STATUS

Last ID Read JOBSTATS STEP.MOST.RECENT.KEY

Error Count JOBSTATS STEP.ERROR.COUNT

Total Records to Process JOBSTATS RECORDS.TO.PROCESS

Already Processed JOBSTATS RECORDS.PROCESSED

Time Started JOBSTATS STEP.START.TIME

Time Elapsed JOBSTATS STEP.END.TIME

Runtime Administration, March 10, 2010 479© 2010 Datatel, Inc.

Page 480: Envision Runtime Administration

Appendices: Form Reference

480 Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 481: Envision Runtime Administration

Index

From this index you can click on any entry to access the information about the topic.

AACCOUNT.PARAMETERS

System Parameters 55

ACSO form 304

Action Checked Out Studio Obj (ACSO) form 304

appl.PPROCESS file 440

Application hierarchyand screen chains 123

Audit Trail Report (UTXL) form 470

Automatically generated services 279

BBatch Error Report (UTBE) form 425

Batch Runtime RFSPECS Refresh (BRRR) form 226

BROWSE File Authorization (UTFA) form 436

BRRR form 226

BSEC form 177

BTRR form 305

Build Application Security (BSEC) form 177

CCC Reset for SQL Server (CCRS) form 308

CCLD form 306

CCND form 307

CCRS form 308

CCSR form 310

CDEC form 312

CDED form 314

CDOB form 316

CDPI form 318

Chain Usage Report (CHUS) 129

Chain Usage Report (CHUS) form 319

Change Peripheral Defaults (CPDE) form 320

CHUS form 319

Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Colleague modulesDefining parameter records for 55

Computed Column Library Dply (CCLD) form 306

Computed Columns Not Deployed (CCND) form 307

Concepts 21

CONFIRM level 263

CPAE form 86

CPDE form 320

CPIE form 322

CPKG form 324

CPKP form 326

CPKR form 328

CPRP form 330

Create Printer Control Record (CPRP) form 330

CUSC form 331

Custom Code Scanner (CUSC) form 331

Custom Declaration (CDEC) form 312

Custom Declaration Objects (CDOB) form 316

Custom Development in Progress (CDPI) form 318

Custom Package Import/Export (CPIE) form 322

Custom Package Rebuild Detail (CPKR) form 328

Custom Packaging Detail (CDED) form 314

Custom Paragraph Entry (CPAE) form 86

Custom Release Package Build (CPKG) form 324

Custom Release Package Build (CPKP) form 326

Custom Scanner Report (CCSR) form 310

DDDCV form 333

Define Cursor Keys (SKB2) form 397

Define Field History (DHST) form 335

Define Function Keys (SKB1) form 394

Define Key Functions (RS2) form 371

Define Terminal Keyboard (SKB) form 392

481

Page 482: Envision Runtime Administration

Index

Delete Obsolete Index Files (DOIF) form 234

Device Definition (SDD) form 388

DHST form 335

Dictionary Date Convert (DDCV) form 333

DIFF form 336

Difference Engine (DIFF) form 336

DOIF form 234

EEdit Comments (UTED) form 435

Edit Record (EDRC) form 337

EDRC form 337

EGP (External Global Parameters) 337

Element, Window 30

Envision Parameters Edit (EPED) form 55, 231

EPED form 55, 231

External Global Parameters (EGP) 337

FFHDF form 340

FHDT form 340

Field History Detail (FHDT) form 340

Field Label 30

Field Security Definition (SCDF) form 379

File Creation (UTCF) form 432

File Creation Type Defaults (UTCD) form 430

File indexing 222database 226

when conversion is complete 234

File Resolution Defaults (UTRE) form 453

File Resolve Graphic Display (UTRG) form 456

FilesACCOUNT.PARAMETERS 55appl.PPROCESS 440converting static to dynamic 196resizing 194SYSDEFS 67UT.THROWN.ERRORS 263

Forms, Datatel softwareAction Checked Out Studio Obj (ACSO) 304Audit Trail Report (UTXL) 470Batch Error Report (UTBE) 425Batch Runtime RFSPECS Refresh (BRRR) 226

482

Forms, Datatel software (cont’d)BROWSE File Authorization (UTFA) 436Build Application Security (BSEC) 177CC Reset for SQL Server (CCRS) 308Chain Usage Report (CHUS) 319Change Peripheral Defaults (CPDE) 320Computed Column Library Dply (CCLD) 306Computed Columns Not Deployed (CCND) 307Create Printer Control Record (CPRP) 330Custom Code Scanner (CUSC) 331Custom Declaration (CDEC) 312Custom Declaration Objects (CDOB) 316Custom Development in Progress (CDPI) 318Custom Package Import/Export (CPIE) 322Custom Package Rebuild Detail (CPKR) 328Custom Packaging Detail (CDED) 314Custom Paragraph Entry (CPAE) 86Custom Release Package Build (CPKG) 324Custom Release Package Build (CPKP) 326Custom Scanner Report (CCSR) 310Define Cursor Keys (SKB2) 397Define Field History (DHST) 335Define Function Keys (SKB1) 394Define Key Functions (RS2) 371Define Terminal Keyboard (SKB) 392Delete Obsolete Index Files (DOIF) 234Device Definition (SDD) 388Dictionary Date Convert (DDCV) 333Difference Engine (DIFF) 336Edit Comments (UTED) 435Edit Record (EDRC) 337Envision Parameters Edit (EPED) 55, 231Field History Detail (FHDT) 340Field Security Definition (SCDF) 379File Creation (UTCF) 432File Creation Type Defaults (UTCD) 430File Resolution Defaults (UTRE) 453File Resolve Graphic Display (UTRG) 456GUI Function Button (GUIF) 342International Parameters (INTL) 343Job Statistics Purge (UTJP) 440Job Statistics Report (UTJR) 441LKUP Resolution Specs (LPRT) 356LookUp Resolution Options (UTRO) 458LookUp Resolution Specs (UTRD) 452Menu Definition (SMD) 401Migrate Computed Columns (MGCC) 357Migrate IS-Type Subroutines (MGIS) 358Modify Appl VOC Files (UTVF) 465Modify Appl VOC Misc. Items (UTVM) 466Modify Appl VOC Programs (UTVP) 468

Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 483: Envision Runtime Administration

Index

Forms, Datatel software (cont’d)Multiple File Indexing (UTBA) 233, 426My Processes (MYPR) 102Network Definition (SND) 407Operator Definition (SOD) 409Operator Security Report (SCOR) 383Other Technical Documentation (ODOC) 359Output Security Groups (OSGD) 146Outstanding Processes (OPRM) 95Outstanding Processes Inquiry (OPRI) 110Overwritten & Deleted Records (UODR) 422PDF Defaults (PDFD) 364PDF Retrieval (PDFR) 365Peripheral Option Defaults (PDEF) 362Point to Full Release Copy (PRTF) 366PRCS.CTL Security Inquiry (PCSI) 360Proc Gen to Screen Proc Conv (PTSC) 367Procedure List Specification (JSEL) 352Procedure Rules Documentation (JPRT) 350Procedure Rules Documentation (PGDP) 350Procedure Sort Specification (JSRT) 354Procedure Specification (JDEF) 345Procedure Specifications (JDEF) 345Procedure Step Detail (JDET) 348Process Control Maintenance (SMD2) 404Process Handler Setup (PHSU) 89Process Queue Management (PRQM) 91Process Scheduling (PHTS) 97, 98Process Scheduling (PRSC) 100Process Security Report (SCPR) 384Process Security Summary (PSCS) 159Process Status File Purge (PSFP) 108Rebuild Field History (RBFD) 368Rebuild File History (RBFH) 369Rebuild File Indexing (UTBI) 428Rec Sec User Characteristics (RSUC) 372Record Security List Specs (RPRT) 370Record Security Setup (SCDR) 381Record Security Specification (UTMR) 448Record Security Test Specs (RTST) 375Refresh RFSPECS (BTRR) 305Remote Account New Files (UNFR) 420Remote Account Report (URRA) 424Remote Account Specifications (UTRA) 449Report on New/Obsolete Files (UNFP) 419ReRun a Procedure (UTRR) 460Reset Process Queue Handler (RSPH) 94Running Processes (RPRI) 111Screen Chaining Specification (SCSP) 126, 385Security Class Definition (SCD) 376Security Parameter Values (RSV) 374

Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Forms, Datatel software (cont’d)Sequential File BROWSE Shell (UTFB) 438Set Printer Characteristics (UTSP) 463Speed Entry Text Definition (SPDE) 412Studio Object Status Inquiry (SOSI) 411Studio WorkGroup Definition (SWGD) 413Studio WorkGroup Inquiry (SWGI) 414Transaction Log Specification (UTML) 446TXLOG Purge (UTTP) 464UNIX_CONTROL Record Editing (UCRE) 67Update Main Remote Accounts (UMRA) 417Update User Remote Accounts (UURA) 471User File Index Specification (UTMI) 229, 444User File Information (UTMF) 442User FileSuite Information (UTSF) 461User Help Maintenance (UHLP) 415UT Process Debug Activation (UTDB) 264, 288,

433Validation Codes (VAL) 473View Batch Process Status (VBS) 476View Single Batch Job Step (VBSD) 478

Function keysand screen chains 123

GGenerated Runtime Diagnostic Services (GRDS)

system 262

GRDS log 267how to read 270

GRDS systemadvantages 264log 267on-demand diagnostics 266overview 262

Group, Window 29

GUI Function Button (GUIF) form 342

GUIF form 342

HHistory logging 221

IIndex Storage Field Report (ISFR) 227

International Parameters (INTL) form 343

INTL form 343

ISFR report 227

483

Page 484: Envision Runtime Administration

Index

JJDEF form 345

JDET form 348

Job Statistics Purge (UTJP) form 440

Job Statistics Report (UTJR) form 441

JPRT form 350

JSEL form 352

JSRT form 354

LLabel, Field 30

Label, Window 30

LKUP Resolution Specs (LPRT) form 356

LookUp Resolution Options (UTRO) form 458

LookUp Resolution Specs (UTRD) form 452

LPRT form 356

MMenu Definition (SMD) form 401

MGCC form 357

MGIS form 358

Migrate Computed Columns (MGCC) form 357

Migrate IS-Type Subroutines (MGIS) form 358

Modify Appl VOC Files (UTVF) form 465

Modify Appl VOC Misc. Items (UTVM) form 466

Modify Appl VOC Programs (UTVP) form 468

Multiple File Indexing (UTBA) form 233, 426

My Processes (MYPR) form 102

MYPR form 102

NNetwork Definition (SND) form 407

OODOC form 359

Operator Definition (SOD) form 409

Operator Security Report (SCOR) form 383

OPRI form 110

OPRM form 95

OSGD form 146

Other Technical Documentation (ODOC) form 359

484

Output Security Groups (OSGD) form 146

Outstanding Processes (OPRM) form 95

Outstanding Processes Inquiry (OPRI) form 110

Overwritten & Deleted Records (UODR) form 422

PPCSI form 360

PDEF form 362

PDF Defaults (PDFD) form 364

PDF Retrieval (PDFR) form 365

PDFD form 364

PDFR form 365

Peripheral Option Defaults (PDEF) form 362

PGDP form 350

Phantom processordescription 83

PHSU form 89

PHTS form 97, 98

Point to Full Release Copy (PRTF) form 366

PRCS.CTL Security Inquiry (PCSI) form 360

Proc Gen to Screen Proc Conv (PTSC) form 367

ProcedureDictionary Date Convert (DDCV) 333Job Statistics Purge (UTJP) 440Multiple File Indexing (UTBA) 426Point to Full Release Copy (PRTF) 366Rebuild File Indexing (UTBI) 428TXLOG Purge (UTTP) 464Update Main Remote Accounts (UMRA) 417Update User Remote Accounts (UURA) 471

Procedure List Specification (JSEL) form 352

Procedure Rules Documentation (JPRT) form 350

Procedure Rules Documentation (PGDP) form 350

Procedure Sort Specification (JSRT) form 354

Procedure Specification (JDEF) form 345

Procedure Specifications (JDEF) form 345

Procedure Step Detail (JDET) form 348

Process 23

Process Control Maintenance (SMD2) form 404

Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 485: Envision Runtime Administration

Index

Process handler 83inquiry forms 110managing processes 95managing queues 88process status file records 104setting up 88submitting a task 84

batch process or report 84VOC paragraph 86

system administrator 87task schedules 87

Process Handler Setup (PHSU) form 89

Process Queue Management (PRQM) form 91

Process Scheduling (PHTS) form 97, 98

Process Scheduling (PRSC) form 100

Process Security Report (SCPR) form 384

Process Security Summary (PSCS) form 159

Process Status File Purge (PSFP) form 108

Process Status Report (PSTR) 105

PRQM form 91

PRSC form 100

PRTF form 366

PSCS form 159

PSFP form 108

PSTR report 105

PTSC form 367

RRBFD form 368

RBFH form 369

Rebuild Field History (RBFD) form 368

Rebuild File History (RBFH) form 369

Rebuild File Indexing (UTBI) form 428

Rec Sec User Characteristics (RSUC) form 372

Record Security List Specs (RPRT) form 370

Record Security Setup (SCDR) form 381

Record Security Specification (UTMR) form 448

Record Security Test Specs (RTST) form 375

Recoverygeneral guidelines 249general procedures 249

Refresh RFSPECS (BTRR) form 305

Remote Account New Files (UNFR) form 420

Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Remote Account Report (URRA) form 424

Remote Account Specifications (UTRA) form 449

Remote accountsrecovery procedures 249

ReportAudit Trail Report (UTXL) 470Batch Error Report (UTBE) 425Chain Usage Report (CHUS) 129Difference Engine (DIFF) 336Index Storage Field Report (ISFR) 227Job Statistics Report (UTJR) 441LKUP Resolution Specs (LPRT) 356Operator Security Report (SCOR) 383Overwritten & Deleted Records (UODR) 422Procedure Rules Documentation (JPRT) 350Process Security Report (SCPR) 384Process Security Summary (PSCS) 159Process Status Report (PSTR) 105Record Security List Specs (RPRT) 370Record Security Test Specs (RTST) 375Remote Account Report (URRA) 424Report on New/Obsolete Files (UNFP) 419Sequential File BROWSE Shell (UTFB) 438

Report on New/Obsolete Files (UNFP) form 419

ReRun a Procedure (UTRR) form 460

Reset Process Queue Handler (RSPH) form 94

Resizing files 194, 196

RPRI form 111

RPRT form 370

RS2 form 371

RSPH form 94

RSUC form 372

RSV form 374

RTST form 375

Running Processes (RPRI) form 111

SSCD form 376

SCDF form 379

SCDR form 381

SCOR form 383

SCPR form 384

ScreenExternal Global Parameters (EGP) 337

485

Page 486: Envision Runtime Administration

Index

Screen Chaining Specification (SCSP) form 126, 385

Screen chainsapplication hierarchy 123function keys 123procedure for defining 127procedure for reporting on 129security 122

SCSP form 126, 385

SDD form 388

Securityand screen chains 122

Security Class Definition (SCD) form 376

Security Parameter Values (RSV) form 374

Sequential File BROWSE Shell (UTFB) form 438

Set Printer Characteristics (UTSP) form 463

SKB form 392

SKB1 form 394

SKB2 form 397

SMD form 401

SMD2 form 404

SND form 407

SOD form 409

SOSI form 411

SPDE form 412

Speed Entry Text Definition (SPDE) form 412

Static files, converting to dynamic 196

Status line 30

Studio Object Status Inquiry (SOSI) form 411

Studio WorkGroup Definition (SWGD) form 413

Studio WorkGroup Inquiry (SWGI) form 414

SWGD form 413

SWGI form 414

SYSDEFS file 67

TTransaction Log Specification (UTML) form 446

TXLOG Purge (UTTP) form 464

UUCRE form 67

UHLP form 415

486

UMRA form 417

UNFP form 419

UNFR form 420

UNIX_CONTROL Record Editing (UCRE) form 67

UODR form 422

Update Main Remote Accounts (UMRA) form 417

Update User Remote Accounts (UURA) form 471

URRA form 424

User File Index Specification (UTMI) form 229, 444

User File Information (UTMF) form 442

User FileSuite Information (UTSF) form 461

User Help Maintenance (UHLP) form 415

UT Process Debug Activation (UTDB) form 264, 288, 433

UT.THROWN.ERRORS file 263

UTBA form 233, 426

UTBE form 425

UTBI form 428

UTCD form 430

UTCF form 432

UTDB form 264, 288, 433

UTED form 435

UTFA form 436

UTFB form 438

UTJP form 440

UTJR form 441

UTMF form 442

UTMI form 229, 444

UTML form 446

UTMR form 448

UTRA form 449

UTRD form 452

UTRE form 453

UTRG form 456

UTRO form 458

UTRR form 460

UTSF form 461

UTSP form 463

Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

Page 487: Envision Runtime Administration

Index

UTTP form 464

UTVF form 465

UTVM form 466

UTVP form 468

UTXL form 470

UURA form 471

VVAL form 473

Validation Codes (VAL) form 473

VBS form 476

VBSD form 478

View Batch Process Status (VBS) form 476

View Single Batch Job Step (VBSD) form 478

WWEEKLY.UDT.FILE.ANALYSIS (WUFA) utility

193benefits 196excluding files 200functions 194output items 195resizing files 194, 196workflow 196

WEEKLY.UDT.INDEX.ANALYSIS (WUIA) utility 193, 201

output items of logical check 209output items of physical check 206recommendations 212setting up paragraphs 213understanding 201

Window Element 30

Window Group 29

Window Label 30

WUFA utility 193benefits 196excluding files 200functions 194output items 195resizing files 194, 196workflow 196

Runtime Administration, March 10, 2010© 2010 Datatel, Inc.

WUIA utility 193, 201output items of logical check 209output items of physical check 206recommendations 212setting up paragraphs 213understanding 201

487

Page 488: Envision Runtime Administration

Index

488

Runtime Administration, March 10, 2010© 2010 Datatel, Inc.