Runtime Administration
Reissued Manual as of July 7, 2009
This is a new edition of the Runtime Administration manual for Release 4.7/4.8. This edition replaces the
previous edition dated June 19, 2008.
The Primary Changes Made
Section
Pages
Changes Made
Envision Application Files
46
The description of appl.PRCS.GEN was updated.
MIO Level Check Disable
61
The Envision Parameters Edit (EPED) form was modified to no longer
accept the ALL option. For more information, see AnswerNet
document 39958.15.
Header Blocks
113
Information for Header Blocks was updated to resolve AnswerNet
document 38514.56.
HOLD File Security
143, 145,
and 146
Information for HOLD shared file security was updated to resolve
AnswerNet document 31504.78.
Restricting User Access on
the Security Class
Definition (SCD) Form
149 – 150,
344
Information was updated on the Security Class Definition (SCD) form
to resolve AnswerNet document 32638.48.
Creating/Deleting Operator
Definition Records
154 – 155
Information was updated for new functionality:
Defining Field Security
176
Problems in Envision
Applications
254 and
259
Form Reference
344 – 345,
347 and
377
Using the Process Security
Summary (PSCS) Form
159 – 164
A new form, Process Security Summary (PSCS), was added that
allows you to generate a security-related report for a process you
specify. This resolves AnswerNet document 219.36.
Updating and Maintaining
Security
177
Information for the Build Application Security (BSEC) form was
included to resolve AnswerNet document 40119.04.
Envision Diagnostics
261 – 294
Information on Envision diagnostics was updated to include the
Generated Runtime Diagnostic Services (GRDS) system.
Savedlist Creation (SLCR)
367
The description of the Savedlist Creation (SLCR) form was updated.
Remote Account Report
(URRA)
389
A note was added that the URRA form is not used for Envision 4.8
• The Security Class Definition (SCD) form allows you to detail to
the Field Security Definition (SCDF) form.
• The SCDF form allows you to detail to SCD.
• The Operator Definition (SOD) form allows you to detail to SCD.
Envision®
Runtime Administration
Release 4.7/4.8
July 7, 2009
For last-minute updates and additional information about this manual, see AnswerNet page 2103.81.
Runtime Administration
© 2009 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 Court
Fairfax, VA 22033
(703) 968-9000
(800) DATATEL
www.datatel.com
Table of Contents
17
Overview
19
About This Manual
19
19
20
In This Chapter
Who Should Read This Manual?
How This Manual is Organized
21
Basic Envision Concepts
21
21
22
22
23
23
23
24
24
25
25
26
26
27
28
28
29
30
30
30
31
32
32
32
What is Envision?
Structure of Envision
Envision Tool Kit
Envision Runtime
Envision Forms
Form Layout
Header Block
Data Area
LookUp Area
Types of Envision Forms
Menus
Process Forms
Detail Forms
Envision Fields
Basic Concepts
What is a Window?
Terminology
Types of Windows
Vertical Windows
Horizontal Windows
Processing Windows
General Purpose Forms
Change Peripheral Defaults
Sort/Break Criteria
33
Runtime Features and Terminology
33
35
35
35
36
36
Features
Terminology
Application
Application Trees
Tree Reads
Module
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
5
Table of Contents
37
38
38
39
39
40
40
41
6
Process
Forms
Batch Programs
Procedures
Operator
Device
Peripheral
Security
43
Envision File Overview
43
47
48
48
50
Envision Application Files
Trans-Application Files
Shared and Protected Files
Shared Files
Protected Files
51
Setup
53
Introduction to Setup
55
Defining System Parameters
55
55
56
57
57
57
57
58
58
59
59
59
59
60
60
60
61
61
61
In This Chapter
Using the Envision Parameters Edit (EPED) Form
MIO Indexing Mode (Envision 4.7 Only)
Oracle I/O Off (Envision 4.7 Only)
Disable Full OCI (Envision 4.7 Only)
SQL Select Off (Envision 4.7 Only)
Read Cache Size (Envision 4.7 Only)
Read Cache Log State (Envision 4.7 Only)
Clear Cache Off (Envision 4.7 Only)
Execute Log On
Numeric Precision
Subscription Enabled
Inbound EDX TX Enabled
Use Passive FTP
Windows Clients
Error Stamping
MIO Level Check Disable
UT Debug String
DMI Print Server IP/Port (Envision 4.7 Only)
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
Table of Contents
63
Defining Validation Codes
63
63
64
64
65
In This Chapter
Code Files
Code Tables
Maintaining VAL Codes
Disabling Valcode Tables
67
Editing UNIX_CONTROL Records
67
67
68
70
73
In This Chapter
Form Used
Editing a UNIX_CONTROL Record
Noteworthy Fields on the UCRE Form
Procedure for Editing a UNIX_CONTROL Record
75
Printing
75
75
75
75
76
76
76
78
79
Understanding Levels of Printing
Operating System
Database Management System Software
LPTR
SETPTR
Application Software
Change Peripheral Defaults Form
Defining Printers to Envision for Windows NT and
Windows 2003/2008
For All Printers Defined On The Same Local Server as
Colleague
For a Network Print Server
83
Using the Envision Process Handler
83
84
84
86
87
87
88
89
91
94
95
95
98
What is the Envision Process Handler?
Submitting a Task to the Envision Process Handler
Submitting a Batch Process or Report
Submitting a VOC Paragraph
Viewing and Editing Task Schedules
The System Administrator’s Role
Setting Up the Process Handler and Managing Queues
The Process Handler Setup (PHSU) Form
The Process Queue Management (PRQM) Form
The Reset Process Queue Handler (RSPH) Form
Managing Processes
The Outstanding Processes (OPRM) Form
The Process Scheduling (PHTS) Form
78
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
7
Table of Contents
8
100
102
104
105
108
110
The Process Scheduling (PRSC) Form
The My Processes (MYPR) Form
Working with Process Status File Records
The Process Status Report (PSTR) Form
The Process Status File Purge (PSFP) Form
Using Inquiry Forms
113
Customizing an Application
113
113
113
114
115
115
116
116
118
118
Features
Header Blocks
Resolution Forms
To Change a Resolution Form
Adding/Changing Envision Menus
Creating a New Menu in the Same Application as the
Model
Creating a New Menu
Creating a Menu Based on a Model in a Higher Application
STANDARD.FORMS (Release 17.0 only)
Modifying a Program in STANDARD.FORMS
121
Grouping Screens
121
122
123
123
126
127
129
Chaining Screens
Security and Chaining
Application Hierarchy and Chaining
Function Keys and Chaining
Components of a Screen Chain Definition
Procedure for Chaining Screens
Procedure for Reporting on Chained Screens
131
Security
133
Security Overview
133
133
134
134
135
137
Introduction
Logging In
UNIX
Windows 2003/2008
For All Platforms
Logging Off
139
Operating System Security
139
139
Setting Up Login IDs and Passwords for Users
Setting Up Users in UNIX
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
Table of Contents
140
140
141
141
141
142
142
143
143
143
143
145
Operating System Security in UniData
Accessing the Database Management System
Complete Restriction
Guidelines for Complete Restriction
Limited Restriction
Guidelines for Limited Restriction
Using the Sequential File BROWSE Shell (UTFB) Process
HOLD File Security
Public file security (PB)
Private file security (PR)
Shared file security (SH)
Output Security Groups
147
Application Security
147
148
149
Types of Security
Security Classes
Restricting User Access on the Security Class Definition
(SCD) Form
Restricting User Access for Detail Forms
Guidelines for Defining Security Classes for an Application
Procedure for Creating Security Classes
Operator Definition
Creating/Deleting Operator Definition Records
Procedure for Creating an Operator Definition Record
Procedure for Deleting an Operator Definition Record
Using the PRCS.CTL Security Inquiry (PCSI) Form
Process Security Classes
Field Security Classes
Using the Process Security Summary (PSCS) Form
Noteworthy Fields on the PSCS Form
Procedure for Using the Process Security Summary
Report
150
151
152
153
154
155
155
157
158
158
159
161
162
165
Record and Field Security
165
165
165
166
166
167
168
169
169
Security Layers
Record Security
User Characteristics
Evaluation by Envision Runtime
Guidelines for Specifying Record Security
Defining Record Security User Characteristics
Keywords
Constants
Function Expressions
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
9
Table of Contents
10
169
171
175
175
177
Previously Defined Parameter Definitions
Record Security Definitions
Field Security
Defining Field Security
Updating and Maintaining Security
179
Encrypting Colleague Data
179
179
180
180
181
181
182
183
183
184
185
186
In This Chapter
Before You Begin
Understanding Colleague Encryption
Encryption Algorithm and Encryption Key
Key Concepts
Form Used
File Used
Defining Colleague Encryption
Noteworthy Fields on the UTEP Form
Procedure for Changing an Encryption Parameter
Troubleshooting
Troubleshooting a Failed Encryption Process
187
Maintenance
189
Maintenance Introduction
189
189
190
190
190
191
191
Scheduling System Maintenance
Saves
Consolidation of Job Histories
Purges
Disk Maintenance
Sample Daily Schedule
Notes
193
Using File and Index Analysis Utilities
193
194
195
196
197
200
201
201
203
206
In This Chapter
Using WEEKLY.UDT.FILE.ANALYSIS (WUFA)
Output Items from the WUFA Utility
Workflow for Using the WUFA Utility
Running the WUFA Utility
Excluding Files from Analysis
Using WEEKLY.UDT.INDEX.ANALYSIS (WUIA)
Understanding the WUIA Utility
Examples of Running the WUIA Utility
Results of Running a Physical Check on Index Files
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
Table of Contents
209
212
213
Results of Running a Logical Check on Index Files
Recommendations When Running the WUIA Utility
Setting up Paragraphs for the WUIA Utility
215
Envision File Services
216
217
219
220
220
221
222
223
223
226
234
Add/Change Tracking
Record Link Management
Record Deletion
Transaction Logging
Requesting Transaction Logging
History Logging
File Indexing
Datatel Defined Indexes
User Defined Indexing
Converting Files to Database Indexing
When File Conversion Is Complete
237
Envision Runtime Reports
237
238
238
239
239
240
Procedure Rules Documentation
Lookup Resolution Specifications
Record Security Specifications
Batch Error Report
Job Statistics Report
Audit Trail Report
241
Purging Files
241
242
242
243
244
244
Data Files
Background System Files
Batch Status
Transaction Logging
Database Management Files
Database Management System Files Naming
Conventions
HOLD
PH
SAVEDLISTS
245
245
246
247
Troubleshooting
249
Introduction to Troubleshooting
249
250
Recovery Guidelines
Troubleshooting Envision-Based Software
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
11
Table of Contents
253
Problems in Envision Applications
253
257
System Setup or Security Issues
Runtime Error Messages
261
Envision Diagnostics
261
262
263
264
264
264
265
265
265
266
267
267
268
268
270
279
280
In This Chapter
Overview of the GRDS System
System Integrity Checking
Envision On-demand Diagnostic Systems
Advantages of Using the GRDS System
Auto-generated Logging Services
Self-Diagnostic Services
Log Saved to Disk
Easy to Use, Efficient, and Consistent
On-demand Diagnostics Using GRDS
Sample GRDS Log
Part 1: Runtime Environment Information
Part 2: Services Requested
Part 3: Diagnostic Text
How to Read a GRDS Log
Automatically Generated Services
AE, AX & AD (Process Argument Services: Entry, Exit,
Difference)
PE & PX (Process Entry & Process Exit)
CC (Call Chain)
GS (GEN Stamp)
NK (Next Key)
NS & KS (Number Selected & Keys Selected)
HS, HE, & HX (Hook Services: Sequence, Entry, Exit)
SD (Show Demanded)
ET (Elapsed Time)
Programmer-Specified Services
Accessing GRDS
On-demand Diagnostics Using the UTDB Form
Research the Debug String
Specify UT Process Debug Activation (UTDB) Parameters
Run the Debugged Form
GRDS and UTDB: Do They Interact?
280
281
281
281
282
283
283
284
285
286
288
288
289
291
292
12
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
Table of Contents
293
Appendices
295
System Setup Worksheets
295
296
297
298
299
300
301
Worksheet for Device Definition (SDD)
Worksheet for System Operator Definition (SOD)
Worksheet for Security Classes
Worksheet for Function Keys (SKB1)
Worksheet for Cursor Keys (SKB2)
Worksheet for Graphic Characters
Worksheet For Special Purpose Characters
303
Form Reference
304
305
306
306
308
309
310
312
313
315
318
320
320
320
322
324
326
327
328
329
331
333
335
336
337
338
339
340
342
343
344
Chain Usage Report (CHUS)
Create Printer Control Record (CPRC)
Dictionary Date Convert (DDCV)
Running the Process in Background Mode
Define Field History (DHST)
Difference Engine (DIFF)
Field History Detail (FHDT)
GUI Function Button (GUIF)
International Parameters (INTL)
Procedure Specification (JDEF)
Procedure Step Detail (JDET)
Procedure Rules Documentation (JPRT)
Specifying Output Options
Running the Process in Background Mode
Procedure List Specification (JSEL)
Procedure Sort Specification (JSRT)
LKUP: Resolution Specs (LPRT)
Migrate Computed Columns (MGCC)
Migrate IS-Type Subroutines (MGIS)
Mag Tape Option Defaults (MTOD)
PRCS.CTL Security Inquiry (PCSI)
Peripheral Option Defaults (PDEF)
Point to Full Release Copy (PRTF)
Rebuild Field History (RBFD)
Rebuild File History (RBFH)
Record Security: List Specs (RPRT)
Define Key Functions (RS2)
Rec Sec User Characteristics (RSUC)
Security Parameter Values (RSV)
Record Security: Test Specs (RTST)
Security Class Definition (SCD)
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
13
Table of Contents
347
349
351
352
353
356
356
357
357
357
357
360
360
362
365
367
368
369
369
369
370
370
372
375
377
379
380
382
384
385
387
389
390
391
393
393
395
397
398
400
401
403
14
Field Security Definition (SCDF)
Record Security Setup (SCDR)
Operator Security Report (SCOR)
Process Security Report (SCPR)
Screen Chaining Specification (SCSP)
Device Definition (SDD)
Computer Access Strategies
Assigning Devices on a Switch-based System
Assigning Devices on a Port-based System
Combining Features of Switch-Based and Port-Based
Systems
Device Security
Define Terminal Keyboard (SKB)
Defining a Keyboard
Define Function Keys (SKB1)
Define Cursor Keys (SKB2)
Savedlist Creation (SLCR)
Savedlist Edit Contents (SLED)
Menu Definition (SMD)
Defining a New Menu
Adding a Process to a Menu
Removing a Process from a Menu
Adding a Custom Program to a Menu
Process Control Maintenance (SMD2)
Network Definition (SND)
Operator Definition (SOD)
Speed Entry Text Definition (SPDE)
User Help Maintenance (UHLP)
Update Main Remote Accounts (UMRA)
Report on New/Obsolete Files (UNFP)
Remote Account New Files (UNFR)
Overwritten & Deleted Records (UODR)
Remote Account Report (URRA)
Batch Error Report (UTBE)
File Indexing (UTBI)
Multiple File Indexing (UTBA)
Oracle Clients
File Creation Type Defaults (UTCD)
File Creation (UTCF)
UT Process Debug Activation (UTDB)
Edit Comments (UTED)
BROWSE File Authorization (UTFA)
Sequential File BROWSE Shell (UTFB)
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
Table of Contents
404
404
405
406
407
409
411
413
415
417
419
421
423
425
426
428
429
430
432
434
436
437
439
442
444
447
Functions
Commands
Job Statistics Purge (UTJP)
Job Statistics Report (UTJR)
User File Information (UTMF)
User File Index Specification (UTMI)
Transaction Log Specification (UTML)
Record Security Specification (UTMR)
Remote Account Specifications (UTRA)
LookUp Resolution Specs (UTRD)
File Resolution Defaults (UTRE)
File Resolve Graphic Display (UTRG)
LookUp Resolution Options (UTRO)
ReRun a Procedure (UTRR)
User FileSuite Information (UTSF)
Set Printer Characteristics (UTSP)
TXLOG Purge (UTTP)
Modify Appl VOC Files (UTVF)
Modify Appl VOC Misc. Items (UTVM)
Modify Appl VOC Programs (UTVP)
Audit Trail Report (UTXL)
Update User Remote Accounts (UURA)
Validation Codes (VAL)
View Batch Process Status (VBS)
View Single Batch Job Step (VBSD)
Index
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
15
Table of Contents
16
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
Runtime Administration
Overview
Overview
About This Manual
In This Chapter
This 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, July 7, 2009
© 2009 Datatel, Inc.
19
Overview: About This Manual
How This Manual is Organized
Runtime 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, July 7, 2009
© 2009 Datatel, Inc.
Overview
Basic Envision Concepts
What is Envision?
Envision is one of a category of computer programs referred to as computeraided 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 Envision
Envision consists of two components:
„ Envision Tool Kit (ETK)
„ Envision Runtime (UT)
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
21
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, July 7, 2009
© 2009 Datatel, Inc.
Envision Forms
Envision Forms
All 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, July 7, 2009
© 2009 Datatel, Inc.
23
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, July 7, 2009
© 2009 Datatel, Inc.
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, July 7, 2009
© 2009 Datatel, Inc.
25
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, July 7, 2009
© 2009 Datatel, Inc.
Envision Fields
Envision Fields
Envision 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, July 7, 2009
© 2009 Datatel, Inc.
27
Overview: Basic Envision Concepts
Basic Concepts
Many 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 multivalued 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, July 7, 2009
© 2009 Datatel, Inc.
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 openended; 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, July 7, 2009
© 2009 Datatel, Inc.
29
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, July 7, 2009
© 2009 Datatel, Inc.
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, July 7, 2009
© 2009 Datatel, Inc.
31
Overview: Basic Envision Concepts
General Purpose Forms
In 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, July 7, 2009
© 2009 Datatel, Inc.
Overview
Runtime Features and
Terminology
Features
Envision 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 selfexplanatory 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, July 7, 2009
© 2009 Datatel, Inc.
33
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, July 7, 2009
© 2009 Datatel, Inc.
Terminology
Terminology
Envision 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 Envisionbased 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, July 7, 2009
© 2009 Datatel, Inc.
35
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, July 7, 2009
© 2009 Datatel, Inc.
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 Envisionbased 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, July 7, 2009
© 2009 Datatel, Inc.
37
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, July 7, 2009
© 2009 Datatel, Inc.
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, July 7, 2009
© 2009 Datatel, Inc.
39
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, July 7, 2009
© 2009 Datatel, Inc.
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, July 7, 2009
© 2009 Datatel, Inc.
41
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, July 7, 2009
© 2009 Datatel, Inc.
Overview
Envision File Overview
Envision Application Files
Every 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, July 7, 2009
© 2009 Datatel, Inc.
43
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, July 7, 2009
© 2009 Datatel, Inc.
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, July 7, 2009
© 2009 Datatel, Inc.
45
Overview: Envision File Overview
„
„
„
„
„
„
„
46
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 nongenerated 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.
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
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 userdefined parameters which control how Envision processes records when
they are written to files. The parameters specified in the UFSPECS file are
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
47
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 Envisionbased 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, July 7, 2009
© 2009 Datatel, Inc.
Envision Application Files
Shared Application Files
„
„
„
„
„
„
„
„
„
„
„
„
ERROR*
MENU*
OPERS
PARMS*
PPROCESS
PRCS.CTL*
PRCS.GEN*
PRINTERS*
QBEDEF
SECLASS
VALCODES*
VOC*
Shared Trans-application Files
„
„
„
„
„
„
APPL.CT*
DEVICES*
REMOTES
RFSPECS*
SYSDEFS*
UFSPECS*
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
49
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, July 7, 2009
© 2009 Datatel, Inc.
Runtime Administration
Setup
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, July 7, 2009
© 2009 Datatel, Inc.
53
Setup: Introduction to Setup
54
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
Setup
Defining System Parameters
In This Chapter
This 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, July 7, 2009
© 2009 Datatel, Inc.
55
Setup: Defining System Parameters
Figure 3: Envision Parameters Edit (EPED) Form (Envision 4.7)
Envision 4.7 only
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.
56
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
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”.
Note: The Oracle I/O Off flag is valid only in Oracle environments
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”.
Note: The Disable Full OCI flag is active only in Oracle environments.
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”.
Note: The SQL Select Off flag is valid only in Oracle environments.
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
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
57
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, July 7, 2009
© 2009 Datatel, Inc.
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.
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.
Subscription Enabled
Enter Yes in the Subscription Enabled field to enable DMI transaction
transmission. The default for this field is “No”.
Note: Datatel recommends modifying this field only if specific
application software requires it.
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.
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
59
Setup: Defining System Parameters
If you enter “No”, then DMI_DISPATCH does not accept EDX transactions
from DMI, and returns an error message.
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.
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.
60
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
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, July 7, 2009
© 2009 Datatel, Inc.
61
Setup: Defining System Parameters
62
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
Setup
Defining Validation Codes
In This Chapter
Validation 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, July 7, 2009
© 2009 Datatel, Inc.
63
Setup: Defining Validation Codes
Code Tables
Code 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, July 7, 2009
© 2009 Datatel, Inc.
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.
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.
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.
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
65
Setup: Defining Validation Codes
66
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
Setup
Editing UNIX_CONTROL Records
In This Chapter
This 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.
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
Form Used
Table 2 lists and describes the form used in this chapter.
Table 2: Form Used in This Chapter
Form
UNIX_CONTROL Record Editing
(UCRE)
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
Purpose
View or update a UNIX_CONTROL
record in the SYSDEFS file.
67
Setup: Editing UNIX_CONTROL Records
Editing a UNIX_CONTROL Record
Use 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, July 7, 2009
© 2009 Datatel, Inc.
Editing a UNIX_CONTROL Record
Figure 4: UNIX_CONTROL Record Editing (UCRE) Form
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
69
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, July 7, 2009
© 2009 Datatel, Inc.
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).
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.
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.
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
71
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, July 7, 2009
© 2009 Datatel, Inc.
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, July 7, 2009
© 2009 Datatel, Inc.
73
Setup: Editing UNIX_CONTROL Records
74
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
Setup
Printing
Understanding Levels of Printing
There 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, July 7, 2009
© 2009 Datatel, Inc.
75
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.
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.
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.
76
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
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, July 7, 2009
© 2009 Datatel, Inc.
77
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, July 7, 2009
© 2009 Datatel, Inc.
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, July 7, 2009
© 2009 Datatel, Inc.
79
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, July 7, 2009
© 2009 Datatel, Inc.
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, July 7, 2009
© 2009 Datatel, Inc.
81
Setup: Printing
82
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
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, July 7, 2009
© 2009 Datatel, Inc.
83
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, July 7, 2009
© 2009 Datatel, Inc.
Submitting a Task to the Envision Process Handler
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.
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.
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
85
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, July 7, 2009
© 2009 Datatel, Inc.
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, July 7, 2009
© 2009 Datatel, Inc.
87
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, July 7, 2009
© 2009 Datatel, Inc.
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, July 7, 2009
© 2009 Datatel, Inc.
89
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.
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.
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.
90
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
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.
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.
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.
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
91
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, July 7, 2009
© 2009 Datatel, Inc.
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.
Note: You cannot set suspend start and suspend end times globally.
They must be set for individual queues.
„
Enter the maximum number of concurrent tasks for the queue in the
Maximum Processes field.
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.
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.
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
93
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.
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.
All tasks that are currently running will continue to completion, no new tasks
are started, and the Process Handler is reset.
94
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
Managing Processes
Managing Processes
Three 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, July 7, 2009
© 2009 Datatel, Inc.
95
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.
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.
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: 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, July 7, 2009
© 2009 Datatel, Inc.
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, July 7, 2009
© 2009 Datatel, Inc.
97
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, July 7, 2009
© 2009 Datatel, Inc.
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.
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.
„
„
„
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
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
99
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, July 7, 2009
© 2009 Datatel, Inc.
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, July 7, 2009
© 2009 Datatel, Inc.
101
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, July 7, 2009
© 2009 Datatel, Inc.
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, July 7, 2009
© 2009 Datatel, Inc.
103
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, July 7, 2009
© 2009 Datatel, Inc.
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, July 7, 2009
© 2009 Datatel, Inc.
105
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.
Note: This field is a display only field if you set the Report Only Most
Recent Run field to "Yes."
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.
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.
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.
106
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
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, July 7, 2009
© 2009 Datatel, Inc.
107
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, July 7, 2009
© 2009 Datatel, Inc.
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.
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.
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.
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
109
Setup: Using the Envision Process Handler
Using Inquiry Forms
Two 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, July 7, 2009
© 2009 Datatel, Inc.
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, July 7, 2009
© 2009 Datatel, Inc.
111
Setup: Using the Envision Process Handler
112
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
Setup
Customizing an Application
Features
As 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
Note: The STANDARD.FORMS directory file is no longer supported
in Release 18.0.
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
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
113
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 326,
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, July 7, 2009
© 2009 Datatel, Inc.
Adding/Changing Envision Menus
Adding/Changing Envision Menus
The 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, July 7, 2009
© 2009 Datatel, Inc.
115
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 Datateldefined 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, July 7, 2009
© 2009 Datatel, Inc.
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, July 7, 2009
© 2009 Datatel, Inc.
117
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.
Note: STANDARD.FORMS is no longer supported in Release 18.0.
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
118
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
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, July 7, 2009
© 2009 Datatel, Inc.
119
Setup: Customizing an Application
120
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
Setup
Grouping Screens
Chaining Screens
You 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, July 7, 2009
© 2009 Datatel, Inc.
121
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, July 7, 2009
© 2009 Datatel, Inc.
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
FWD
Function Description
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, July 7, 2009
© 2009 Datatel, Inc.
123
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
CANCEL
Function Description
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, July 7, 2009
© 2009 Datatel, Inc.
Chaining Screens
Table 4: Existing Function Keys and Chained Screens (cont’d)
Function
EXIT
Function Description
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.
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
125
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
Required/
Optional
Usage
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, July 7, 2009
© 2009 Datatel, Inc.
Procedure for Chaining Screens
Table 5: Fields on the Screen Chaining Specification (SCSP) Form (cont’d)
Field
Usage
Required/
Optional
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
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
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
127
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, July 7, 2009
© 2009 Datatel, Inc.
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, July 7, 2009
© 2009 Datatel, Inc.
129
Setup: Grouping Screens
130
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
Runtime Administration
Security
Security
Security Overview
Introduction
The 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 In
When 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, July 7, 2009
© 2009 Datatel, Inc.
133
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.
ALERT! The .login and .cshrc files must be present in your home
directory.
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
134
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
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.
Technical Tip: Device Security Classes are ignored for Switch-based
systems.
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.
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
135
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, July 7, 2009
© 2009 Datatel, Inc.
Logging Off
Logging Off
When the user logs off, the system looks for the paragraph LOGOUT and runs
it if it exists.
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
137
Security: Security Overview
138
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
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
Note: You must be logged in to your host system as the system
administrator to use these utilities.
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.
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
139
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, July 7, 2009
© 2009 Datatel, Inc.
Complete Restriction
Complete Restriction
Complete 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 Restriction
Limited 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, July 7, 2009
© 2009 Datatel, Inc.
141
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.
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.
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.
142
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
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: This version of the UTFB form (including Security Type) is
available in Release 18.0 for Envision 4.8 only.
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
143
Security: Operating System Security
Figure 26: Sample Sequential File BROWSE Shell (UTFB) Form
Envision
4.8 only
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.
144
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
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, July 7, 2009
© 2009 Datatel, Inc.
145
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, July 7, 2009
© 2009 Datatel, Inc.
Security
Application Security
Types of Security
Envision 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, July 7, 2009
© 2009 Datatel, Inc.
147
Security: Application Security
Security Classes
Security 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, July 7, 2009
© 2009 Datatel, Inc.
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, July 7, 2009
© 2009 Datatel, Inc.
149
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.
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.
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.
150
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
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.
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.
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.
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
151
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, July 7, 2009
© 2009 Datatel, Inc.
Operator Definition
Operator Definition
Each 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, July 7, 2009
© 2009 Datatel, Inc.
153
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, July 7, 2009
© 2009 Datatel, Inc.
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, July 7, 2009
© 2009 Datatel, Inc.
155
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, July 7, 2009
© 2009 Datatel, Inc.
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, July 7, 2009
© 2009 Datatel, Inc.
157
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.
Note: An empty list implies all classes.
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.
Technical Tip: This list is derived from the application’s SECLASS file.
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.
158
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
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, July 7, 2009
© 2009 Datatel, Inc.
159
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.
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.
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: 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, July 7, 2009
© 2009 Datatel, Inc.
Using the Process Security Summary (PSCS) Form
Noteworthy Fields on the PSCS Form
The fields described in this section are important for generating a securityrelated 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, July 7, 2009
© 2009 Datatel, Inc.
161
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, July 7, 2009
© 2009 Datatel, Inc.
Using the Process Security Summary (PSCS) Form
Example of the Process Security Summary Report
July 02 2009
Page
1
Process Security Summary Report
Procedure CSRP (Cash Receipt Print)
=================================================================================
Mnemonic...: CSRP / CRJ011
Process....: CRJ011
Application: ST
Type.......: Procedure
---------------------------------------------------------------------------------
Section 1: Security Classes Referencing the Process
--------------------------------------------------Appln
-----ST
ST
ST
ST
Class
-------------------ALLOW.CRJ011
ALLOW.CSRP
BLOCK.CRJ011
BLOCK.CSRP
Usage
----------------------------------------------------Do Only These
Do Only These
Never Do These
Never Do These
July 02 2009
Page
2
Process Security Summary Report
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, July 7, 2009
© 2009 Datatel, Inc.
163
Security: Application Security
July 02 2009
Page
3
Process Security Summary Report
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
Page
4
Process Security Summary Report
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, July 7, 2009
© 2009 Datatel, Inc.
Security
Record and Field Security
Security Layers
Record 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 Security
Envision 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, July 7, 2009
© 2009 Datatel, Inc.
165
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, July 7, 2009
© 2009 Datatel, Inc.
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 reinitialized.
Step 7. Changes to record security definitions do not take effect until Envision is reinitialized.
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, July 7, 2009
© 2009 Datatel, Inc.
167
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, July 7, 2009
© 2009 Datatel, Inc.
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, July 7, 2009
© 2009 Datatel, Inc.
169
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.
Note: Remember that changes or additions to the current user
characteristics do not take effect until a user re-initializes the Envision
environment.
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.
170
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
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, July 7, 2009
© 2009 Datatel, Inc.
171
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, July 7, 2009
© 2009 Datatel, Inc.
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, July 7, 2009
© 2009 Datatel, Inc.
173
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.
Note: Remember that changes or additions to the current record
security definition do not take effect until a user re-initializes the
Envision environment.
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.
174
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
Field Security
Field Security
Envision 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, July 7, 2009
© 2009 Datatel, Inc.
175
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, July 7, 2009
© 2009 Datatel, Inc.
Updating and Maintaining Security
Updating and Maintaining Security
The 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, July 7, 2009
© 2009 Datatel, Inc.
177
Security: Record and Field Security
178
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
Security
Encrypting Colleague Data
In This Chapter
This chapter provides information on the encryption capabilities available for
Colleague processes.
Table 6 lists the topics covered 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
Before You Begin
Table 7 lists the actions that must be complete before you can continue with
the procedures in this chapter.
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, July 7, 2009
© 2009 Datatel, Inc.
179
Security: Encrypting Colleague Data
Understanding Colleague Encryption
In 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-40CBC, 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, July 7, 2009
© 2009 Datatel, Inc.
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
UT Encryption (UTEP)
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
Purpose
Define the encryption scheme used to
encrypt predefined CDD elements.
181
Security: Encrypting Colleague Data
File Used
Table 9 lists the primary file used with Colleague encryption.
Table 9: File Used with Colleague Encryption
File
EDPARMS
182
Description
Stores data from the UTEP form, including encryption
scheme and encryption status information.
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
Defining Colleague Encryption
Defining Colleague Encryption
Figure 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, July 7, 2009
© 2009 Datatel, Inc.
183
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.
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.
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.
184
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
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.
Troubleshooting
The 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, July 7, 2009
© 2009 Datatel, Inc.
185
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.
ALERT! Datatel strongly recommends contacting the Solution
Center for assistance to restart the encryption process when it
does not abort cleanly.
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.
186
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
Runtime Administration
Maintenance
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 Maintenance
Scheduling 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, July 7, 2009
© 2009 Datatel, Inc.
189
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, July 7, 2009
© 2009 Datatel, Inc.
Sample Daily Schedule
Sample Daily Schedule
Below is the example site’s daily schedule.
Table 10: Sample Daily Schedule
Sample Daily Maintenance Schedule
Time and Task performed
Days
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
Notes
1. 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.
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
191
Maintenance: Maintenance Introduction
192
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
Maintenance
Using File and Index Analysis
Utilities
In This Chapter
This 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, July 7, 2009
© 2009 Datatel, Inc.
193
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, July 7, 2009
© 2009 Datatel, Inc.
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, July 7, 2009
© 2009 Datatel, Inc.
195
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 " "
Note: See AnswerNet Document 156.19 for information on how to fix
damaged files.
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.
Note: See AnswerNet document 147.992 for more information on
whether to use static or dynamic UniData files in Colleague.
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: 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, July 7, 2009
© 2009 Datatel, Inc.
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.
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.
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.
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
197
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.
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.
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.
198
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
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, July 7, 2009
© 2009 Datatel, Inc.
199
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, July 7, 2009
© 2009 Datatel, Inc.
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, July 7, 2009
© 2009 Datatel, Inc.
201
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, July 7, 2009
© 2009 Datatel, Inc.
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, July 7, 2009
© 2009 Datatel, Inc.
203
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, July 7, 2009
© 2009 Datatel, Inc.
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, July 7, 2009
© 2009 Datatel, Inc.
205
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, July 7, 2009
© 2009 Datatel, Inc.
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.
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.
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.
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
207
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, July 7, 2009
© 2009 Datatel, Inc.
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, July 7, 2009
© 2009 Datatel, Inc.
209
Maintenance: Using File and Index Analysis Utilities
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.
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.
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.
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.
210
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
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, July 7, 2009
© 2009 Datatel, Inc.
211
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, July 7, 2009
© 2009 Datatel, Inc.
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, July 7, 2009
© 2009 Datatel, Inc.
213
Maintenance: Using File and Index Analysis Utilities
214
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
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, July 7, 2009
© 2009 Datatel, Inc.
215
Maintenance: Envision File Services
Add/Change Tracking
Add/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
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
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.
216
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
Record Link Management
Record Link Management
Some 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, July 7, 2009
© 2009 Datatel, Inc.
217
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, July 7, 2009
© 2009 Datatel, Inc.
Record Deletion
Record Deletion
Record 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, July 7, 2009
© 2009 Datatel, Inc.
219
Maintenance: Envision File Services
Transaction Logging
With 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, July 7, 2009
© 2009 Datatel, Inc.
History Logging
History Logging
History logging enables you to use field and file history to track changes and
view records as they existed at an earlier time.
Note: You can only view data in inquiry mode. History logging does
not allow you to change records or restore them to earlier versions.
„
„
„
„
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 308.
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 310.
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 336.
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 337.
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
221
Maintenance: Envision File Services
File Indexing
Prior 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, July 7, 2009
© 2009 Datatel, Inc.
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
Envision 4.7 only
„
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
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
223
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.
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.
„
„
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: 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, July 7, 2009
© 2009 Datatel, Inc.
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.
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.
„
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.
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
225
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, July 7, 2009
© 2009 Datatel, Inc.
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.
Note: If you have not created custom indexes, skip to step 5 on
page 231.
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.
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
227
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, July 7, 2009
© 2009 Datatel, Inc.
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
Envision 4.7 only
„
„
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.
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.
„
„
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
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
229
Maintenance: Envision File Services
„
„
„
„
„
230
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.
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
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)
Envision 4.7 only
„
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.
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.
For information about the other fields on the EPED form, see “Using the
Envision Parameters Edit (EPED) Form” beginning on page 55.
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, July 7, 2009
© 2009 Datatel, Inc.
231
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
Envision 4.7
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).
Technical Tip: If your account is set up for Envision/Database
Indexing, you can change the default target type by using the dropdown list. You cannot make this change with any other type of accountwide indexing.
232
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
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.
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.
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.
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
233
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.
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.
Figure 42: Delete Obsolete Index Files (DOIF) Form
234
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
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, July 7, 2009
© 2009 Datatel, Inc.
235
Maintenance: Envision File Services
236
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
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 Documentation
The 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, July 7, 2009
© 2009 Datatel, Inc.
237
Maintenance: Envision Runtime Reports
Lookup Resolution Specifications
The 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 Specifications
The 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, July 7, 2009
© 2009 Datatel, Inc.
Batch Error Report
Batch Error Report
The 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 Report
The 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, July 7, 2009
© 2009 Datatel, Inc.
239
Maintenance: Envision Runtime Reports
Audit Trail Report
The 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, July 7, 2009
© 2009 Datatel, Inc.
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 Files
Purging, 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, July 7, 2009
© 2009 Datatel, Inc.
241
Maintenance: Purging Files
Background System Files
The 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, July 7, 2009
© 2009 Datatel, Inc.
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, July 7, 2009
© 2009 Datatel, Inc.
243
Maintenance: Purging Files
Database Management Files
Three 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, July 7, 2009
© 2009 Datatel, Inc.
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, July 7, 2009
© 2009 Datatel, Inc.
245
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, July 7, 2009
© 2009 Datatel, Inc.
Runtime Administration
Troubleshooting
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 Guidelines
Occasionally 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, July 7, 2009
© 2009 Datatel, Inc.
249
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, July 7, 2009
© 2009 Datatel, Inc.
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, July 7, 2009
© 2009 Datatel, Inc.
251
Troubleshooting: Introduction to Troubleshooting
252
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
Troubleshooting
Problems in Envision
Applications
System Setup or Security Issues
This 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, July 7, 2009
© 2009 Datatel, Inc.
253
Table 12: Problems With System Setup or Security
Problem
I get logged out when I try to enter an
application.
Cause
Invalid or missing OPERS
record.
Solution
Check the user’s OPERS record. Start with the application the
user is trying to run. Enter the application and run SOD. If the
user’s OPERS record is not in the current application, determine if
the OPERS record is in an application higher up in the tree. If the
user should only access the current application, create a new
OPERS record through SOD.
Make sure the Name field has data entered.
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
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 DEVICE record. For port-based systems, run
SND and determine the DEVICES type from the user’s line
number. For switch-based systems, use the user’s login ID as the
DEVICES type. Run SDD from any application for the device
definition in question. Go to the display table field and use the
LookUp Processor to select a valid display table.
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 DEVICE record. For port-based systems, run
SND and determine the DEVICES type from the user’s line
number. For switch-based systems, use the user’s login ID as the
DEVICES type. Run SDD from any application for the device
definition in question. Go to the display table field and use the
LookUp Processor to select a valid display table. You may need to
define the desired keyboard table.
Troubleshooting: Problems in Envision Applications
254
Table 12 lists common problems with system setup or security, with their causes and solutions
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
Table 12: Problems With System Setup or Security (cont’d)
Problem
Cause
Solution
Invalid mnemonic or
insufficient security rights.
Check the spelling of the entered mnemonic. If spelled incorrectly,
enter the correct spelling. If the user has insufficient security
rights for a mnemonic, check if the user is supposed to use that
process and check the security class definition on SCD for the
secured mnemonic. If the user should have access to the
process, check the user’s security class for the current application
on SOD. If the user has a specific operator definition for the
current application, make sure the operator definition includes the
security class for the secured mnemonic. If the user does not
have an operator definition for the current application, either add
a specific operator definition for the current application or check
the operator definition for the next higher application in the tree.
A mnemonic does not show up on the menu.
Insufficient security right for
the mnemonic.
The Runtime Menu Processor does not show mnemonics for
which a user has no security rights. If the user is supposed to
have access to the process, see the solution to the last problem.
I can’t enter data into a field on a screen.
Insufficient Field Security
Rights.
Check the Field Security definition for the field in question on
SCDF. The security class assigned for field security. Then check
the user’s security classes on SOD. If the user should have
access to the data in the field, add the proper security class for
the 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 access to more than one process, check
the initial menu mnemonic on SOD. If the user does not have an
operator definition for the current application, check the operator
definition in the next higher application. Make sure the initial
menu mnemonic for the user is a menu.
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 user can re-initialize the Envision
environment by:
or
Data doesn’t show for a field; all I see are
asterisks.
• 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.
255
System Setup or Security Issues
My terminal just beeps when I enter a
mnemonic at a menu prompt.
Problem
Cause
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 has a lapsed time specified. The user
must re-enter his Envision password defined on SOD.
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 Envision. 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.
To prevent a user from BROWSEing a COMO file, you may
consider removing the &UFD& directory file from the BROWSE
file authorization list on UTFA.
Troubleshooting: Problems in Envision Applications
256
Table 12: Problems With System Setup or Security (cont’d)
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
Runtime Error Messages
Table 13 lists common Envision initialization error messages with their causes and solutions.
Table 13: Envision Initialization Error Messages
Message
“FATAL: bad.file is not present”
Cause
One of the following transapplication files is missing:
• SYSDEFS
• DEVICES
• VOC
• SAVEDLISTS
• REFSPECS
Solution
Check the VOC file definitions for each file ENVINIT cannot open. If
the VOC file is the bad file, make sure you are attached to a valid
database account in which an Envision-based application has been
installed. If the bad file is a database file (one with “&” in its name),
create the file on your account. If the bad file is an Envision file
(SYSDEFS, DEVICES, RFSPECS or UFSPECS), call Datatel if the
VOC record for the file seems in order. There may have been a
problem with your last release installation or VOC pointers may be
damaged.
• UPSPECS
• UFD
• HOLD
• PH
Missing or invalid renewal
codes detected.
Call Datatel. The renewal codes control what Envision modules you
can run. There may have been a problem with your last release
installation or VOC pointers may be damaged.
“SYSTEM DATE current.date precedes
previous login date”
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 your computer. If the message persists,
call Datatel.
“Envision not initialized”
257
Runtime Error Messages
“FATAL security fault: Missing Renewal
Code Record”
Message
Cause
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. There may have been a problem with your
last release installation or you may need to install a new release.
“Warning: Lease to module expired date (n
days grace)”
The date on which your
software lease expires has
passed.
Call Datatel immediately. There may have been a problem with your
last release installation or you may need to install a new release.
Damaged or missing renewal
code record.
Call Datatel immediately. The renewal codes control what Envision
modules you can run. There may have been a problem with your
last release installation or VOC pointers may be damaged.
“FATAL: Network definitions not present.”
Envision cannot read the
TASKLIST record in the
SYSDEFS file.
Check the VOC pointer for the SYSDEFS file. It should be pointing
to the current release account. If this record is damaged or missing,
call Datatel immediately. If both the SYSDEFS VOC record and the
TASKLIST record in SYSDEFS are in order, call Datatel. There may
have been a problem with your last release installation or VOC
pointers may be damaged.
“Unauthorized access to secured terminal.”
Incorrect password entered for
a secured terminal.
If the password was misspelled, enter the correct spelling. If the
password is not misspelled, you may think the password is one
thing while Envision thinks it is another. Check the device definition
on the Device Definition (SDD) form and make sure the device
password is correct.
“Please contact Datatel”
“FATAL security fault: Bad Customer
Number in
Renewal Code Record“
Troubleshooting: Problems in Envision Applications
258
Table 13: Envision Initialization Error Messages (cont’d)
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
Table 14 lists common application initialization error messages with their causes and solutions.
Table 14: Application Initialization Error Messages
Message
“Missing file: appl.bad.applfile
All base application files must be present.”
Cause
Missing or invalid application
file.
“Session not established.”
Solution
Check the VOC pointers for each of the application files for the
current application (an asterisk (*) means is subject to tree reads):
• CDD
• PPROCESS*
• DOC
• PRCS.CTL*
• ENV*
• PRCS.DEF
• ERROR*
• PRCS.GEN*
• FILE.SPECS*
• PRINTERS*
• HELP*
• QBEDEF*
• HELP.LONG*
• SECLASS*
• INSERTS
• SOURCE
• MENU*
• SUBROUTINES
• OBJ
• VALCODES*
• OPERS*
• VOC
• PARMS*
“Improperly set up user: login. See your
system administrator.”
Missing or invalid OPERS
record.
Be sure the Name field has data.
If there is no data in the field, the OPERS record is invalid.
259
Runtime Error Messages
Check the user’s OPERS record. Start with the application the
user is trying to run. Enter the application and run the SOD form. If
the user’s OPERS record is not in the current application,
determine if the OPERS record is in an application higher up in
the tree. If the user should only access the current application,
create a new OPERS record through SOD.
Message
Cause
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 the entered mnemonic. If spelled incorrectly,
enter the correct spelling. If the user has insufficient security rights
for a mnemonic, check if the user is supposed to use that process
and check the security class definition on SCD for the secured
mnemonic. If the user should have access to the process, check
the user’s security class for the current application on the SOD
form. If the user has a specific operator definition for the current
application, make sure the operator definition includes the
security class for the secured mnemonic. If the user does not
have an operator definition for the current application, either add a
specific operator definition for the current application or check the
operator definition for the next higher application in the tree.
“Password expired on date”
The user’s password has
expired.
If the user’s need to access your system has ended, delete the
user’s operator definition. If the user should still have access to
the application in question, check the password expiration date on
the SOD form.
“WARNING: Your password expires on
date.
The user’s access to the
application is near its end.
If the user’s access to the application should end on the date
specified, do nothing: the user will be unable to enter the
application on or after that date. If the user should continue to
have access to the application, change the password expiration
date on the SOD form.
Invalid operator definition or
incorrect Envision password.
If this message appears alone, the user has entered an incorrect
Envision password. If the password was misspelled, have the
user type in the correct password. If the user has typed in what he
thought was the correct password, check the Envision password
on the SOD form. If this message appears with another message,
see above for the other message.
See your security administrator“
“Access to appl has been denied”
Troubleshooting: Problems in Envision Applications
260
Table 14: Application Initialization Error Messages (cont’d)
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
Troubleshooting
Envision Diagnostics
In This Chapter
This 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, July 7, 2009
© 2009 Datatel, Inc.
261
Troubleshooting: Envision Diagnostics
Overview of the GRDS System
The 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, July 7, 2009
© 2009 Datatel, Inc.
System Integrity Checking
System Integrity Checking
The 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, July 7, 2009
© 2009 Datatel, Inc.
263
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, July 7, 2009
© 2009 Datatel, Inc.
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 handcoded 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, July 7, 2009
© 2009 Datatel, Inc.
265
Troubleshooting: Envision Diagnostics
On-demand Diagnostics Using GRDS
The 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, July 7, 2009
© 2009 Datatel, Inc.
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.....: SAMPLE
Started....: 00:04:16 Aug 23 2006
User.......: jgv
Server.....: SDW2K3APP
Environment: D:\dev\etk48dev
OS.........: Windows NT
UniData....: 6.1 Build: (5150)
UDT.OPTIONS ON: 41 U_UDT_SERVER ON
46 U_UNFLUSHDATA ON
88 U_CALLC_CDECL ON
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
267
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, July 7, 2009
© 2009 Datatel, Inc.
On-demand Diagnostics Using GRDS
2_3_4| ad} Arg 2: AR.VWVAR: MAT(25)
2_3_4| ad}
(2) =XGUS
2_3_4| ad}
(12) =001000111111101111001100100011111110111100111011110111000000
2_3_4| ad}
(16) =0
2_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 lists
2_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 lists
2_3| et} ACTUAL=2078 CPU=16 (milliseconds)
...
2_3|
2_3|
2_3|
2_3|
2_3|
2_3|
2_3|
2_3|
2_3|
2_3|
2_3|
...
1}
1}
1}
1}
1}
1}
1}
1}
1}
1}
1}
@60: X.TEST.STRING has 10 fields:
<1> =THIS
<2> =IS
<3> =A} 2 {TEST} 3 {OF}
<4> =MULTI-FIELD
<5> =SHOWA
<6> =WITH
<7> =3rd
<8> =fld
<9> =having
<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@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 =S_GUS
...
2_3_4|
2_3_4|
...
1}
2}
@123: XTEST1 =THIS HAS~A CONTROL CHARACTER IN IT !Contains non-printing characters!
@124: XTEST2 =This has 200 trailing blanks<- +200 trailing spaces!
2_3|
2_3|
2_3|
2_3|
2_3|
...
1}
1}
1}
1}
1}
@542: SHOWA $TABLE(GUSV.A1,GUSV.A2,GUSV.A3)
GUSV.A1 GUSV.A2 GUSV.A3
======= ======= =======
1) F
G
H
2) I
J
K
2_3|
2_3|
-------------------------------------------------------------Closing GRDS session log "SAMPLE" at 00:04:31 Aug 23 2006
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
269
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 lists
2_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, July 7, 2009
© 2009 Datatel, Inc.
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}
2_3_4| ae}
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
Arg 6: R.CWSTATE has 10 fields
<6> =Bob
271
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}
2_3_4| ae}
Arg 2: AR.VWVAR: MAT(25)
(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}
272
Arg2: POP.MENU =
CSEG
^^^
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
On-demand Diagnostics Using GRDS
Trailing Spaces
Trailing blanks are not printed, but their presence is indicated:
2_3_4|
2}
@124) XTEST2 =This has 200 trailing blanks<- +200 trailing spaces!
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").
2_3_4|
2_3_4|
2_3_4|
2_3_4|
2_3_4|
2_3_4|
2_3_4|
2_3_4|
2_3_4|
2_3_4|
2_3_4|
2_3_4|
2_3_4|
ae}
ae}
ae}
ae}
ae}
ae}
ae}
ae}
ae}
ae}
ae}
ae}
ae}
Arg 4: V.BASE.LINE has 2 fields
Arg 5: AR.CWVAR: MAT(50,25)
(1,1) =MENU_PRCSR
(1,5) =10
(1,8) =10
(1,9) =10
(1,10) =20
(1,20) has 2 fields
<2> =1
(1,21) =Enter Mnemonic or Selection Number, or press FINISH
Arg 6: R.CWSTATE has 2 fields
<1> =X
<2> =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}
2_3_4| ae}
2_3_4| ad}
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
ARG 1: A.TYPECODE =C2
-------------<>------------ARG 1: A.TYPECODE =
273
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|
2_3|
2_3|
2_3|
1}
1}
1}
1}
@60: X.TEST.STRING has 10 fields
<1> =THIS
<2> =IS
<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}
2_3| hx}
2_3| hs}
274
-->Enter FLD_ENTRY hook of F5 (GUS.FILE.ID)
<- Leave FLD_ENTRY hook of F5 (GUS.FILE.ID)
-->Enter FLD_ACCEPT hook of F5 (GUS.FILE.ID)
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
On-demand Diagnostics Using GRDS
Control Characters
Non-printing characters are replaced by the tilde character, and a warning is
issued:
2_3_4| 1} @123: XTEST1 =THIS HAS~A CONTROL CHARACTER IN IT !Contains non-printing characters!
^
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
$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|
2_3|
2_3|
2_3|
2_3|
1}
1}
1}
1}
1}
@542: SHOWA $TABLE(GUSV.A1,GUSV.A2,GUSV.A3)
GUSV.A1 GUSV.A2 GUSV.A3
======= ======= =======
1) F
G
H
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.
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
275
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.
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)
The context marker below shows that "JGV..." was entered into the SOD
form’s LookUp prompt.
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, July 7, 2009
© 2009 Datatel, Inc.
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):
397]
398]
399]
400]
401.
402.
403.
404.
405.
406.
407]
408]
409]
410]
411.
412.
413.
414.
415]
416]
417]
...
2_3_4_\
2_3_4_5| pe} * S_MIO_READ (from S.GET.RESOLUTN @145)
2_3_4_5| cc} 1=UT.INIT@49 2=MENU.INIT@1981 3=UTOPRS@3072 ... 5=S_MIO_READ
2_3_4_/ px} * RETURN to S.GET.RESOLUTN @145 (from S_MIO_READ)
2_3_/ --} * RETURN to UTOPRS @12 (from S.GET.RESOLUTN)
2_3_\ ++} * S.INPT.SEL.ID.LKUP (from UTOPRS @3072)
2_3_4_\ ++} * S.LKUP.ID.PARSE (from S.INPT.SEL.ID.LKUP @335)
2_3_4_5_\ ++} * S.SELECT.LISTS (from S.LKUP.ID.PARSE @154)
2_3_4_5_6_\ ++} * S_MIO_EXECUTE (from S.SELECT.LISTS @594)
2_3_4_5_6_7_\ ++} * S_MIO_SEL (from S_MIO_EXECUTE @473)
2_3_4_5_6_7_8_\
2_3_4_5_6_7_8_9| pe} * S_MIO_READ (from S_MIO_SEL @784)
2_3_4_5_6_7_8_9| cc} 1=UT.INIT@49 2=MENU.INIT@1981 3=UTOPRS@3072 ... 9=S_MIO_READ
2_3_4_5_6_7_8_/ px} * RETURN to S_MIO_SEL @784 (from S_MIO_READ)
2_3_4_5_6_7_/ --} * RETURN to S_MIO_EXECUTE @473 (from S_MIO_SEL)
2_3_4_5_6_/ --} * RETURN to S.SELECT.LISTS @594 (from S_MIO_EXECUTE)
2_3_4_5_/ --} * RETURN to S.LKUP.ID.PARSE @154 (from S.SELECT.LISTS)
2_3_4_5_\ ++} * UTRESO (from S.LKUP.ID.PARSE @565)
2_3_4_5_6_\
2_3_4_5_6_7| pe} * S_MIO_READ (from UTRESO @21)
2_3_4_5_6_7| cc} 1=UT.INIT@49 2=MENU.INIT@1981 3=UTOPRS@3072 ... 7=S_MIO_READ
...
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.
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
277
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, July 7, 2009
© 2009 Datatel, Inc.
Automatically Generated Services
Automatically Generated Services
An 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, July 7, 2009
© 2009 Datatel, Inc.
279
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, July 7, 2009
© 2009 Datatel, Inc.
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, July 7, 2009
© 2009 Datatel, Inc.
281
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, July 7, 2009
© 2009 Datatel, Inc.
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, July 7, 2009
© 2009 Datatel, Inc.
283
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, July 7, 2009
© 2009 Datatel, Inc.
Programmer-Specified Services
Programmer-Specified Services
Programmer-specified services are available only if you added supporting
code to your process.
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
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.
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
285
Troubleshooting: Envision Diagnostics
Accessing GRDS
Access 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, July 7, 2009
© 2009 Datatel, Inc.
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, July 7, 2009
© 2009 Datatel, Inc.
287
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_DEBUG
END
288
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
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.
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.
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.
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
289
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.
Note: You can also remove a string that already exists in the Debug
String field by entering that string in the Modify String field
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].
290
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
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, July 7, 2009
© 2009 Datatel, Inc.
291
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 (UTDBstyle) 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 oldstyle 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, July 7, 2009
© 2009 Datatel, Inc.
Runtime Administration
Appendices
Appendices
System Setup Worksheets
Worksheet for Device Definition (SDD)
Device Name
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
Display Table
Keyboard
295
Appendices: System Setup Worksheets
Worksheet for System Operator
Definition (SOD)
Application:
Login ID
296
Initial Menu
Security Class(es)
Envision
Password
Password
Expiration
Date
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
Worksheet for Security Classes
Worksheet for Security Classes
Do Only These
Class Name:
Never Do These
Inquiry Only
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
Privileged
297
Appendices: System Setup Worksheets
Worksheet for Function Keys (SKB1)
Keyboard Name:
Envision Function
Key Assignment
ASCII 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, July 7, 2009
© 2009 Datatel, Inc.
Worksheet for Cursor Keys (SKB2)
Worksheet for Cursor Keys (SKB2)
Keyboard Name
Envision Function
Key Assignment
ASCII 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, July 7, 2009
© 2009 Datatel, Inc.
299
Appendices: System Setup Worksheets
Worksheet for Graphic Characters
Graphic
Abbreviation
Display Type Name
Character Set to
Graphic
Display Graphic
Description
Line
Character
Decimal Equivalent of
Graphic
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, July 7, 2009
© 2009 Datatel, Inc.
Worksheet For Special Purpose Characters
Worksheet For Special Purpose
Characters
Display Type Name:
Character
Abbreviation
Character Description
Special Purpose
Character Definition
Line
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, July 7, 2009
© 2009 Datatel, Inc.
301
Appendices: System Setup Worksheets
302
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
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, July 7, 2009
© 2009 Datatel, Inc.
303
Appendices: Form Reference
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 46: Sample Chain Usage Report (CHUS) Form
304
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
Create Printer Control Record (CPRC)
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.
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.
You can find detailed steps to set up the VALID.PRINTERS valcode in
Answernet document 196.848.
Figure 47: Sample Create Printer Control Record (CPRC) Form
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
305
Appendices: Form Reference
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.
306
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
Dictionary Date Convert (DDCV)
Figure 48: Sample Dictionary Date Convert (DDCV) Form
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
307
Appendices: Form Reference
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.
Note: The FLDH form is available only through the Envision Tool Kit.
Figure 49: Sample Define Field History (DHST) Form
308
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
Difference Engine (DIFF)
Difference Engine (DIFF)
Figure 50: Sample Difference Engine (DIFF) Form
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
309
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 51: 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.
310
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
Field History Detail (FHDT)
Table 18: Query Lang Retrieval Help for Field History Detail (FHDT) Form
Where Field History Detail (FHDT) Data Is Stored
To 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, July 7, 2009
© 2009 Datatel, Inc.
311
Appendices: Form Reference
GUI Function Button (GUIF)
Figure 52: Sample GUI Function Button (GUIF) Form
Table 19: Query Lang Retrieval Help for GUI Function Button (GUIF) Form
Where GUI Function Button (GUIF) Data Is Stored
To 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
312
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
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.
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.
Figure 53: Sample International Parameters (INTL) Form
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
313
Appendices: Form Reference
Table 20: Query Lang Retrieval Help for International Parameters (INTL) Form
Where International Parameters (INTL) Data Is Stored
To 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
314
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
Procedure Specification (JDEF)
Procedure Specification (JDEF)
Use the Procedure Specifications (JDEF) form to modify an existing
procedure or to create a new one.
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.
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.
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.
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.
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
315
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.
316
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
Procedure Specification (JDEF)
Figure 54: Sample Procedure Specification (JDEF) Form
Table 21: Query Lang Retrieval Help for Procedure Specification (JDEF) Form
Where Procedure Specification (JDEF) Data Is Stored
To 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, July 7, 2009
© 2009 Datatel, Inc.
317
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.
318
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
Procedure Step Detail (JDET)
Figure 55: Sample Procedure Step Detail (JDET) Form
Table 22: Query Lang Retrieval Help for Procedure Step Detail (JDET) Form
Where Procedure Step Detail (JDET) Data Is Stored
To retrieve data from
use this file
and this field
Procedure Description
PRCS.CTL
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
PROCESS.DESCRIPTION
319
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.
320
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
Procedure Rules Documentation (JPRT)
Figure 56: Sample Procedure Rules Documentation (JPRT) Form
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
321
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 57: Sample Procedure List Specification (JSEL) Form
322
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
Procedure List Specification (JSEL)
Table 23: Query Lang Retrieval Help for Procedure List Specification (JSEL) Form
Where Procedure List Specification (JSEL) Data Is Stored
To 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, July 7, 2009
© 2009 Datatel, Inc.
323
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 58: Sample Procedure Sort Specification (JSRT) Form
324
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
Procedure Sort Specification (JSRT)
Table 24: Query Lang Retrieval Help for Procedure Sort Specification (JSRT) Form
Where Procedure Sort Specification (JSRT) Data Is Stored
To 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, July 7, 2009
© 2009 Datatel, Inc.
325
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 417.
Figure 59: Sample LKUP: Resolution Specs (LPRT) Form
326
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
Migrate Computed Columns (MGCC)
Migrate Computed Columns (MGCC)
Use the Migrate Computed Columns (MGCC) form to do the following:
„ Convert your computed columns to the R18 computed column language.
„ Create a record in the CC.ITEMS file for each computed column.
„ Assign the computed columns to the USER bundle, in preparation for later
migration steps.
„ 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 the Envision Tool Kit for each application (CORE, ST,
etc.) in which you have custom computed columns.
ALERT! This form is available in Release 18.0 for Envision 4.8
only.
Figure 60: Sample Migrate Computed Columns (MGCC) Form
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
327
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.
ALERT! This form is available in Release 18.0 for Envision 4.8
only.
Figure 61: Sample Migrate IS-Type Subroutines (MGIS) Form
328
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
Mag Tape Option Defaults (MTOD)
Mag Tape Option Defaults (MTOD)
Use the Mag Tape Option Defaults (MTOD) form to define all of the
attributes associated with magnetic tape units. You can only access this form
by entering T (the tape unit output mode) in field 6 on the Peripheral Option
Defaults (PDEF) form. The tape unit output mode and the Mag Tape Option
Defaults form are obsolete.
Figure 62: Sample Mag Tape Option Defaults (MTOD) Form
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
329
Appendices: Form Reference
Table 25: Query Lang Retrieval Help for Mag Tape Option Defaults Form
Where Mag Tape Option Defaults Data Is Stored
To retrieve data from
use this file
and this field
Mag Tape ID
PRINTERS
PRINTERS.ID
Description
PRINTERS
PTR.DESCRIPTION
Double Buffering
PRINTERS
TAPE.DOUBLE.BUFFER
Conversion Mode
PRINTERS
TAPE.CONV.MODE
No of Tracks
PRINTERS
TAPE.NO.OF.TRACKS
Tape Drive Unit
PRINTERS
TAPE.DRIVE.UNIT
Block Size
PRINTERS
TAPE.BLKSIZE
Wait Option
PRINTERS
TAPE.WAIT
Initial Append
PRINTERS
TAPE.INIT.APPEND
Exit Append
PRINTERS
TAPE.EXIT.APPEND
Unload Option
PRINTERS
TAPE.UNLOAD
330
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
PRCS.CTL Security Inquiry (PCSI)
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 63: Sample PRCS.CTL Security Inquiry (PCSI) Form
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
331
Appendices: Form Reference
Table 26: Query Lang Retrieval Help for PRCS.CTL Security Inquiry (PCSI) Form
Where PRCS.CTL Security Inquiry (PCSI) Data Is Stored
To 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
332
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
Peripheral Option Defaults (PDEF)
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, tape devices, and dedicated
printers.
Figure 64: Sample Peripheral Option Defaults (PDEF) Form
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
333
Appendices: Form Reference
Table 27: Query Lang Retrieval Help for Peripheral Option Defaults (PDEF) Form
Where Peripheral Option Defaults (PDEF) Data Is Stored
To 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
334
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
Point to Full Release Copy (PRTF)
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.
Note: The Point to Full Release Copy (PRTF) form is not used for
Envision 4.8 because of changes to the Envision architecture.
Figure 65: Sample Point to Full Release Copy (PRTF) Form
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
335
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 66: 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.
336
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
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.
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.
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 67: Sample Rebuild File History (RBFH) Form
Table 28: Query Lang Retrieval Help for Rebuild File History (RBFH) Form
Where Rebuild File History (RBFH) Data Is Stored
To retrieve data from
use this file
and this field
Field
PRCS.CTL
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
PROCESS.FIELD.LIST
337
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 413.
Figure 68: Sample Record Security: List Specs (RPRT) Form
338
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
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.
ALERT! You cannot access this form from the RSUC form if the
key derivation is not a function.
Figure 69: Sample Define Key Functions (RS2) Form
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
339
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.
340
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
Rec Sec User Characteristics (RSUC)
Figure 70: 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 Stored
To 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, July 7, 2009
© 2009 Datatel, Inc.
341
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 71: Sample Security Parameter Values (RSV) Form
342
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
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 72: Sample Record Security: Test Specs (RTST) Form
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
343
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 switchbased 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.
344
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
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 377.
See page 356 for details on the Device Definition (SDD) form. For more
information about the Menu Definition (SMD) form, refer to page 369.
Figure 73: Sample Security Class Definition (SCD) Form
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
345
Appendices: Form Reference
Table 30: Query Lang Retrieval Help for Security Class Definition (SCD) Form
Where Security Class Definition (SCD) Data Is Stored
To 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
346
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
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 74: Sample Field Security Definition (SCDF) Form
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
347
Appendices: Form Reference
Table 31: Query Lang Retrieval Help for Field Security Definition (SCDF) Form
Where Field Security Definition (SCDF) Data Is Stored
To 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
348
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
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 75: Sample Record Security Setup (SCDR) Form
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
349
Appendices: Form Reference
Table 32: Query Lang Retrieval Help for Record Security Setup (SCDR) Form
Where Record Security Setup (SCDR) Data Is Stored
To 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
350
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
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 76: Sample Operator Security Report (SCOR) Form
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
351
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 77: Sample Process Security Report (SCPR) Form
352
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
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, July 7, 2009
© 2009 Datatel, Inc.
353
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.
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.
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 78: Sample Screen Chaining Specification (SCSP) Form
354
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
Screen Chaining Specification (SCSP)
Table 33: Query Lang Retrieval Help for Screen Chaining Specification (SCSP) Form
Where Form Chaining Specification (SCSP) Data Is Stored
To retrieve data from
use this file
and this field
Chain Process LookUp
PRCS.CTL
PROCESS.MNEMONIC
Description
PRCS.CTL
PROCESS.DESCRIPTION
PROCESS.GROUP.POST.CO
MMIT
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, July 7, 2009
© 2009 Datatel, Inc.
355
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.
356
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
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 PortBased 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 portdefinition 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, July 7, 2009
© 2009 Datatel, Inc.
357
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.
Technical Tip: For switch-based devices, the system ignores the
security classes defined in the device record.
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 375. For more information on defining security classes, refer to
page 344.
Figure 79: Sample Device Definition (SDD) Form
358
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
Device Definition (SDD)
Table 34: Query Lang Retrieval Help for Device Definition (SDD) Form
Where Device Definition (SDD) Data Is Stored
To 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, July 7, 2009
© 2009 Datatel, Inc.
359
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.
360
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
Define Terminal Keyboard (SKB)
Figure 80: 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 Stored
To 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, July 7, 2009
© 2009 Datatel, Inc.
361
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.
362
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
Define Function Keys (SKB1)
Figure 81: 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 Stored
To 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, July 7, 2009
© 2009 Datatel, Inc.
363
Appendices: Form Reference
Table 36: Query Lang Retrieval Help for Define Function Keys (SKB1) Form (cont’d)
Where Define Function Keys (SKB1) Data Is Stored
To retrieve data from
use this file
and this field
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
364
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
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 82: Sample Define Cursor Keys (SKB2) Form
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
365
Appendices: Form Reference
Table 37: Query Lang Retrieval Help for Define Cursor Keys (SKB2) Form
Where Define Cursor Keys (SKB2) Data Is Stored
To 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
366
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
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.
ALERT! This form is available in Release 18.0 for Envision 4.8
only.
Figure 83: Sample Savedlist Creation (SLCR) Form
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
367
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.
ALERT! This form is available in Release 18.0 for Envision 4.8
only.
Figure 84: Sample Savedlist Edit Contents (SLED) Form
368
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
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.
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.
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.
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
369
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 344 for details on the Security Class Definition (SCD) form.
370
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
Menu Definition (SMD)
Figure 85: Sample Menu Definition (SMD) Form
Table 38: Query Lang Retrieval Help for Menu Definition (SMD) Form
To retrieve data from
Where Menu Definition (SMD) Data Is Stored
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, July 7, 2009
© 2009 Datatel, Inc.
371
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.
372
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
Process Control Maintenance (SMD2)
Figure 86: Sample Process Control Maintenance (SMD2) Form
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
373
Appendices: Form Reference
Table 39: Query Lang Retrieval Help for Process Control Maintenance (SMD2) Form
Where Process Control Maintenance (SMD2) Data Is Stored
To 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
374
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
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.
Technical Tip: Use this process only with host systems that are portdependent or host systems that run on a network.
Figure 87: Sample Network Definition (SND) Form
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
375
Appendices: Form Reference
Table 40: Query Lang Retrieval Help for Network Definition (SND) Form
Where Network Definition (SND) Data Is Stored
To 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
376
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
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 88: Sample Operator Definition (SOD) Form
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
377
Appendices: Form Reference
Table 41: Query Lang Retrieval Help for Operator Definition (SOD) Form
Where Operator Definition (SOD) Data Is Stored
To 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
378
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
Speed Entry Text Definition (SPDE)
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 89: 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 Stored
To 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
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
379
Appendices: Form Reference
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 90: Sample User Help Maintenance (UHLP) Form
380
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
User Help Maintenance (UHLP)
Table 43: Query Lang Retrieval Help for User Help Maintenance (UHLP) Form
Where User Help Maintenance (UHLP) Data Is Stored
To 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.OPERAT
OR
SHRTHELP
SHRTHELP.CHANGE.OPERATOR
Process
SHRTHELP
HELP.PROCESS.LIST
Alternate Dict
SHRTHELP
HELP.ALTERNATE.DICT
Short Help
SHRTHELP
SHORT.HELP.MESSAGE
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
381
Appendices: Form Reference
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.
Note: The Update Main Remote Accounts (UMRA) form is not used
for Envision 4.8 because of changes to the Envision architecture.
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.
Note: The UURA and UNFR forms are not used for Envision 4.8
because of changes to the Envision architecture.
For more information about the Update User Remote Accounts (UURA)
form, refer to page 437.
For more information about the Remote Account New Files (UNFR) form,
refer to page 385.
382
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
Update Main Remote Accounts (UMRA)
Figure 91: Sample Update Main Remote Accounts (UMRA) Form
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
383
Appendices: Form Reference
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.
Note: The Remote Account New Files (UNFR) form is not used for
Envision 4.8 because of changes to the Envision architecture.
Figure 92: Sample Report on New/Obsolete Files (UNFP) Form
384
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
Remote Account New Files (UNFR)
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.
Note: The Remote Account New Files (UNFR) form is not used for
Envision 4.8 because of changes to the Envision architecture.
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 rerun 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.
Note: The UMRA and UURA forms are not used for Envision 4.8
because of changes to the Envision architecture.
For more information about the Update Main Remote Accounts (UMRA)
form, refer to page 382.
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
385
Appendices: Form Reference
Figure 93: 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 Stored
To 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
386
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
Overwritten & Deleted Records (UODR)
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.
Note: The Overwritten & Deleted Records (UODR) form is not used
for Envision 4.8 because of changes to the Envision architecture.
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).
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
387
Appendices: Form Reference
Figure 94: Sample Overwritten & Deleted Records (UODR) Form
388
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
Remote Account Report (URRA)
Remote Account Report (URRA)
Note: The Remote Account Report (URRA) form is not used for
Envision 4.8 because of changes to the Envision architecture.
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 95: Sample Remote Account Report (URRA) Form
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
389
Appendices: Form Reference
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 96: Sample Batch Error Report (UTBE) Form
390
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
File Indexing (UTBI)
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.
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.
For more information about the User File Index Specification (UTMI) form,
refer to page 409.
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
391
Appendices: Form Reference
Figure 97: Sample File Indexing (UTBI) Form
Envision 4.7 only
392
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
Multiple File Indexing (UTBA)
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.
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
393
Appendices: Form Reference
Figure 98: Sample Multiple File Indexing (UTBA) Form
394
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
File Creation Type Defaults (UTCD)
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 99: Sample File Creation Type Defaults (UTCD) Form
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
395
Appendices: Form Reference
Table 45: Query Lang Retrieval Help for File Creation Type Defaults (UTCD) Form
Where File Creation Type Defaults (UTCD) Data Is Stored
To 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
396
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
File Creation (UTCF)
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 100: Sample File Creation (UTCF) Form
Table 46: Query Lang Retrieval Help for File Creation (UTCF) Form
To retrieve data from
Where File Creation (UTCF) Data Is Stored
use this file
and this field
User File Specifications LookUp
UFSPECS
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
UFSPECS.ID
397
Appendices: Form Reference
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.
Example
IF 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.
398
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
UT Process Debug Activation (UTDB)
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 101: Sample UT Process Debug Activation (UTDB) Form
Envision 4.8
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
399
Appendices: Form Reference
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.
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.”
Figure 102: Sample Edit Comments (UTED) Form
400
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
BROWSE File Authorization (UTFA)
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 103: Sample Browse File Authorization (UTFA) Form
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
401
Appendices: Form Reference
Table 47: Query Lang Retrieval Help for BROWSE File Authorization (UTFA) Form
Where BROWSE File Authorization (UTFA) Data Is Stored
To retrieve data from
use this file
and this field
Authorized Directory File Name
402
UTFBLIST
UTFB.AUTH.FILE.LIST
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
Sequential File BROWSE Shell (UTFB)
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, 80character 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.
Note: This version of the form (containing Security Type) is available
in Release 18.0 for Envision 4.8 only.
Figure 104: Sample Sequential File BROWSE Shell (UTFB) Form
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
403
Appendices: Form Reference
The BROWSE functions and commands are as follows:
Functions
„
„
„
„
„
„
„
Window 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.
Commands
„
„
„
„
„
„
„
„
„
„
„
„
„
404
Lnnn. 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, July 7, 2009
© 2009 Datatel, Inc.
Job Statistics Purge (UTJP)
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 105: Sample Job Statistics Purge (UTJP) Form
Envision 4.8 only
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
405
Appendices: Form Reference
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 106: Sample Job Statistics Report (UTJR) Form
406
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
User File Information (UTMF)
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 107: Sample User File Information (UTMF) Form
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
407
Appendices: Form Reference
Table 48: Query Lang Retrieval Help for User File Information (UTMF) Form
Where User File Information (UTMF) Data Is Stored
To 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
408
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
User File Index Specification (UTMI)
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.
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.
For more information about the File Indexing (UTBI) form, refer to page 391.
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
409
Appendices: Form Reference
Figure 108: 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 Stored
To retrieve data from
use this file
and this field
User File Specifications LookUp
410
UFSPECS
UFSPECS.ID
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
Transaction Log Specification (UTML)
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 109: Sample Transaction Log Specification (UTML) Form
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
411
Appendices: Form Reference
Table 50: Query Lang Retrieval Help for Transaction Log Specification (UTML) Form
Where Transaction Log Specification (UTML) Data Is Stored
To 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
412
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
Record Security Specification (UTMR)
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 340.
Figure 110: Sample Record Security Specification (UTMR) Form
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
413
Appendices: Form Reference
Table 51: Query Lang Retrieval Help for Record Security Specification (UTMR) Form
Where Record Security Specification (UTMR) Data Is Stored
To 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
414
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
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.
Note: The Remote Account Specifications (UTRA) form is not used
for Envision 4.8 because of changes to the Envision architecture.
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.
Figure 111: Sample Remote Account Specifications (UTRA) Form
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
415
Appendices: Form Reference
Table 52: Query Lang Retrieval Help for Remote Account Specifications (UTRA) Form
Where Remote Account Specifications (UTRA) Data Is Stored
To 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
416
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
LookUp Resolution Specs (UTRD)
LookUp Resolution Specs (UTRD)
When the Envision LookUp Processor encounters one or more records in a
file that match the selection criteria, it must resolve these multiple record keys
to one or none. To do this resolution, LookUp displays pre-defined data fields
from the records on a resolution form to let end users select the appropriate
record.
Use the LookUp Resolution Specifications (UTRD) form to define the data
fields that appear on this resolution form. In addition to defining the data
fields, you can define output transformations and placement for the displayed
data.
Figure 112: Sample LookUp Resolution Specs (UTRD) Form
Displays the login ID of the person who most recently changed this resolution
form.
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
417
Appendices: Form Reference
Table 53: Query Lang Retrieval Help for LookUp Resolution Specs (UTRD) Form
Where LookUp Resolution Specs (UTRD) Data Is Stored
To 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
418
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
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.
Figure 113: Sample File Resolution Defaults (UTRE) Form
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
419
Appendices: Form Reference
Table 54: Query Lang Retrieval Help for File Resolution Defaults (UTRE) Form
Where File Resolution Defaults (UTRE) Data Is Stored
To 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
420
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
File Resolve Graphic Display (UTRG)
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 114: Sample File Resolve Graphic Display (UTRG) Form
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
421
Appendices: Form Reference
Table 55: Query Lang Retrieval Help for File Resolve Graphic Display (UTRG) Form
Where File Resolve Graphic Display (UTRG) Data Is Stored
To 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
422
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
LookUp Resolution Options (UTRO)
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 421.
Figure 115: Sample LookUp Resolution Options (UTRO) Form
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
423
Appendices: Form Reference
Table 56: Query Lang Retrieval Help for LookUp Resolution Options (UTRO) Form
Where LookUp Resolution Options (UTRO) Data Is Stored
To 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
424
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
ReRun a Procedure (UTRR)
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 116: Sample ReRun a Procedure (UTRR) Form
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
425
Appendices: Form Reference
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 117: Sample User FileSuite Information (UTSF) Form
426
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
User FileSuite Information (UTSF)
Table 57: Query Lang Retrieval Help for User FileSuite Information (UTSF) Form
Where User FileSuite Information (UTSF) Data Is Stored
To 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
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
427
Appendices: Form Reference
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 118: Sample Set Printer Characteristics (UTSP) Form
428
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
TXLOG Purge (UTTP)
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 411.
Figure 119: Sample TXLOG Purge (UTTP) Form
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
429
Appendices: Form Reference
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.
Note: The UMRA and UURA forms are not used for Envision 4.8
because of changes to the Envision architecture.
Figure 120: Sample Modify Appl VOC Files (UTVF) Form
430
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
Modify Appl VOC Files (UTVF)
Table 58: Query Lang Retrieval Help for Modify Appl VOC Files (UTVF) Form
Where Modify Appl VOC Files (UTVF) Data Is Stored
To 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
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
431
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 434.
For more information about the Modify Application VOC Files (UTVF) form,
refer to page 430.
432
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
Modify Appl VOC Misc. Items (UTVM)
Figure 121: 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 Stored
To 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, July 7, 2009
© 2009 Datatel, Inc.
433
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 122: Sample Modify Appl VOC Programs (UTVP) Form
434
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
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 Stored
To 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, July 7, 2009
© 2009 Datatel, Inc.
435
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.
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.
For more information about the TXLOG Purge (UTTP) form, refer to
page 429.
436
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
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.
Note: The Update User Remote Accounts (UURA) form is not used
for Envision 4.8 because of changes to the Envision architecture.
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 nonstandard 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 415.
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
437
Appendices: Form Reference
Figure 123: Sample Update User Remote Accounts (UURA) Form
438
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
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, July 7, 2009
© 2009 Datatel, Inc.
439
Appendices: Form Reference
Figure 124: Sample Validation Codes (VAL) Form
440
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
Validation Codes (VAL)
Table 61: Query Lang Retrieval Help for Validation Codes (VAL) Form
To retrieve data from
Where Validation Codes (VAL) Data Is Stored
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, July 7, 2009
© 2009 Datatel, Inc.
441
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 125: Sample View Batch Process Status (VBS) Form
442
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
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 Stored
To 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, July 7, 2009
© 2009 Datatel, Inc.
443
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 126: Sample View Single Batch Job Step (VBSD) Form
444
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
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 Stored
To 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, July 7, 2009
© 2009 Datatel, Inc.
445
Appendices: Form Reference
446
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
Index
From this index you can click on any entry to access the information about the topic.
A
Delete Obsolete Index Files (DOIF) form 234
ACCOUNT.PARAMETERS
System Parameters 55
Device Definition (SDD) form 356
appl.PPROCESS file 405
Dictionary Date Convert (DDCV) form 306
Application hierarchy
and screen chains 123
DIFF form 309
Audit Trail Report (UTXL) form 436
DOIF form 234
Automatically generated services 279
E
B
DHST form 308
Difference Engine (DIFF) form 309
Edit Comments (UTED) form 400
Batch Error Report (UTBE) form 390
Element, Window 30
Batch Runtime RFSPECS Refresh (BRRR) form
226
Envision Parameters Edit (EPED) form 55, 231
BROWSE File Authorization (UTFA) form 401
EPED form 55, 231
BRRR form 226
F
BSEC form 177
FHDF form 310
Build Application Security (BSEC) form 177
Field History Detail (FHDT) form 310
C
Field Label 30
Chain Usage Report (CHUS) 129
Chain Usage Report (CHUS) form 304
CHUS form 304
Field Security Definition (SCDF) form 347
File Creation (UTCF) form 397
File Creation Type Defaults (UTCD) form 395
Colleague modules
Defining parameter records for 55
File indexing 222
database 226
when conversion is complete 234
Concepts 21
File Resolution Defaults (UTRE) form 419
CONFIRM level 263
File Resolve Graphic Display (UTRG) form 421
CPAE form 86
Files
ACCOUNT.PARAMETERS 55
appl.PPROCESS 405
converting static to dynamic 196
resizing 194
SYSDEFS 67
UT.THROWN.ERRORS 263
Custom Paragraph Entry (CPAE) form 86
D
DDCV form 306
Define Cursor Keys (SKB2) form 365
Define Field History (DHST) form 308
Define Function Keys (SKB1) form 362
Define Key Functions (RS2) form 339
Define Terminal Keyboard (SKB) form 360
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
447
Index
Forms, Datatel software
Audit Trail Report (UTXL) 436
Batch Error Report (UTBE) 390
Batch Runtime RFSPECS Refresh (BRRR) 226
BROWSE File Authorization (UTFA) 401
Build Application Security (BSEC) 177
Chain Usage Report (CHUS) 304
Custom Paragraph Entry (CPAE) 86
Define Cursor Keys (SKB2) 365
Define Field History (DHST) 308
Define Function Keys (SKB1) 362
Define Key Functions (RS2) 339
Define Terminal Keyboard (SKB) 360
Delete Obsolete Index Files (DOIF) 234
Device Definition (SDD) 356
Dictionary Date Convert (DDCV) 306
Difference Engine (DIFF) 309
Edit Comments (UTED) 400
Envision Parameters Edit (EPED) 55, 231
Field History Detail (FHDT) 310
Field Security Definition (SCDF) 347
File Creation (UTCF) 397
File Creation Type Defaults (UTCD) 395
File Resolution Defaults (UTRE) 419
File Resolve Graphic Display (UTRG) 421
GUI Function Button (GUIF) 312
International Parameters (INTL) 313
Job Statistics Purge (UTJP) 405
Job Statistics Report (UTJR) 406
LKUP Resolution Specs (LPRT) 326
LookUp Resolution Options (UTRO) 423
LookUp Resolution Specs (UTRD) 417
Mag Tape Option Defaults (MTOD) 329
Menu Definition (SMD) 369
Modify Appl VOC Files (UTVF) 430
Modify Appl VOC Misc. Items (UTVM) 432
Modify Appl VOC Programs (UTVP) 434
Multiple File Indexing (UTBA) 233, 393
My Processes (MYPR) 102
Network Definition (SND) 375
Operator Definition (SOD) 377
Operator Security Report (SCOR) 351
Output Security Groups (OSGD) 146
Outstanding Processes (OPRM) 95
Outstanding Processes Inquiry (OPRI) 110
Overwritten & Deleted Records (UODR) 387
Peripheral Option Defaults (PDEF) 333
Point to Full Release Copy (PRTF) 335
PRCS.CTL Security Inquiry (PCSI) 331
Procedure List Specification (JSEL) 322
Procedure Rules Documentation (JPRT) 320
448
Procedure Sort Specification (JSRT) 324
Procedure Specification (JDEF) 315
Procedure Step Detail (JDET) 318
Process Control Maintenance (SMD2) 372
Process Handler Setup (PHSU) 89
Process Queue Management (PRQM) 91
Process Scheduling (PHTS) 97, 98
Process Scheduling (PRSC) 100
Process Security Report (SCPR) 352
Process Security Summary (PSCS) 159
Process Status File Purge (PSFP) 108
Rebuild Field History (RBFD) 336
Rebuild File History (RBFH) 337
Rebuild File Indexing (UTBI) 391
Rec Sec User Characteristics (RSUC) 340
Record Security List Specs (RPRT) 338
Record Security Setup (SCDR) 349
Record Security Specification (UTMR) 413
Record Security Test Specs (RTST) 343
Remote Account New Files (UNFR) 385
Remote Account Report (URRA) 389
Remote Account Specifications (UTRA) 415
Report on New/Obsolete Files (UNFP) 384
ReRun a Procedure (UTRR) 425
Reset Process Queue Handler (RSPH) 94
Running Processes (RPRI) 111
Screen Chaining Specification (SCSP) 126, 353
Security Class Definition (SCD) 344
Security Parameter Values (RSV) 342
Sequential File BROWSE Shell (UTFB) 403
Set Printer Characteristics (UTSP) 428
Speed Entry Text Definition (SPDE) 379
Transaction Log Specification (UTML) 411
TXLOG Purge (UTTP) 429
UNIX_CONTROL Record Editing (UCRE) 67
Update Main Remote Accounts (UMRA) 382
Update User Remote Accounts (UURA) 437
User File Index Specification (UTMI) 229, 409
User File Information (UTMF) 407
User FileSuite Information (UTSF) 426
User Help Maintenance (UHLP) 380
UT Process Debug Activation (UTDB) 264, 288,
398
Validation Codes (VAL) 439
View Batch Process Status (VBS) 442
View Single Batch Job Step (VBSD) 444
Function keys
and screen chains 123
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
Index
G
Modify Appl VOC Files (UTVF) form 430
Generated Runtime Diagnostic Services (GRDS)
system 262
Modify Appl VOC Misc. Items (UTVM) form 432
GRDS log 267
how to read 270
MTOD form 329
GRDS system
advantages 264
log 267
on-demand diagnostics 266
overview 262
My Processes (MYPR) form 102
Group, Window 29
Network Definition (SND) form 375
GUI Function Button (GUIF) form 312
O
GUIF form 312
Operator Definition (SOD) form 377
H
Operator Security Report (SCOR) form 351
History logging 221
OPRI form 110
I
OPRM form 95
Index Storage Field Report (ISFR) 227
Output Security Groups (OSGD) form 146
International Parameters (INTL) form 313
Outstanding Processes (OPRM) form 95
INTL form 313
Outstanding Processes Inquiry (OPRI) form 110
ISFR report 227
Overwritten & Deleted Records (UODR) form 387
J
P
JDEF form 315
PCSI form 331
JDET form 318
PDEF form 333
Job Statistics Purge (UTJP) form 405
Peripheral Option Defaults (PDEF) form 333
Job Statistics Report (UTJR) form 406
JPRT form 320
Phantom processor
description 83
JSEL form 322
PHSU form 89
JSRT form 324
PHTS form 97, 98
L
Point to Full Release Copy (PRTF) form 335
Label, Field 30
Modify Appl VOC Programs (UTVP) form 434
Multiple File Indexing (UTBA) form 233, 393
MYPR form 102
N
OSGD form 146
PRCS.CTL Security Inquiry (PCSI) form 331
M
Procedure
Dictionary Date Convert (DDCV) 306
Job Statistics Purge (UTJP) 405
Multiple File Indexing (UTBA) 393
Point to Full Release Copy (PRTF) 335
Rebuild File Indexing (UTBI) 391
TXLOG Purge (UTTP) 429
Update Main Remote Accounts (UMRA) 382
Update User Remote Accounts (UURA) 437
Mag Tape Option Defaults (MTOD) form 329
Procedure List Specification (JSEL) form 322
Menu Definition (SMD) form 369
Procedure Rules Documentation (JPRT) form 320
Label, Window 30
LKUP Resolution Specs (LPRT) form 326
LookUp Resolution Options (UTRO) form 423
LookUp Resolution Specs (UTRD) form 417
LPRT form 326
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
449
Index
Procedure Sort Specification (JSRT) form 324
Procedure Specification (JDEF) form 315
Procedure Step Detail (JDET) form 318
Process 23
Process Control Maintenance (SMD2) form 372
Process handler 83
inquiry forms 110
managing processes 95
managing queues 88
process status file records 104
setting up 88
submitting a task 84
batch process or report 84
VOC paragraph 86
system administrator 87
task 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 352
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 335
PSCS form 159
PSFP form 108
PSTR report 105
R
Remote Account New Files (UNFR) form 385
Remote Account Report (URRA) form 389
Remote Account Specifications (UTRA) form 415
Remote accounts
recovery procedures 249
Report
Audit Trail Report (UTXL) 436
Batch Error Report (UTBE) 390
Chain Usage Report (CHUS) 129
Difference Engine (DIFF) 309
Index Storage Field Report (ISFR) 227
Job Statistics Report (UTJR) 406
LKUP Resolution Specs (LPRT) 326
Operator Security Report (SCOR) 351
Overwritten & Deleted Records (UODR) 387
Procedure Rules Documentation (JPRT) 320
Process Security Report (SCPR) 352
Process Security Summary (PSCS) 159
Process Status Report (PSTR) 105
Record Security List Specs (RPRT) 338
Record Security Test Specs (RTST) 343
Remote Account Report (URRA) 389
Report on New/Obsolete Files (UNFP) 384
Sequential File BROWSE Shell (UTFB) 403
Report on New/Obsolete Files (UNFP) form 384
ReRun a Procedure (UTRR) form 425
Reset Process Queue Handler (RSPH) form 94
Resizing files 194, 196
RPRI form 111
RPRT form 338
RS2 form 339
RBFD form 336
RSPH form 94
RBFH form 337
RSUC form 340
Rebuild Field History (RBFD) form 336
RSV form 342
Rebuild File History (RBFH) form 337
RTST form 343
Rebuild File Indexing (UTBI) form 391
Running Processes (RPRI) form 111
Rec Sec User Characteristics (RSUC) form 340
S
Record Security List Specs (RPRT) form 338
Record Security Setup (SCDR) form 349
Record Security Specification (UTMR) form 413
Record Security Test Specs (RTST) form 343
450
Recovery
general guidelines 249
general procedures 249
SCD form 344
SCDF form 347
SCDR form 349
SCOR form 351
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
Index
SCPR form 352
UODR form 387
Screen Chaining Specification (SCSP) form 126,
353
Update Main Remote Accounts (UMRA) form 382
Screen chains
application hierarchy 123
function keys 123
procedure for defining 127
procedure for reporting on 129
security 122
URRA form 389
SCSP form 126, 353
User Help Maintenance (UHLP) form 380
SDD form 356
UT Process Debug Activation (UTDB) form 264,
288, 398
Security
and screen chains 122
Update User Remote Accounts (UURA) form 437
User File Index Specification (UTMI) form 229,
409
User File Information (UTMF) form 407
User FileSuite Information (UTSF) form 426
UT.THROWN.ERRORS file 263
Security Class Definition (SCD) form 344
UTBA form 233, 393
Security Parameter Values (RSV) form 342
UTBE form 390
Sequential File BROWSE Shell (UTFB) form 403
UTBI form 391
Set Printer Characteristics (UTSP) form 428
UTCD form 395
SKB form 360
UTCF form 397
SKB1 form 362
UTDB form 264, 288, 398
SKB2 form 365
UTED form 400
SMD form 369
UTFA form 401
SMD2 form 372
UTFB form 403
SND form 375
UTJP form 405
SOD form 377
UTJR form 406
SPDE form 379
UTMF form 407
Speed Entry Text Definition (SPDE) form 379
UTMI form 229, 409
Static files, converting to dynamic 196
UTML form 411
Status line 30
UTMR form 413
SYSDEFS file 67
UTRA form 415
T
UTRD form 417
Transaction Log Specification (UTML) form 411
TXLOG Purge (UTTP) form 429
U
UTRE form 419
UTRG form 421
UTRO form 423
UTRR form 425
UCRE form 67
UTSF form 426
UHLP form 380
UTSP form 428
UMRA form 382
UTTP form 429
UNFP form 384
UTVF form 430
UNFR form 385
UTVM form 432
UNIX_CONTROL Record Editing (UCRE) form
67
UTVP form 434
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.
UTXL form 436
451
Index
UURA form 437
V
VAL form 439
Validation Codes (VAL) form 439
VBS form 442
VBSD form 444
View Batch Process Status (VBS) form 442
View Single Batch Job Step (VBSD) form 444
W
WEEKLY.UDT.FILE.ANALYSIS (WUFA) utility
193
benefits 196
excluding files 200
functions 194
output items 195
resizing files 194, 196
workflow 196
WEEKLY.UDT.INDEX.ANALYSIS (WUIA)
utility 193, 201
output items of logical check 209
output items of physical check 206
recommendations 212
setting up paragraphs 213
understanding 201
Window Element 30
Window Group 29
Window Label 30
WUFA utility 193
benefits 196
excluding files 200
functions 194
output items 195
resizing files 194, 196
workflow 196
WUIA utility 193, 201
output items of logical check 209
output items of physical check 206
recommendations 212
setting up paragraphs 213
understanding 201
452
Runtime Administration, July 7, 2009
© 2009 Datatel, Inc.