Unify ACCELL/IDS Reference

Transcription

®
Unify ACCELL /IDS
Reference
© 1987, 2000, 2002 Unify Corporation. All rights reserved.
No part of this document may be reproduced, transmitted, transcribed, stored in a retrieval system, or
translated into any language or computer language, in any form or by any means, electronic, mechanical,
magnetic, optical, chemical, manual, or otherwise without the prior written consent of Unify Corporation.
Unify Corporation makes no representations or warranties with respect to the contents of this document
and specifically disclaims any implied warranties of merchantability or fitness for any particular purpose.
Further, Unify Corporation reserves the right to revise this document and to make changes from time to
time in its content without being obligated to notify any person of such revisions or changes.
The Software described in this document is furnished under a Software License Agreement. The
Software may be used or copied only in accordance with the terms of the license agreement. It is against
the law to copy the Software on tape, disk, or any other medium for any purpose other than that
described in the license agreement.
The Unify Corporation Technical Publications Department values and appreciates any comments you
may have concerning our products or this document. Please address comments to:
Product Manager
Unify Corporation
2101 Arena Boulevard, Suite 100
Sacramento, CA 95834
(800) 24-UNIFY • (916) 928-6400 • FAX (916) 928-6401
Unify DataServer, Unify eWave, Unify VISION, Unify WebNow! and the Unify logo are trademarks of
Unify Corporation in the United States and other countries. Unify and ACCELL are registered
trademarks of Unify Corporation in the United States and other countries. Other brand or product names
shown are trademarks of their respective owners. Printed in U.S.A.
Part Number: 7065-01
Contents
Chapter 1: Introduction to ACCELL/IDS
Introduction
13
13
What is ACCELL/IDS?
15
How to work with ACCELL
What is an application?
17
18
How to create an ACCELL/IDS application
Terms used in this manual
General terms
Form terms
Variable terms
22
29
32
34
Standard form
34
Master Application form
Zoom form
22
24
Database terms
Form types
20
34
34
Multi-Occurrence form
Help form
34
Error form
35
34
Chapter 2: Introduction to application design
Introduction
37
Application design basics
ACCELL/IDS design tips
37
38
Chapter 3: ACCELL/Environment
Introduction
37
45
45
ACCELL/Environment forms and menus
Creating applications
45
47
Help for the ACCELL/Environment
48
Setting ACCELL/Environment variables
49
iii
49
Entering the ACCELL/Environment
Selecting the current application
51
57
Selecting the current form
Entering different parts of ACCELL/IDS
Chapter 4: ACCELL/Manager
Introduction
65
65
Screen organization
68
68
System areas
70
Status information messages
72
Function key labels
Error handling
74
74
Types of error messages
74
Types of errors
75
Information levels
User modes
78
78
Add/Update/Delete mode
Find mode
79
User commands
84
User command execution sequence
84
87
User command descriptions
Chapter 5: ACCELL/Generator
99
Introduction to the ACCELL/Language
Creating forms
99
101
101
Defining form characteristics
Specifying Next Form characteristics
101
Sizing and locating the form window
101
Adding Form Trim
101
Defining field characteristics
102
Defining Advanced Field characteristics
Defining help forms
102
102
Marking repeating areas
102
Exiting ACCELL/Generator
103
Help for the ACCELL/Generator
Entering the Generator
iv
60
63
Exiting the ACCELL/Environment
103
103
Unify ACCELL/IDS Developer’s Reference
103
Specifying NEXT FORM Characteristics
109
Sizing and Locating Forms
110
Adding form trim
113
Using color graphics
114
123
Setting session defaults
126
Editing new forms
119
123
Creating help forms
127
Exiting the Generator
128
Generator commands
129
Generator command summary
129
131
Generator command descriptions
Chapter 6: ACCELL/Language overview
Introduction to the ACCELL/Language
Variables
107
141
141
142
ACCELL/IDS Variable classes
142
143
Variable names and references
144
Variable declaration
Scope of variables
145
146
Determining variable type
Variable assignment compatibility
ACCELL/IDS attributes
Variable attributes
148
149
Target variable attributes
150
Screen variable attributes
152
Form attributes
147
154
ACCELL/IDS name classes
156
ACCELL/IDS system functions and variables
ACCELL/IDS system functions
THE status$() FUNCTION
String comparison masks
181
185
ACCELL/IDS system variables
Contents
158
158
189
v
Data types
193
ACCELL type conversion functions
Operators
194
196
Arithmetic and concatenation operators
201
Relational operators
Logical operators
202
Bitwise operators
202
Chapter 7: ACCELL/Language sections
Introduction
198
205
205
Master Application Form control section
Application header
209
Before application section
209
After application section
210
CHOOSE FIRST FORM section
210
Other language sections
Standard form control section
Form declaration
211
213
214
BEFORE FORM section
214
ON NEXT FORM section
ON PREVIOUS FORM section
AFTER FORM RETURN section
214
214
215
AFTER ZOOM section
CHOOSE NEXT FORM section
ON EXIT section
215
218
Find Language sections
219
Add Language sections
223
Update Language sections
Record Language sections
Field Language sections
226
227
Delete Language sections
229
231
Chapter 8: ACCELL/Language statements
Introduction
235
235
Database statements
vi
207
209
236
Screen statements
238
Control statements
239
ACCELL/IDS statement descriptions
242
CHOOSE FIRST FORM and CHOOSE NEXT FORM
244
CLOSE PIPELINE
245
COMMIT
245
CREATE PIPELINE
246
DELETE
247
DISABLE ZOOM
247
DISPLAY
DISPLAY TRIM
252
ENABLE ZOOM
254
ERASE TRIM
256
257
EXTERN
258
FOR
IF
260
INPUT
262
264
INSERT
NEXT ACTION
265
265
REFRESH SCREEN
266
REJECT OPERATION
REJECT RECORD
267
REPAINT SCREEN
267
268
REPEAT
269
RESTART ON FIELD
SET
270
SET/SELECT FIELD
SLOCK
271
275
SWITCH
277
UNLOCK
279
UPDATE CURRENT RECORD
Using the AFA unique option
WHILE
XLOCK
280
281
282
WRITE PIPELINE
284
285
Chapter 9: Advanced application design
ACCELL/IDS files
287
287
Types of ACCELL/IDS files
Contents
243
287
vii
289
ACCELL/IDS file processing
292
Environment variables required by ACCELL/IDS
Environment variables
293
293
How to set environment variables
Using environment variables
294
Basic environment variables
295
297
Advanced environment variables
ACCELL/IDS command level development
310
Entering the ACCELL/Generator from the operating system
Compiling language scripts from the operating system
311
312
Combining forms and language scripts from the operating system
Linking files from the operating system
314
Building ACCELL/IDS executables with make
314
316
Moving an application
317
Renaming an application
Registering ACCELL/IDS applications
Accessing multiple databases
318
319
Setting up end user access to an application
Listing form defaults and help text
User functions
326
327
330
User functions and applications
330
331
A sample user function
Combining the application and the user function
User function conventions
339
341
341
Pipeline statement syntax
Controlling pipeline output format
Transaction control and locking
343
344
ACCELL/IDS transaction management
344
Specifying a form's transaction information
Using interactive operations in a transaction
356
361
Using non-interactive operations in a transaction
Application optimization
Memory optimization
371
381
Performance optimization
viii
333
335
Notes on writing user functions
Pipelines
314
381
391
395
Diagnostic guide
Writing batch applications
396
396
Considerations
397
Sample Application
Customizing ACCELL/IDS error forms using PAINTHLP
407
PAINTHLP ERRORS
Chapter 10: Runtime execution
Introduction
411
411
Clear To Find and Clear To Add operations
Find and Add/Update/Delete modes
412
Application, Form and Field execution
Application execution
Form execution
417
Field Execution
421
User Modes execution
424
424
425
User command execution notes
CLEAR TO ADD
427
CLEAR TO FIND
427
429
429
NEXT RECORD
NEXT FORM
NEXT SET
430
430
PREVIOUS FIELD
431
PREVIOUS RECORD
PREVIOUS FORM
PREVIOUS SET
PREVIOUS TAB
RECALL FIELD
Contents
427
428
NEXT FIELD
TAB
416
416
FIND
411
412
Execution of a form
Find mode
406
431
431
432
432
433
433
ix
ACCELL/Language grammar 435
Introduction
435
436
How to use the grammar
Typographical conventions
436
ACCELL/Language scripts
438
Language sections
Statements
443
Specifiers
447
Expressions
Operators
440
449
451
Variables and constants
Constants
452
453
Attributes, characteristics, and system functions and variables
Attributes
455
455
Characteristics
457
459
System functions and variables
Setting up the system 463
Introduction
463
Additional termcap file entries
termcap entry formats
464
465
Screen SIZE entries
466
Embedded attributes
467
467
Types of terminals
Setting up termcap for an embedded terminal
468
Embedded terminals and ACCELL/IDS forms
469
Combined and independent attributes
Combined attributes
474
Independent attributes
Graphics capabilities
unicap file entries
475
475
Customizing function key names
Special considerations
476
476
Developer’s command summary
ACCELL/IDS/Manager commands
x
472
472
477
477
ACCELL/IDS/Generator commands
Contents
478
xi
Unify ACCELL/IDS Error messages 479
xii
ACMB error messages
479
ALNK error messages
483
ACPL error messages
488
Chapter 1: Introduction to ACCELL/IDS
1.1 Introduction
Welcome to the ACCELL/IDS Reference Manual. This manual contains information
describing how all the parts of ACCELL/IDS work both individually and together.
Before you begin using the reference manual and developing your applications, work
through the ACCELL/IDS Developer's Tutorial and ACCELL/IDS User's Tutorial to get
a feel for ACCELL/IDS.
Start using this manual by reading the first two chapters. They provide valuable
information on how ACCELL/IDS works and they give you guidelines for developing
your own applications effectively.
This manual is divided into ten major chapters, three appendixes, a glossary, and an
Index, as described below:
•
Chapter 1, Introduction, gives an overview of information covered in the
manual, describes the overall structure of ACCELL, and defines some key
terms and concepts used throughout the manual.
•
Chapter 2, Introduction to Application Design, provides guidelines for
designing applications and offers specific tips on using ACCELL/IDS
effectively.
•
Chapter 3, ACCELL/Environment, describes the different parts of the
ACCELL/Environment and explains how to build applications using the
ACCELL/Environment menus.
•
Chapter 4, ACCELL/Manager, outlines the different parts of the ACCELL/IDS
runtime environment handled by ACCELL/Manager. Topics include screen
organization, error message handling, and user modes and commands.
•
Chapter 5, ACCELL/Generator, explains ACCELL's visual application
generator and provides information on creating forms.
13
14
•
Chapter 6, ACCELL/Language Overview, introduces the basic elements of the
ACCELL/Language–the variables, attributes, system functions, data types,
and operators used in ACCELL/Language scripts–and explains how they work
together.
•
Chapter 7, ACCELL/Language sections, describes all the sections used in
ACCELL/Language scripts and gives examples of how each one is used.
•
Chapter 8, ACCELL/Language Statements, describes all of the ACCELL/IDS
statements used in ACCELL/IDS Language sections, shows their syntax, and
gives examples of how each one is used.
•
Chapter 9, Advanced Application Design, explains how to use ACCELL/IDS
directly from the operating system command prompt–a level of operation
intended for experienced developers only–and describes advanced uses of
User Functions and Pipeline statements.
•
Chapter 10, Runtime Execution Information, gives specific execution
information for different language sections, user modes, and user commands.
This detailed information is intended primarily for experienced developers.
•
Appendix A, ACCELL/IDS Language/Grammar, lists all the syntax for the
ACCELL/IDS statements, Language sections, and statement elements.
•
Appendix B, Setting Up the System, outlines procedures performed when
installing ACCELL/IDS or an ACCELL/IDS application–specifically termcap
and unicap file entries. Included is a Developer's Command Summary that
lists both ACCELL/Manager and Generator commands.
•
Appendix C, Error Messages, lists and describes all ACCELL/IDS error
messages.
•
The Glossary provides comprehensive definitions of the terms used
throughout this manual.
1.2 What is ACCELL/IDS?
ACCELL/IDS is a unique applications development tool that combines the best
features of application generators, relational DBMS, windowing interfaces and fourth
generation languages into a single, powerful package. ACCELL/IDS is divided into
five modules that work together in an integrated applications development system as
shown in Figure 1.
EN
ME
RO
VI
NT
MANAGER
S
GE
M
B
E
NE
D
AG
RA
U
G
TO
R L AN
Figure 1. The Parts of ACCELL/IDS
Each ACCELL/IDS module performs a unique function in applications development:
•
ACCELL/Environment provides a convenient series of forms and menus that
give you access to different parts of ACCELL. Working in the ACCELL/
Environment, you can easily edit or create forms with the ACCELL/Generator
or open an ACCELL/Language script in the editor of your choice. The
ACCELL/Environment also takes care of managing and processing your files
automatically so you can concentrate on developing your application. It also
includes a source management database to ease maintenance of
applications.
Introduction to ACCELL/IDS
15
16
•
ACCELL/Generator is a visual application generator designed to work like an
ACCELL/IDS application. ACCELL/Generator commands let you create forms
on the screen exactly as you want them to appear in your application. You
specify characteristics of forms and fields by filling in ACCELL/Generator
forms. Each form is stored in a separate file.
•
ACCELL/Language is a fourth generation language that lets you enhance the
forms created in the ACCELL/Generator with logic and computational power.
You create and edit ACCELL/Language scripts using your own system editor.
ACCELL/Language for each form is stored in a separate file. Additionally,
ACCELL/IDS supports the C language preprocessor on ACCELL/Language
scripts.
•
ACCELL/Manager is the runtime component of ACCELL. It automatically
takes care of the details of runtime processing for you. When an application
runs, the ACCELL/Manager serves as a link between the end user running the
application, the compiled ACCELL/Language and forms that make up the
application, and the database used by the application. The ACCELL/Manager
accepts user commands, executes the appropriate compiled ACCELL/IDS
code, displays forms in the appropriate order, and interacts with the database.
•
ACCELL/DBMS is Unify DataServer/ELS, a powerful relational database
management system that handles the data storage and retrieval needs of
sophisticated applications. You define and create databases for your ACCELL/
IDS applications with the ACCELL/DBMS utilities. Using SQL, RPT, and third
generation language programs, you can also utilize your database in a more
traditional fashion, generating reports and sending output to other sources.
1.3 How to work with ACCELL
When you are developing applications, you are working within the ACCELL/IDS
Development Environment (ACCELL/Environment). When you or an end user are
running an application, ACCELLIDS is operating inside the Runtime Environment.
ACCELL/Manager serves as the manager of the Runtime Environment, interacting
with the end user and modifying the database as necessary.
Figure 2 shows how both the Development and Runtime Environments fit together to
form one integrated environment.
Development Environment
ACCELL/Environment
ACCELL/Generator
ACCELL/Language Editor
ACCELL/SmartlinkTMCompiler
Runtime
Environment
ACCELL/Manager
ACCELL/DBMS Runtime
ACCELL/DBMS Report Writer
ACCELL/DBMS SQL Query Language
ACCELL/DBMS Development
Figure 2. The ACCELLIDS Environment
17
1.4 What is an application?
Applications are sets of forms for entering and retrieving information from a database.
An application is usually designed to accomplish an integrated series of tasks, such
as keeping track of prospective sales, entering orders, or managing inventories.
Applications consist of form files created in ACCELL/Generator and optional ACCELL/
Language scripts set up with your system editor. See Figure 3.
HJKLLKJH
HJKLLKJH
HJKLLKJH
HJKLLKJH
HJKLLKJH
JKLKKHHJ
HJKLLKJH
JKLKKHHJ
HJKLLKJH
JKLKKHHJ
HJKLLKJH
HJKLLKJH
JKL;JHN
M JKL;JHN
JKL;JHN
M
M
HJKLLKJHJKLKKHHJKKL
JHFHFJK
FKDJJH
KKLDHS
LKJHJK
JHFL
FKDJ
DHFJHNM
DHFJKJ
JDHF DHSKL;
KHLL;K
KJLMNE
JFHDKFJ
DHFKCS DHFJ
DHFJ
HJKLLKJHJKLKKHHJKKL
Figure 3. An ACCELL/IDS Application
The ACCELL/Environment automatically processes these application files into a
working application when you select the appropriate options from the ACCELL/
Environment menus.
You can make extensive use of the ACCELL/Language to create sophisticated
applications, or you can create simple multi-form applications that require no
Language at all. Whatever type of application you need, ACCELL/IDS lets you create
an attractive, consistent, and easy-to-use user interface.
18
Figure 4 shows a sample series of forms created with the ACCELL/Generator.
replace
stored
update
record 1 of 10
RECORDS FOUND
COMPANY: Yujikawa Limited
SALES REP#: 3
ADDRESS: 115 Wedgewood Court
NAME: A Kurasaki
Suite 250
PHONE: (415) 645-1212
CITY: San Francisco
STATE: CA
ZIP: 90403
MAIN PHONE: (415) 765-8800
CONTACT:
MAP:
LEAD: Opening new branch office in Irvine, CA.
Y Kazi
FOUND: 10/07/85 EST. VALUE: 22000.00 PROB: 55%
VP Facilities
STATUS: 1
BUY DATE: 12/01/85 NEXT: 10/21/85
ext 90
MAP:
PROGRESS TO DATE
MAP:
10/7/85 - Excellent prospect for our first contract with this company.
They are opening new branch and need offices furnished. If we land
this contract, I'm sure we'll get more business from them. They are
interested in standardizing the look of all their corporate offices
(and there are 5 of them), so if we give them good results on the new
branch, they will probably want to have their old office re-furnished.
We might be asked to work with their architectural design firm, but
that will not be
Enter comments on prospect.
F1-Prv Form F2-Nxt Form F3-Prv Rec
F4-Nxt Rec
F5-Fld Help
F10-More Key
Figure 4. Sample Forms Created With ACCELL/IDS Generator
19
1.5 How to create an ACCELL/IDS application
The process of developing applications with ACCELL/IDS is quite simple, as
summarized below:
1. Define the database tables and fields and create the database using ACCELL/
DBMS menus. See the DBMS Developer's Tutorial Manual and the DBMS
Developer's Reference Manual for information on creating and maintaining a
database.
2. Create the forms for your application using the ACCELL/Generator.
Remember each form has its own defaults and can be connected
automatically to other forms, so you can develop simple applications and
prototypes very quickly. In fact, if you are working with a relatively simple
application, your prototype may be complete at this stage of the development
process. If so, you are ready to use the SmartlinkT Compiler described in step
5, below.
3. Create an ACCELL/Language script for any form that needs additional
computation and processing logic. Again, Language for individual forms is
entered in separate files using the system editor.
4. Define reports using ACCELL/Language PIPE statements and the ACCELL/
DBMS RPT Report Writer.
5. Use the SmartlinkT Compiler to compile and merge the application files.
6. Test run the application to see how it works.
7. Go back and edit the form or Language script if any refinements are
necessary.
8. Recompile and run the application if any modifications were made. This is a
very rapid process, since the compiler is smart enough to only compile the
modified forms.
There are two ways to create applications in ACCELL:
20
•
from within the ACCELL/Environment
•
directly from the operating system prompt
The ACCELL/Environment method lets you use a simple series of menus to enter the
ACCELL/Generator and to set up ACCELL/Language files in the system editor. It also
takes care of all the file processing for you automatically and is recommended for
most developers. For more information, see Chapter 3, ACCELL/Environment.
With the operating system method, you do all the required file processing yourself.
Chapter 9, Advanced Application Design, describes how to work at the operating
system level.
21
1.6 Terms used in this manual
The following terms are used throughout this manual to refer to different parts of
ACCELL/IDS and the database. Careful reading will help you understand the
concepts explained in this manual. Keep in mind that some of the definitions use
terms that appear later in this chapter; read all the definitions to ensure that you
understand all the concepts. The terms are grouped into four categories: general,
form, database, and variable.
General terms
Application
An application is a set of forms and associated ACCELL/Language designed to
accomplish an integrated task, such as keeping track of orders, inventory, or
prospective clients. For example, a Prospect and Order Tracking application might
contain the following forms, as shown in Figure 5.
ORDER
LEAD
COMPANY
ITEM
INVENTORY
INVENTORY
TEXT
CONTRACT
SALES
Figure 5. Sample ACCELL/IDS Application
22
Screen
The term screen is used to refer to the computer terminal display. The screen is
divided into the following areas:
•
The two system areas
•
The application area
The system areas are used exclusively by ACCELL/IDS to display system messages
and valid function key assignments. With the new ACCELL/IDS version 1.3, you can
switch off and reposition system areas. The application area is used and controlled by
the running ACCELL/IDS application. See Figure 6. For more information on adjusting
the system areas, see Chapter 9.2, Environment Variables, under AMGRINIT.
application area
replace
not stored
system area
find
Athena Development
SALES REP#: 7
5800 S. W. Washington St.
NAME: G. Moore
PHONE: (415) 645-1214
CITY: Portland
STATE: OR
ZIP: 97210
MAIN PHONE: (503) 246-2400
CONTACT:
MAP:
M Bennett
Purchasing Manager
ext 2406
COMPANY:
ADDRESS:
Enter the company name.
F1-Prv Form
F2-Nxt Form
F3-Find
F5-Fld Help
F10-More Key
23
Figure 6. ACCELL/Ids Screen Organization
Attribute
An attribute describes a characteristic of a screen, form, field, or variable. Attributes
specify, for example, video display characteristics and formats for user input.
Form terms
Form
The form is the basic building block of the application. It is similar in appearance to a
paper form, though it does much more. It can have various fields and Language
associated with it as needed. Forms can be overlaid, and can occupy any part of the
screen that is not reserved for system displays and messages. See Figure 7.
FORM
COMPANY: Athena Development Corp.
ADDRESS: 5800 S.W. Washington St.
CITY: Portland
MAIN PHONE: (503) 246-2400
CONTACT:
M Bennett
Purchasing Manager
ext. 2406
SALES REP#: 7
NAME: G. Moore
PHONE: (415) 645-1214
STATE: OR
ZIP: 97210
MAP:
MAP:
Figure 7. ACCELL/Ids Form
Many forms can be displayed on the screen while an ACCELL/IDS application is
running. Forms provide space for screen fields, which are used to enter and retrieve
information. See subsection Form Types, for a description of all the types of
ACCELL/IDS forms.
24
Form window
The form window is the screen area occupied by a form, and its screen fields and trim.
A form window always includes the border surrounding the displayed information. A
terminal's screen size determines a window's maximum size. The position and size of
the form window is determined from within the ACCELL/Generator. See Figure 8.
FORM WINDOW
replace
stored
update
record 1 of 10
RECORDS FOUND
F4-Nxt Rec F5-Fld Help F10-More Key
Figure 8. ACCELL/IDS Form Window
25
Form trim
Any component information on a form that is not a screen field is form trim. This
includes lines, headings, and screen field prompts, for example, COMPANY. See
Figure 9.
COMPANY:
ADDRESS: .
CITY:
MAIN PHONE:
CONTACT:
STATE:
SALES REP#:
NAME:
PHONE:
ZIP:
Trim
(borders and headings)
MAP:
MAP:
Figure 9. ACCELL/IDS Form Trim
Current form
The form currently being executed by ACCELL/IDS is the current form. If more than
one form is displayed on the screen at a time, the cursor position marks the current
form.
Active form
All the forms that appear on the screen, or that may be overlaid (and may not be
visible), are active forms.
Screen field
Screen fields are the area on a form used to display and accept information. There
are two types of screen fields:
26
•
Database screen fields
•
Non-database screen fields
Database screen fields display information stored in the database, while nondatabase screen fields display information calculated from other values stored in the
database. Non-database display fields may contain averages or totals, or information
from other database tables. See Figure 10.
Screen fields are associated with different types of ACCELL/IDS variables to display
and accept different types of information. Screen field information is displayed in field
windows.
Athena Development Corp.
5800 S.W. Washington St.
Portland
(503) 246-2400
OR
7
G. Moore
(415) 645-1214
97210
M Bennett
Purchasing Manager
ext. 2406
Screen fields
Figure 10. ACCELL/IDS Screen Fields
Field windows
The area used to display a single screen field on a form is a field window. A field
window may be smaller than the length of the screen field. In this case, the user can
scroll the window display horizontally to see the rest of the field's value. This scrolling
feature can be specified in the ACCELL/Generator in a matter of seconds. It is
especially useful in conserving screen spaces for fields that only occasionally require
27
long entries. Field windows may not overlap and are limited to a single line. See
Figure 11.
Field windows
Figure 11. ACCELL/IDS Field Windows
Multi-occurrence forms
Multi-occurrence forms are standard forms that can display more than one record at a
time. See Figure 13.
28
Database terms
Database
A database is the collection of information used by an ACCELL/IDS application.
ACCELL/IDS databases are divided into tables, records, and fields, as shown in Figure
12.
NEXTNUM
ALTADD
TEXT
Database
LEADS
CONTACT
EMPLOYEE
COMPANY
ITEMS
ORDERS
NVENTRY
Field
value
No Desc Cost Price On Hand Order
Field
1003 LAMP $14.00
$39.00
12
20
rd
co
e
R
Table
Figure 12. Parts of a Relational Database
Table
The largest division of a relational database, also called a relation. It is made up of
records of the same type. For example, a company table might contain records storing
29
the names and addresses of various companies. Each record in a table contains a
value for each field in that table.
Record
A related, specific group of field values in a relational database table, that describes a
specific entity, also called a row or a tuple. A record includes an entry for each of the
fields in the database table it belongs to. For example, a record might contain the
name, address, and phone number of a particular company. Each record must have at
least one unique identifying field or group of fields.
Field
The smallest division of a relational database used for storing information, also called
a column or an attribute. For example, one field in a company table might store the
names of companies, and another field might store phone numbers. All the records in
a table contain entries for the same group of fields.
Another way of thinking about fields is as classifications of data: Information in a
record is divided into classes, such as name information and phone number
information. Each class or group of information is known as a field. Values contained
in fields can be displayed on forms or used internally in ACCELL/Language files.
Fields can be associated with different types of ACCELL/IDS variables to perform
different tasks.
Target table
The database table that is searched and updated automatically by a form created with
the ACCELL/Generator. Forms can also search and update non-target database
tables if you add ACCELL/Language statements.
Target record
A record within the target table.
30
Selected set
The set of target records that can be displayed on a form with the NEXT RECORD
and PREV RECORD user commands. Records become part of the selected set when
they are found by a database search, or when they are added to the database by
users. The selected set may be empty if no records were found or added.
Current set
That portion of the selected set displayed on the screen. The current set can be
considered a window through which you can view the selected set. For forms that
display more than one record, or multi-occurrence forms, the current set can contain
many records, as follows. See Figure 13.
Current
Set
asd fg
jlkadfg
sd fgfdg
fgh wdfh
whwfgh
fghgfjnh
rgewrgh
piusdfhb wgf
qef gqef
aglkjdfg
adfg afd;
rgdq g
grd gh
eqrdh rt
fg jt
puih
lkjfdg
gqerj
adglkjd; lk
jlkfgdfq
qrgh h
g
erth
t jhtrwjh
pkhj
q p;oidfgb
rfg qefdg
f ghgh
grggj
hdf
qgg r
qerh
wrthtr
piu
pfg
gqer
sdfkladsg klj
asdertfb
sdfsdfg
asd
ljka
asdfg
jlkadfg
sdfgfdg
fghwdfh
whwfgh
fghgfjnh
rgewrgh
piusdfhbwgf
qefgqef
asdj asdfklj
adafgg
wtdewrtt
fasdfas
adskj
aglkjdfg
adfg afd
rgdq g
grd gh
eqrdh rt
fgjt
puih
lkjfdg
gqerj
asdklasd
sfgh
etsdfgk
dfasdk
alkjasd
adglkjdlk
lkj lkfg df
qrgh h
g
erth
tjhtrwjh
pkhj
qoidfgb
rfg qefdg
fla
dfgg
qerg
we we
fgasd
fghgh
grggj
hdf
qggr
qerh
wrthtr
piu
pfg
gqer
sdfkladsg klj
asderb
sdfsdfg
ljkas
asdfg
jlkdfg
grggjsdfasd
asdjasdfklj
afdafgg
wtdewrtt
adskj
aglkjdfg
adfgafd
kjlsmjkjjh
asd klasd
sfgh
etsdfg
alkjasd
adglkjdlk
lkjlkfgdfq
irtjgh
fla
dfgg
wewe
fgasd
fghgh
fghet
iuh
Selected
Set
Figure 13. Current Set and Multi-Occurrence Forms
31
Current record
The target record currently displayed on a form, or the target record on which the
cursor is positioned for multi-occurrence forms. The current record may change as the
result of commands issued by the end user such as NEXT RECORD or PREV
RECORD.
Find
A database search requested by the application user with a FIND command.
Optional search criteria can be specified by the user, as well as in ACCELL/
Language.
Transaction
A transaction consists of a logical unit of work done by an end user on a form or group
of forms. During a transaction, certain records in the database may be protected or
locked from other users working with the same database. At the end of each
transaction, these locks are released and the transaction end is noted in the ACCELL/
DBMS transaction log for future reference.
Transactions are used to guarantee that the actions of one user do not interfere with
those of another, and to permit recovery of the database to a logically consistent point
in case of system failure. They protect the database by automatically locking certain
records.
Two transaction level settings are available to accommodate the amount of protection
a transaction needs. See Chapter 7.3, under Choose Next Form, for more information
on transaction level settings and locking conventions. See Chapter 9.6, Transaction
Control and Locking, for a detailed discussion of the ACCELL/IDS locking
mechanisms.
Variable terms
Variable
An ACCELL/Language identifier and storage location for a value. There are four
classes of variables, each with its own set of attributes:
32
General Variable
A variable that does not refer either to a target field or a screen field.
Screen Variable
A variable that refers to a non-database screen field defined on the
form. Screen variables have screen variable attributes.
Target Variable
A variable that refers only to a field in the target table. Target variables
have target variable attributes.
Screen/Target Variables
A variable that refers to a database screen field as defined on the form.
Screen/Target variables have screen variable attributes and target
variable attributes.
All classes share the attributes of a general variable; the screen/target variable
combines the added attributes of screen and target variables. Figure 14 shows the
relationship of each variable class to the screen field and to target field names.
Screen variable
(matches name of
screen field on
form)
General variable
(no name match to
a program variable
Target variable
(matches name of
field in target table)
Value on the
Screen
Value in
memory
Screen/Target
variable
(matches name of
screen field on form
and field in target
table)
Value from
database
Figure 14. Types of ACCELL/IDS Variables
The name of the variable determines its class and must be unique within the
Language script for that form. A variable's class is based on whether its name
matches an existing screen field or target field name.
See Chapter 6.2, Variables, for more information.
33
1.7 Form types
Standard form
Any regular application form created with the ACCELL/Generator that is not the
Master Application form or a Help form. A standard form can have a target table,
which is the database table it automatically searches and updates.
Master Application form
A special form that serves as an entry and exit point for the application. There can be
only one Master Application form per application. Master Application forms may not
have a target table. They are useful for setting up global variables for use anywhere in
the application, as well performing initialization and exit processing.
Zoom form
A standard form that is referenced by the ENABLE ZOOM statement and invoked by
the end user with the ZOOM command. Zoom forms offer a window into other parts of
the database without leaving the context of a transaction. Zoom forms are often used
for looking up information or performing tasks that are done infrequently. Zoom forms
are the implementation of the ZoomView™ feature.
A standard form that can display more than one record at a time. The part of the form
that will be repeated is marked in the ACCELL/Generator. See Chapter 5.2, under
Marking Repeating Areas, for more information on creating multi-occurrence forms.
Help form
Optional forms containing explanatory text. Help forms are displayed when the end
user enters the FIELD HELP command from a screen field. Help forms can contain
trim and are automatically managed by the ACCELL/Generator.
34
Error form
ACCELL/IDS automatically displays system error forms when errors occur. The display
of error forms and error messages depends on the information level set for the
application. See Chapter 4.3, Error Handling, for an explanation of information level
settings. For a more detailed explanation of a one-line error message or beep, the
user can press EXPLAIN ERROR to call up an error form.
ACCELL/IDS system error forms can be modified by the user. See Chapter 9.9
Customizing ACCELL/IDS Error Forms Using PAINTHLP.
35
36
Chapter 2: Introduction to application
design
2.1 Introduction
This chapter provides basic techniques and tips for designing database applications.
The next subsection, Application Design Basics, provides guidelines for individuals
who may not be familiar with application design. The subsection ACCELL/IDS Design
Tips is intended for developers who are familiar with application design and want
specific information about designing applications with ACCELL/IDS.
Application design basics
Techniques for designing applications vary depending on the size and complexity of
the application and the database. However, there are some basic steps you can follow
when designing applications:
•
Identify the parts of the application; what are the main tasks the application
must accomplish?
•
Identify the relationships among the parts; will each part operate
independently or will some parts be dependent on others?
•
Diagram the function of each part; what are the subtasks each main part must
perform?
•
Diagram the structure of the database; what database tables will
accommodate each of the subtasks and what relationships will the tables have
to each other?
•
Select the fields for each database table; which fields will each table contain?
•
Ensure that the database design is normalized. That is, each field within a
record must contain only a single data item for that field. See section 2.2 of the
37
Direct HLI Programmer's Manual for more information on normalizing your
database design.
See Chapter 2 of the ACCELL/IDS Developer's Tutorial for examples of how these
steps can be applied to application design.
ACCELL/IDS design tips
The rest of Chapter 2 outlines the use of ACCELL/IDS features to simplify application
design.
Organizing forms
If your application has many forms, use the ZoomView™ and form menu (branching)
capabilities of ACCELL/IDS, rather than making forms into a single sequence. Using
Zoom forms and form menus lets the user choose between forms and zoom to less
frequently used forms as needed. See the ACCELL/IDS Developer's Tutorial Manual
for examples of Zoom forms and form branching.
Form menus and Zoom forms also conserve memory by reducing the number of
active forms.
Transaction definition
Divide the forms in the application into logical transactions. Generally, a transaction
consists of a series of operation so that you do not want interrupted. For example, a
single transaction might consist of entering all of the line items for an order. Making an
entire order a single transaction guarantees that item entries cannot be modified until
the user enters all of the order information.
Keep your transactions short in order to use your database as efficiently as possible
and to improve your application's use of memory.
Special variable symbols
All ACCELL/IDS variables have an optional prefix symbol, $, that helps differentiate
them from other names, and to indicate that the variable name is not a keyword.
Although ACCELL/IDS can distinguish all variables by context, use of the special
38
symbol, $, enables you to more easily identify variables while reviewing Language
sections. For example:
form: $variable
Using the variable symbol removes potential conflicts with keywords and ensures that
your applications will run under future releases of ACCELL/IDS that may include new
keywords.
Using the set/select statement
To select records from a database table, use the WHERE clause of the SET/SELECT
statement. The WHERE clause specifies which subset of table records is the object of
the current operation.
When searching for data specified in a SET/SELECT statement, ACCELL/IDS
automatically chooses the most efficient access path to the data. The ACCELL/DBMS
supports four access methods:
•
hashing on the record's primary key
•
B-tree index on any field or combination of fields set up by the user
•
explicit relationships between Parent/Child records set up by the user
•
buffered sequential scan of all records in a table
For a given SET/SELECT statement, ACCELL/IDS analyzes the access methods
available and selects the most efficient method, based on search criteria in the
WHERE clause.
As a developer, you need to keep in mind that the search criteria in the WHERE
clause directly affect the access method selected, and consequently, affect how fast
the data is found. For best results using the WHERE clause search, you should fully
expand all expressions which appear in your WHERE clause.
Make efficient use of SET/SELECT statements by selecting only the record fields the
application needs. For example, the SET/SELECT statement in the following example
has an expression in the WHERE clause that is not fully expanded.
Introduction to application design
39
SET/SELECT statements execute faster if you perform only necessary calculations in
the WHERE clause. For example, the following statement performs a subtraction in its
WHERE clause:
SET $acct_number, $date, $first_name, $last_name
TO SELECT #acct, #bill_date, #cust_first_name,
#cust_last_name
FROM accounts
WHERE #bill_date < = current_date$()-30;
EXECUTING
. . .
It is more efficient to write this statement as follows:
SET $thirty_days_past TO current_date$() - 30;
SET $acct_ number, $date, $first_name, $last_name
TO SELECT #acct, #bill_date, #cust_first_name,
#cust_last_name
FROM accountsj WHERE #bill_date < = $thirty_days_past;j
EXECUTING
. . .
Because the second statement does not require the calculation of 30 days past to be
performed multiple times.
Default field values and range checking
The ACCELL/DBMS Advanced Field Attributes can be used to establish default
values and to perform range checking for database fields. If the Advanced Field
Attributes are set, ACCELL/IDS displays an error message on a PREV FIELD or
NEXT FIELD user command if a value does not fall within the proper range.
ACCELL/IDS uses the default value set in the Advanced Field Attributes if there is no
Clear to Add value. See the ACCELL/DBMS Reference Manual for more information
on Advanced Field Attributes.
40
Adding third generation language functions
ACCELL/IDS lets you add custom user functions you've written in C to your
applications. See Chapter 9.4, “User Functions”, for information about adding
functions to your applications.
Functions can extend ACCELL/IDS to perform calculations such as net present value
or rate of return, and to optimize the performance of complex algorithms.
Controlling the screen with user functions
Experienced developers can write user functions that use the screen for input and
output. First, have your function save the I/O control settings. Once the settings are
saved, your function will need to alter them because ACCELL/IDS leaves the terminal
in raw mode. Your function must restore the original control settings before returning
to the application.
Finally, because the application is unaware of any changes your function made, the
application must restore the screen after the function call by using the REPAINT
SCREEN statement.
Changing the system area display
The ACCELL/IDS screen layout can be controlled by setting several screen
characteristics. You can determine what the end user will see on the screen by
specifying how the ACCELL/IDS system area will look. The system area consists of
the mode, function key, and For Your Information (FYI) lines. You can control where
the system area displays as well as whether the application area windows appear.
Setting screen layout characteristics is useful when you want to simulate the
appearance of an existing software interface with ACCELL/IDS. You set the system
area characteristics by initializing the ACCELL/IDS environment variable AMGRINIT.
See Chapter 9.2, “Environment Variables”, for more information about the AMGRINIT
variable, and Chapter 4.2, “Screen Organization”, for more information about setting
screen layout characteristics.
41
Communicating with other programs or computers
ACCELL/IDS's pipeline facility lets you send information to an external program or
series of programs. Pipelines make it possible to send data to the DBMS report
generator (RPT) or your own report programs with your ACCELL/IDS applications.
See Chapter 9.5, Pipelines, for information about ACCELL/IDS pipelines.
•
Use as few video attributes (blink, reverse, underline, etc.) as possible for your
screen fields.
•
Run the terminal at 19200 baud rather than 9600 baud. Consult your terminal
manual or the manufacturer to see if this is possible on your system.
•
Use a VT100-compatible terminal that uses a higher performance chip such
as the Intel 80186.
•
Run your applications on non-VT100 terminals.
Form appearance
The appearance of application forms is enhanced by using terminals with line
graphics capabilities. If the terminal your application is using does not have line
graphics characters, ACCELL/IDS can also use standard ASCII characters, such as
the vertical bar (|) and asterisk (*), as form trim.
Exiting applications
ACCELL/IDS provides three ways to leave an application:
•
the EXIT option on the NEXT FORM statement
•
the NEXT ACTION IS EXIT statement
•
the user command ABORT APPLICATION
he NEXT ACTION and NEXT FORM statements provide an exit option that executes
the AFTER APPLICATION section, allowing the application to perform any necessary
final operations.
42
The ABORT APPLICATION command halts application execution ON EXIT, without
executing any Language sections. This command executes the ON EXIT section of
the current form, if present, and is intended primarily for developers to use during
application writing and testing. You may wish to remove the command from an
application user's unicap file.
ACCELL/IDS's self-documenting capabilities
ACCELL/IDS contains several features that speed up application development and
maintenance by making your applications self-documenting.
The ACCELL/Language's flexible and English-like syntax produce application scripts
that require little or no documentation. Comments can be included in your scripts
should they be necessary.
In addition, ACCELL/IDS includes three utility programs– Q2ASC, H2ASC, and
FRMDOC–that automate the documentation of your application and Help forms.
Q2ASC takes an ACCELL/IDS form created with the Generator and produces an
ASCII file. This file contains a complete list of all form and field attribute settings,
along with a reproduction of the form.
H2ASC performs the same conversion on your Help form archives to produce a file
containing a reproduction of the form, and a list of video attribute settings.
FRMDOC takes a Standard or Master Application form and produces a multiple page
report of the form's characteristics on your terminal.
These programs can also be used with operating system pipelines and can send
output directly to your terminal. See Chapter 9 for more information about Q2ASC,
FRMDOC, and H2ASC.
43
44
Chapter 3: ACCELL/Environment
3.1 Introduction
The ACCELL/Environment is itself an ACCELL/IDS application. The Environment
maintains its own database to:
•
track your application development
•
manage access to the application's forms and Language scripts
The Environment database supports the ACCELL Access Management System.
Access Management is accomplished by ACCELL/Environment through selective use
of ACCELL/IDS's advanced Lock Manager. The Lock Manager allows the
Environment to place shared and exclusive locks on each of the application's
development objects, such as forms and Language scripts.
ACCELL/Environment forms and menus
The ACCELL/Environment provides a convenient set of forms and menus for
developing applications. It gives you an easy alternative to issuing commands directly
from the operating system.
By selecting menu options, you can enter the ACCELL/Generator and create or edit
forms, enter the system editor to work on ACCELL/Language files, integrate with your
forms any language scripts you may have into a complete application, or call up the
ACCELL/Manager to execute an application. Prompts and help messages guide you
through the process of defining an application and simplify entering the different parts
of ACCELL/IDS.
When you select the option to compile and run an application, ACCELL/IDS
automatically takes care of compiling, combining, linking, and loading your files and
starts the application running. ACCELL/IDS even checks to see which forms you've
worked on before processing, eliminating unnecessary handling of unchanged forms.
45
Besides handling tedious processing tasks, the ACCELL/Environment provides an
easy way to keep track of all your applications and their related forms. Your
applications are listed together on one form for quick reference; and each application
has a list of its own forms.
Figure 15 shows the forms and menu available in the ACCELL/Environment.
Current application
List of forms in
current application
List of
applications
Application/Form
operations
Form
information
Application
information
(zoom form)
Figure 15. Overview: ACCELL/Environment Forms and Menus
The following section gives an overview of how to use these forms and menus to
define applications and enter the different parts of ACCELL/IDS.
46
3.2 Creating applications
To create an application with the ACCELL/IDS, you use the Environment menus to
name applications and forms. You then enter the different ACCELL/IDS modules from
within the Environment to create forms and Language scripts for your applications.
See Figure 16.
An overview of the process follows:
•
Selecting a Current Application: When you enter the ACCELL/Environment
you will first specify the name of the application you want to work on–the
current application–on the Current Application form. Additional Zoom forms let
you add and modify application names and write a detailed description of the
current application. You work on one application at a time within the ACCELL/
Environment; if you want to work on another application, you need to return to
the Current Application form and select another application.
•
Selecting the Current Form: Once you have selected a current application, use
the Form List form to indicate the form in the application you want to work with.
The Form List form lists all the forms defined for the application and lets you
select a current form, modify existing form names, and add new forms to the
application. A Zoom form available from this form lets you write a detailed
description of the current form.
•
Entering Different Parts of ACCELL/IDS: Once you have established a current
application and a current form, the Application/Form Operation menu lets you
enter the different parts of ACCELL/IDS to work on the form and process and
ACCELL/Environment
47
run the application. This menu also gives you access to the operating system
commands to perform more sophisticated tasks.
Current application
1.
Select current
application
2.
Select current
form
3.
Select
action
List of forms in
current application
Application/Form
operations
Figure 16. Creating Applications with the ACCELL/Environment
The next five subsections outline in detail how to create applications in the ACCELL/
Environment.
Help for the ACCELL/Environment
Help is available any time you are working with the ACCELL/Environment forms and
menus. To get help, use the FIELD HELP command from the field you need help for. A
small, pop-up Help form will appear over the current form you are filling out. Press
RETURN to exit the Help form.
48
Setting ACCELL/Environment variables
Before entering the ACCELL/Environment, you must set some special environment
variables in the operating system. See section 6.2, Variables, for information on
setting environment variables for your particular operating system. If you do not set
these variables, the ACCELL/Environment may not operate correctly.
Entering the ACCELL/Environment
After you set the environment variables, follow the steps below to start up the
ACCELL/Environment:
1. Make a work directory.
NOTE: If you have not already run an ACCELL/IDS application, the
application directory, accellapp, will not exist. You will first need to
create a directory for your ACCELL/IDS application. The accellapp
directory name is an example only. You can use whatever name you
wish.
❖ mkdir accellapp
2. Move to your ACCELL/IDS application directory.
❖ cd accellapp
3. At the operating system prompt, type:
❖ accell
Press RETURN. The ACCELL/IDS logo displays for a few seconds on your
screen.
NOTE: If you have not previously started ACCELL/IDS in the current directory,
the prompt will display:
Do you wish to create a new data dictionary?
If this prompt displays, type:
❖ Y
ACCELL/Environment
49
The ACCELL/IDS Main Menu displays.
[acimenu]
ACCELL Release 1.3
ACCELL Main Menu
1.
2.
3.
4.
5.
6.
23 Mar 1987 - 16:01
ACCELL/Environment
ACCELL/DBMS
User’s Tutorial
Developer’s Tutorial
Completed Tutorial Application
Operating System
SELECTION:
F1-Prv Form
F2-Nxt Form
F3-Prv Rec
4. Select the fourth option, Developer's Tutorial. Type:
❖ 1
at the SELECTION: prompt, then press RETURN
NOTE:If you have not previously started ACCELL/IDS in the current directory,
you will see the prompt:
ACCELL Environment does not exist, do you want to create a new one?(y/n)
If this prompt displays, type:
❖ Y
50
ACCELL/IDS creates the ACCELL/Environment and displays the Current
Application form.
NOTE:
You can also enter the Environment directly from the operating
system prompt by typing adev. See section 9.3, ACCELL/IDS
Command Level Development, for more information on working with
ACCELL/IDS from the operating system.
Selecting the current application
Three forms are used to define and describe the current application: the Current
Application form, the Application List form, and the Application Description form.
The first ACCELL/Environment form displayed is the following Current Application
form. This one-field form displays the name of the current application. The term
current is used to indicates that this is the application you will be working with; you
ACCELL/Environment
51
can work only on one application at a time in the ACCELL/Environment. See Figure
17.
replace
not stored
update zoom
record 1 of 1
ACCELL/ENVIRONMENT 1.3
Tue Jan 28 08:34:25 1986
CURRENT APPLICATION
Application Name: tutorial
Enter an existing application name, or ZOOM to add or list applications.
F1-Prv Form
F2-Nxt Form
F-Prv Rec3 F4-Nxt Rec F5-Fld Help F10-More Key
Figure 17. ACCELL/Environment Current Application Form
You'll notice that the current date and time, as well as the version number of the
ACCELL/Environment you are working with also appear at the top of this form for
easy reference.
To select a current application from this form, type the name of the application in the
Application Name field. If you can't remember the name of the applications you've
defined, or if you want to create a new application, press ZOOM from the Current
Application form, to call up the Application List form–a list of all the applications
currently defined. See the next subsection, Selecting, Adding, Modifying, and Deleting
Applications, for more information on using the Application List form.
52
Once you've selected a current application, press NEXT FORM from the Current
Application form to display the Form List. ACCELL/IDS displays an error message if it
does not find an application by that name or if modifications have been made to that
application from outside the ACCELL/Environment (from the operating system
prompt).
When you exit the ACCELL/Environment, ACCELL/IDS will remember which
application is current and display that application's name when you re-enter.
Selecting, adding, modifying, and deleting applications
To select, add, modify, or delete an application, use the ZOOM command to display
the Application List form. This form lists all the applications currently defined for this
database, and includes a brief description of each application. See Figure 18.
stored
replace
update zoom
record 1 of 1
RECORDS FOUND
Tue Jan 28 08:34:25 1986
CURRENT APPLICATION
LIST OF APPLICATIONS
Name
tutorial
Description
Prospect & Order Tracking
The name of an application. ZOOM for more information.
F1-Prv Form
F2-Nxt Form
F3-Prv Rec F4-Nxt Rec F5-Fld Help F10-More Key
Figure 18. ACCELL/Environment Application List Form
ACCELL/Environment
53
The steps for selecting a current application, adding a new application, modifying an
existing application name and description, and deleting an application using the
Application List follow:
To select an existing application:
1. Position the cursor on the name of the desired application on the Application
List, with the NEXT RECORD and PREV RECORD commands.
2. Press PREV FORM. The name of the application on which the cursor is
positioned is returned to the Current Application form.
To add a new application:
1. Press CLEAR TO ADD from the Application List, to create a new application
record.
2. Type the name of the application you want to add (11 characters maximum).
3. Press RETURN and type an application description (70 characters maximum).
4. Press ADD/UPDATE to save your entry. The FYI line will display a number of
messages.
To change the description for an existing application:
1. On the Application List, press NEXT RECORD and PREV RECORD to
position the cursor on the application you want to change.
2. Press RETURN and type the new description over the top of the existing one.
3. Press ADD/UPDATE to save your entry.
To delete an application:
1. Position the cursor on the appropriate application name on the Application
List, with the NEXT RECORD and PREV RECORD commands.
2. Press DELETE RECORD The application name and description are cleared
from the screen and all the forms and files contained in the application are
deleted from the system.
3. Enter yes at the ACCELL/IDS prompt:
Delete the application (yes/no)?
to confirm that you want to delete the current record.
54
When you delete an application, all its forms and Language scripts are permanently
removed from memory. The entire application directory is also removed.
Using the Application Description form
The Application Description form in Figure 19 provides a place for adding additional
descriptive information about the current application. You can access the Application
Description form from the Application List form by positioning the cursor on the name
of application you want to describe and using the ZOOM command.
replace
not stored
find
APPLICATION INFORMATION
Directory Name ..........:
Time of Creation ........:
Time of Last Modification:
Number of Forms .........:
/ust/accelltut
Thu Jul 3 08:42:30 1986
Mon May 18 10:40:37 1987
1
Description .............:
NameDescription
tutorial
F1-Prv Form
F2-Nxt Form
Figure 19. ACCELL/Environment Application Description Form
This form also automatically fills in other important information about the current
application, such as the directory pathname, when the application was added, when
the application was last updated, and the number of forms in the application.
ACCELL/Environment
55
You can go back and add or modify descriptive information for existing applications at
any time by zooming from the Application List form.
Returning to the Current Application form
You can return to the Current Application form from the Application List form by
pressing PREV FORM. Make sure the cursor is positioned on the name of the
application you want to make current. If you decide not to bring back an application
name to the Current Application form, press CANCEL ZOOM.
Using Access Management and the Lock Manager
The ACCELL/Environment uses Access Management to allow application
development using the team development approach. Access Management uses the
ACCELL/IDS Lock Manager to place shared and exclusive locks on each of the
development objects, such as forms and Language scripts.
A developer can only Add or Delete an application after the ACCELL/Environment has
successfully acquired an XLOCK on the application. Obtaining an XLOCK guarantees
that only the lock owner has the ability to read and write to the locked object.
The Environment will only succeed in acquiring the XLOCK if no other users have
locks on the same application. This convention prevents a developer from deleting the
application while another developer is still using some objects within that application.
For more information on XLOCK, see section 9.6, Transaction Control and Locking.
56
Selecting the current form
The Form List in Figure 20 provides a place for you to name and describe all of the
forms in the current application. The Form List can be accessed by pressing NEXT
FORM from the Current Application form.
stored
replace
update zoom
record 1 of 1
RECORDS FOUND
Tue Jan 28 08:34:25 1986
CURRENT APPLICATION
LIST OF FORMS FOR CURRENT APPLICATION
Form Name
tutorial
Form Description
Master Application Form
The name of a form. ZOOM for more information, NEXT FORM for the menu.
F1-Prv Form
F2-Nxt Form
Figure 20. ACCELL/Environment Form List Form
Using the Form List, you can select an existing form to work on, add a new form to the
current application, delete a form from the application, and modify descriptions of
existing forms. Once you've added a form to this list, you can work on that form just
like any other existing form–by selecting the appropriate options from the Application/
Form Operation menu.
ACCELL/Environment
57
Selecting, adding, modifying, and deleting forms
Using the Form List, you create separate records for each form. To work on an
existing form, you must select it from the Form List.
To select an existing form:
1. Position the cursor on the appropriate form name on the Form List, with the
NEXT RECORD and PREV RECORD commands.
2. Press the NEXT FORM to call up the Application/Form Operation menu.
To add a form to the list:
1. Press the CLEAR TO ADD from the Form List to create a new form record.
2. Type the name of the form you want to add (11 characters maximum).
3. Press RETURN and type a form description (70 characters maximum).
4. Press ADD/UPDATE to save your entry.
To modify an existing form description:
1. On the Form List, position the cursor on the form entry with the NEXT
RECORD and PREV RECORD commands.
2. Press RETURN and type the new description over the top of the existing one.
3.
Press ADD/UPDATE to save your entry.
To delete a form:
1. Position the cursor on the appropriate form name on the Form List.
2. Press DELETE RECORD.
3. Press DELETE RECORD.
4. Enter yes at the ACCELL/IDS prompt:
Delete the form (yes/no)?
to confirm that you want to delete the current form. A no response will abort
the DELETE RECORD command.
58
The form and its associated ACCELL/Language script are permanently deleted from
the system.
Using the Form Description form
To add more descriptive information about a form, press ZOOM to display the Form
Description form shown in Figure 21.
replace
stored
update
record 1 of 1
RECORDS FOUND
FORM INFORMATION
Form
Time
Time
Size
Name
F1-Prv Form
File Name ..........: /usr/accelltut/aclenv/tutor
of Creation ........: Thu Jul 3 13:49:44 1986
of Last Modification: Mon May 11 15:34:22 1987
of File in Bytes.....: 1026
Language File Name .......: /usr/accelltut/aclenv/tutor
Time of Creation .........: Thu Jul 3 13:49:44 1986
Time of Last Modification.: Mon May 11 15:34:22 1987
Size of File in Bytes.......: Description
1364
Description ..............:
F2-Nxt Form
Figure 21. ACCELL/Environment Form Description Form
This form automatically displays more detailed information about a form, such as the
pathnames of the form and its associated ACCELL/Language script, when the form
was created, when the form was last modified, size of the form in bytes. It also lets
you enter up to five lines of descriptive information.
To return to the Form List form from the Form Description form, press PREV FORM,
ACCELL/Environment
59
Using SLOCKs and XLOCKs
Many developers can work on the same application at the same time. The
Environment give each user an SLOCK at the application level. However, users are
prevented from adding, deleting, or updating the same form or Language script at the
same time.
An XLOCK is required for any add, delete, or update operation on a form or a script.
The Environment can only obtain an XLOCK if no other user has a lock on the same
object. See section 9.6, Transaction Control and Locking, for more information on
ACCELL/IDS locks.
Entering different parts of ACCELL/IDS
The ACCELL/Environment provides an Application/Form Operation menu that lets
you enter the ACCELL/Generator and system editor, to process and run applications,
and to access operating system commands. Before you can call up this menu, you
must first select a current application and a current form.
With the cursor on the appropriate form record on the Form List form, press NEXT
FORM to display the Application/Form Operation menu in Figure 22.
60
NOTE:
replace
You can also select an application by entering at the prompt the
number of the desired current application.
stored
update zoom
record 1 of 4
RECORDS FOUND
Tue Jan 28 08:34:25 1986
CURRENT APPLICATION
Select one of the following items
Application
Name:
1. Edit ACCELL/Generator
Form
tutorials
2. Edit Accell/Language Script
& Language
LIST 3.
OF Compile/Integrate
FORMS FOR CURRENT Forms
APPLICATION
4. Run Application
5. Compile/Integrate/Run
Application
Form NameForm
Description
6. Adjust
Forms Form
After DBMS Design Change
tutorialMaster
Application
7. Operation
System Commands
fcompanyCompany
Entry/Inquiry
fleadsProspect Tracking
forders
ENTER SELECTION:
Order Enter/Inquiry
Use the up or down arrows or enter a number; Press MENU SELECT or RETURN.
F1-Menu Sel
F2-Menu Can
F10-More Key
Figure 22. ACCELL/Environment Application/Form Operation Menu
Editing ACCELL/Generator forms
To enter the ACCELL/Generator to create or edit the current form, move the cursor to
the Edit ACCELL/Generator Form option on the Application/Form Operation menu
and press MENU SELECT. After a brief pause you'll be placed inside the ACCELL/
Generator with the specified form or a new form displayed on the screen. See Chapter
5, ACCELL/Generator, for more information on working with the ACCELL/Generator.
When you finish working on the form, press PREV FORM to return to the menu. You
can then select another menu operation, use PREV FORM to return to Form List form
ACCELL/Environment
61
and select another form to work on, or return to the Current Application form to
change applications or exit the Environment.
Editing ACCELL/Language scripts
To create ACCELL/Language scripts, you can use the system editor of your choice. To
go into the editor, select the Edit ACCELL/Language Script option from the
Application/Form Operation menu. You'll be placed inside the system editor, where
you can use standard editing commands to edit Language scripts. ACCELL/IDS
determines which system editor to enter based on operating system environment
variables you have specified. See section 6.2, Variables, for information on setting
environment variables.
When you exit the editor, you are returned to the Application/Form Operation menu.
You can then select another option, use PREV FORM to return to the Form List and
choose another form to work on, or return to the Current Application form to change
applications or exit the Environment.
Processing and running applications
You can select from three options for processing and running ACCELL/IDS
applications, as shown on the Application/Form Operation menu:
3.Compile/Integrate Forms & Language
4.Run Application
5.Compile/Integrate/Run Application
Option 3, Compile/Integrate Forms & Language, compiles the form and Language
scripts in your application. When you select this option, ACCELL/IDS asks if you wish
to compile all forms and scripts or only those that have changed since the previous
compile. in the FYI line changes you have made into a complete application, but does
not start the application running.
Enter yes at the prompt:
Compile/Integrate ALL of application [yes], or just CHANGES [no]:
62
to compile all forms and Language scripts. A no response compiles only those forms
and/or Language scripts that have been modified since your previous compile.
Option 4, Run Application, starts up the last version of the application you compiled.
This option does not compile any new form and Language changes you may have
made.
Option 5, Compile/Integrate/Run Application, recompiles your forms and Language
scripts into a new version of the application. If the compile completes without errors,
this option displays the prompt:
Compile/Integrate ALL of application [yes], or just CHANGES [no]:
Enter yes at the prompt to start the application running.
Rebuilding the application after a database reconfigure
Option 6, Adjust Forms After DBMS Design Change, updates the application form
files to correspond to the new application data dictionary. You must select this option
after you have reconfigured your application database. Otherwise, your ACCELL/IDS
forms may not work correctly with their database target records.
You can also perform this form update from the shell level by running the ACCELL/IDS
script Q2A2Q.
Accessing operating system commands
Option 7, Operating System Commands, temporarily suspends the ACCELL/
Environment to allow you to enter operating system commands from a system
prompt. See section 9.3, ACCELL/IDS Command Level Development, for information
on working with ACCELL/IDS from the operating system prompt.
Exiting the ACCELL/Environment
To exit the Environment, return to the Current Application form using the PREV FORM
command. Press PREV FORM again, and you return to the ACCELL/IDS menu.
ACCELL/Environment
63
64
Chapter 4: ACCELL/Manager
4.1 Introduction
This chapter describes the ACCELL/IDS runtime environment, where application end
users interact with ACCELL/IDS applications. The ACCELL/Manager maintains the
runtime environment and serves as a link between the user, the ACCELL/IDS files,
65
and the database used by the application. See Figure 23.
Development
ACCELL/Environment
ACCELL/Generator
ACCELL/Language
Editor
Runtime
Environment
ACCELL/Manager
ACCELL/DBMS Runtime
ACCELL/DBMS Report Writer
ACCELL/DBMS SQL Query
Language
ACCELL/DBMS
Figure 23. ACCELL/IDS Runtime Environment
The Manager accepts commands entered by the user running the application, calls up
the appropriate forms in the right order, changes the displays in the system area as
necessary, interacts with the database, and executes the appropriate sections of
compiled ACCELL/Language. Some Language sections are executed automatically
when an application runs and others only when certain user commands are issued.
On a more detailed level, the Manager determines the flow of application control, the
active scope of variables, the current set, the current records, most attributes, and the
current user mode.
ACCELL/IDS applications run in one of two standard user modes:
66
•
Find
•
Add/Update/Delete
See section 4.4, User Modes, for a description of ACCELL/IDS user modes. See
section 4.5, User Commands, for more information on user commands.
ACCELL/Manager
67
4.2 Screen organization
The top and bottom of the terminal screen, the system area, is reserved for system
messages shown in reverse video. The rest of the screen, the application area, can
be used by applications. See Figure 24.
application area
replace
stored
system area
update
record 1 of 10
RECORDS FOUND
COMPANY: Asthenia Development Corp.
ADDRESS: 5800 S.W. Washington St.
CITY: Portland
MAIN PHONE: (503) 246-2400
CONTACT:
M Bennett
Purchasing Manager
ext. 2406
SALES REP#:7
NAME:G. Moore
PHONE:(415) 645-1214
STATE: OR
ZIP: 97210
MAP:
system area
Figure 24. ACCELL/IDS Screen Organization
System areas
The first line and last two lines on the screen are reserved for ACCELL/IDS system
displays. The first line shows current status messages, such as Updating; the last two
lines display For Your Information (FYI) messages, system error messages, and
function key labels. See Figure 25.
68
The system areas cannot be used by the application. However, many application
actions affect the contents of the system area. You can change the location of the
system area parts using the AMGRINIT environment variable. See section 9.2,
Environment Variables, for more information on AMGRINIT.
Status information area
replace
not stored
find
COMPANY:
ADDRESS:
CITY:
MAIN PHONE:
CONTACT:
STATE:
SALES REP#:
NAME:
PHONE:
ZIP:
MAP:
F1-Prv Form
F2-Nxt Form
F3-Find
FYI message
F5-Fld Help
F10-More Key
function key labels
Figure 25. ACCELL/IDS System Area
When you design a form with the Generator, you can define FYI messages to display
for each screen field when the application runs. If you do not define an FYI message
for a field, the line reserved for FYI messages remains blank when the cursor is
positioned on that field.
ACCELL/Manager
69
The FYI message line is also used to display one-line error messages generated by
various ACCELL/IDS error conditions. See section 4.3, Error Handling, for more
information on how ACCELL/IDS handles errors.
ACCELL/IDS user commands come with default key assignments that can be
customized as needed by changing the settings in the unicap file. See Appendix B for
information on customizing key assignments with unicap. The function key
assignments are displayed on the last line of the system area. Only the main function
keys used to initiate commands in the current user mode are displayed at any one
time.
Status information messages
This section describes the status information messages appearing in the system
status line at the top of the screen. This status line tells the user the current execution
status of the application.
The discussion of the status areas, numbered 1 through 6, is keyed to Figure 26
1
2
3
4
5
6
Figure 26. Status Message Area
1
replace
Editing mode in which typed characters replace, or overlay, existing
text.
insert
Editing mode in which typed characters are inserted at the cursor and
any existing text is pushed to the right.
2
70
not stored
Indicates that the data on the screen entered by the user has not been
stored in the database.
stored
Indicates that the data displayed on the screen is from a database
record.
stored/modified
the data displayed on the screen is from a stored database record,
and has been modified but not yet updated.
3
find
Indicates the user is in Find mode; any data entered will be used as
search criteria when FIND is pressed.
update
Indicates the user is in Add/Update/Delete mode. Pressing ADD/
UPDATE updates the current record, if it came from the database, or
adds it if it is a new record. Pressing DELECTE RECORD deletes the
current record from the database.
4
zoom
Indicates that a Zoom form can be reached from the current field by
pressing ZOOM
5
record M of N Indicates the number of records in the selected set (N) and the position
of the current record (Mth record in the set).
record N of N Indicates the last record of the selected set; also displayed when
CLEAR TO ADD is pressed, since ACCELL/IDS adds new records to
the end of the selected set.
record M
Indicates that the Browse feature of Find mode is being used. M
indicates the position of the current record in the selected set.
6
FINDING
Indicates that ACCELL/IDS is in the process of selecting records which
meet the selection criteria.
NO RECORDS FOUND
Indicates that no records were found that met the selection criteria.
ACCELL/Manager
71
RECORDS
Displayed in conjunction with the message in box 5 (for example: 1 of 3
RECORDS FOUND), with the data for the first record in the selected
set.
ADDING
Indicates ACCELL/IDS is in the process of adding the current record to
the database.
ADDED
Indicates that the record was successfully added to the database.
UPDATING
Indicates ACCELL/IDS is in the process of updating the current record
in the database.
UPDATED
Indicates that the record was successfully updated in the database.
DELETING
Indicates ACCELL/IDS is in the process of deleting the current record
from the database.
DELETED
Indicates that the record was successfully deleted from the database.
Function key labels
By default, the last line of the screen displays the labels for the current function key
assignments. The area displays the valid commands for the current form. There can
be as many as four levels of labels available at any given time.
Pressing MORE KEY steps you through each level. Function key labels appear with
the appropriate function key numbers. The following tables list the function key labels
that appear in ACCELL/IDS.
ACCELLGenerator
72
1
Prev Form
Next Form
Sz Form
My Form
Fld Help
More Key
2
Help Menu
Set Video
Rep/Ins
Add/Upd
Add Fld
More Key
3
Mv Fld
Add Help
Sz Fld R
Del Fld
Mark Vdo
More Key
4
Mk Rep A
Ins Line
Del Line
Graphics
More Ket
ACCELL/Manager in Add/Update/Delete Mode
1
Prv Form
Next Form
Prv Rec
Nxt Rec
Fld Help
More Key
2
Help Menu
Clr-Add
Rep/Ins
Add/Upd
Rcll Fld
More Key
3
Exp Err
Clr_Find
Prv Set
Nxt Set
First Rec
More Key
4
Last Rec
Del Rec
Cancel Zoom
Zoom
More Ket
ACCELL/Manager in Find Mode
1
Prv Form
Nxt Form
Find
Fld Help
More Key
2
Help Menu
Clr-Add
Rep/Ins
Rcll fld
More Key
3
Expl Err
Clr-Find
4
ACCELL/Manager
More Key
Cancel Zoom
Zoom
More Ket
73
4.3 Error handling
When an error occurs, ACCELL/IDS automatically notifies the end user and takes the
course of action appropriate for the specific error encountered. Two factors determine
how ACCELL/IDS notifies the end user of an error:
•
the type of error encountered
•
the information level set for the application
After an error occurs, the application resumes execution at the last field where the end
user entered information.
Types of error messages
ACCELL/IDS has three types of error messages:
•
beep
•
one-line error message
•
error form
See Appendix C for a list of all one-line ACCELL/IDS compiler, combiner, and linker
error messages.
Types of errors
Errors in ACCELL/IDS are classified based on how serious they are: mild, medium,
severe, and fatal. The severity of the error and the information level specified both
affect the type of message displayed.
Mild errors
Mild errors include commands that are not valid or that are inappropriate under the
current circumstances. For example, pressing NEXT RECORD when you are on the
last record of the selected set.
74
Medium errors
Medium errors include locking conflicts with other users trying to add a record with a
duplicate key, attempting to delete a record that has other records referencing it, and
other operational errors.
Severe errors
Severe errors include problems that may prevent the application from operating
correctly such as dividing by zero, referring to a nonexistent form or variable, running
out of memory, and other application design errors.
Fatal errors
Fatal errors occur when the Manager cannot continue operating. Examples include
the system's inability to read the file containing the application itself, find or read one
of the system files, open the database, or to successfully perform internal consistency
checks.
Information levels
ACCELL/IDS's information level settings let end users select the kind of error
information appropriate for their level of expertise. Novice users can get as much
information as possible about each error, while experienced users don't have to be
bothered with messages for minor errors.
There are three information levels available in ACCELL– novice, intermediate, and
expert. Each affects the display of error message information in a different way.
The default information level is novice. This setting can be changed using the system
variable info_level$(). See section 6.5, under ACCELL/IDS System Variables.
ACCELL/Manager
75
The following table shows the relationship between the information level and the
display of error messages at each error level.
Info Level
Mild
Medium
Severe
Fatal
Novice
Beep
Message Line
Beep
Error Form
Beep
Error Form
Beep
Error Form
Exit
Intermediate Beep
Beep
Message Line
Beep
Error Form
Beep
Error Form
Exit
Expert
Beep
Beep
Message Line
Beep
Error Form
Exit
Beep
End users can get additional information about errors with the EXPLAIN ERROR user
command. For example, if an application is running at intermediate level and it
encounters a mild error, the user is notified with a beep; the user could then use
EXPLAIN ERROR display a one-line message explaining the error. Pressing
EXPLAIN ERROR second time would display an error form.
The SHOW ERROR user command lets the user switch between novice and
intermediate information levels.
NOTE:
Fatal errors at all information levels, described below, are indicated by
a beep.
Novice information level
At the novice information level, mild errors are indicated with a beep and a one-line
error message; medium and severe errors are indicated with a beep and an error
form.
Intermediate information level
At the intermediate information level, mild errors are indicated with a beep, medium
errors with a beep and a one-line message, and severe errors with a beep and an
error form.
76
Expert information level
At the expert information level, mild and medium errors are indicated with a beep,
severe errors with a beep and a message line. Fatal errors are indicated with a beep,
error form, and an exit.
ACCELL/Manager
77
4.4 User modes
ACCELL/IDS applications run in one of two user modes:
•
Add/Update/Delete
•
Find
User modes are entered either automatically as a result of attributes specified in
ACCELL/Language or defaults assumed by ACCELL/IDS, or when the end user
enters particular user commands. The mode descriptions in the following sections
describe how each mode is entered and exited.
In Add/Update/Delete mode, the user may add records to the database, modify
existing records, or remove records.
ACCELL/IDS enters Add/Update/Delete mode under one of three conditions:
•
when the user enters a CLEAR TO ADD command
•
when ACCELL/IDS performs a successful Find
•
when a form has the AUD_ON_ENTRY form attribute specified as TRUE.
A CLEAR TO FIND command exits Add/Update/Delete mode and enters Find mode.
Continuous data entry can be done in Add/Update/Delete mode by setting the
CLEAR_AFTER_AU form attribute to TRUE in Language. When this attribute is set to
TRUE, the form is automatically cleared after each Add/Update/Delete, so the user
can start a new entry. This is known as an implicit Clear to Add and its saves the user
from having to enter the CLEAR TO ADD command before entering each new record.
For information about updating a field that is associated with an AFA “unique”
attribute, see “Update Current Record” in Chapter 8.
78
Find mode
In Find mode, the user can type information in fields and then give the FIND
command. ACCELL/IDS will search the database for records that match those
entries. Information typed in by the user is called search criteria.
Find mode is only used to enter search criteria before the end user performs a Find.
Add/Update/Delete mode is used for all other tasks.
Find mode is entered one of two ways:
•
when the end user issues a CLEAR TO FIND command
•
when the AUD_ON_ENTRY form attribute is set to FALSE, and you are
entering the form
If a user-requested Find is successful, ACCELL/IDS automatically leaves Find mode
and enters Add/Update/Delete mode. If the search fails because of an error or
because no records meeting the search criteria were found, ACCELL/IDS stays in
Find mode and the search criteria remain on the screen.
The end user has the option of ending a search in progress with the INTERRUPT user
command. ACCELL/IDS remains in Find mode after an Interrupt.
Using metacharacters and special symbols
In addition to entering actual field values as search criteria, the end user can enter
special value ranges. There are two ways to specify a value range:
•
Use metacharacters when the screen field is a STRING.
•
Use special symbols if the screen field is not a string (NUMERIC, AMOUNT,
etc.).
Metacharacters
Value ranges are specified for string screen fields by using four metacharacters: ?, *,
[ ], and ,. The question mark (?) matches any single character. The asterisk (*)
matches any string including a null, or zero length string. The comma translates as
the logical “OR.” The left and right brackets ([ ]) are used to specify a range of
characters. The following table shows what each metacharacter matches:
ACCELL/Manager
79
?
Matches any single character.
For example, ABC? matches any field value of four characters that
starts with ABC.
*
Matches any string including null or zero length strings.
For example, A*B matches any string beginning with an upper case A
and ending in a upper case B.
,
OR
For example, a,b indicates a choice between a or b.
[]
Matches the range of characters specified within the brackets.
For example, [ABDE] only matches the field values A, B, D, or E.
As another example, [ABC]??? matches any four-character string beginning with an
upper case A, B, or C.
You can also use a shorthand notation to specify large ranges. For example, [A-Z]
matches any upper case letter and [0-7] matches any of the digits zero through seven.
Special Symbols
Value ranges for non-string fields are specified using the four symbols <, >, !, and -.
The symbols have the following meanings:
80
<
Searches for records with field values less than this value.
For example, <1789 finds any records with a field value less than 1789.
>
Searches for records with field values greater than this value.
For example, n>8890 finds any records with a field value greater than
8890.
!
Looks for fields that do not match the value.
For example, !23 finds any records with a field value not equal to 23.
-
Specifies a range of values; 123-789 finds any record with a field value
from 123 through 789. The range symbol can be used with the
exclamation mark to specify fields outside of a range.
For example, !123-789 matches any records with a field value not in
that range.
Explicit and Default Search Modes
Find itself can be operated in two modes for STRING field searches:
•
explicit mode
•
default mode
These two modes determine how searches are performed on STRING fields. You can
toggle between the two Find modes using the explicit_mode parameter of the
AMGRINIT environment variable. The default Find setting is default mode.
See section 9.2, Environment Variables, for information about setting explicit_mode.
NOTE:
Searches on key fields and components of COMB fields are always
performed explicitly.
In explicit mode, searches are performed for the exact match to the search criteria.
The asterisk (*) is not appended to the end of the search criteria.
In default mode, searches are performed by appending an asterisk (*) to the end of
the search criteria if the criteria does not end in a metacharacter. If a metacharacter is
the last character of the search criteria, the search is performed explicitly.
The explicit mode of Find is advantageous because searches will use a hash table
rather than a B-tree or sequential search as in default mode. Explicit mode also offers
the user more control in setting search criteria.
Some examples of explicit and default mode searches are shown in Figure 26.
The data being searched is:
ACCELL/Manager
81
John, Johnson, John Doe, Jok, Joe, Job
Mode
Field
Explicit
key/
Comb
Search
Criteria
Selection result
John
John
John
John, Johnson, John Doe
✔
John
John
✔
✔
John
John
✔
✔
John*
John, Johnson, John Doe
Default
non-key
✔
✔
✔
✔
✔
✔
Jo[a-g]
Job, Joe
✔
✔
Jo?
Job, Joe, Jok
Figure 27 Find Mode Search Examples
Browse Feature
The Browse feature lets you specify the number of records initially selected for, and
then incremented to, the selected set. Browse suspends the record search after each
subset of records is found.
The standard record search method puts all selected records into the selected set.
The Browse feature is implemented by setting the FIND_COUNT form attribute to a
positive integer. For example:
FORM CUSTOMER
BEFORE FORM
SET CUSTOMER:FIND_COUNT TO 25;
If the user scrolls through the selected set to the end boundary using NEXT RECORD
or NEXT SET, another group of records equal to FIND_COUNT is added to the set.
This select and add process occurs each time the user passes the selected set's end
boundary until no more records are found that satisfy the search criteria.
A LAST RECORD command will cause the Manager to find all the remaining records
and add them to the selected set.
82
Browse is useful if the user does not need all of the records in the selected set at one
time and the number of records that meet the selection criteria is much larger in
comparison to FIND_COUNT.
When using Browse, your application's performance will increase because only the
FIND_COUNT number of records are put into the selected set before control returns
to the user.
Browse also allows the user more control over the number of records that are being
displayed on Multi-occurrence forms.
Application performance may not improve if the user is performing a sorted Find.
Sorted Finds require ACCELL/IDS to scan all records first. Under this condition, BTrees are recommended to increase performance.
ACCELL/Manager
83
4.5 User commands
As an ACCELL/IDS application runs, the end user enters commands to perform
functions like moving the cursor between fields, displaying different forms, and finding,
adding, and updating database records.
See subsection User Command Summary, for user commands and subsection User
Command Descriptions, for detailed descriptions of each command. Some user
commands also execute sections of ACCELL/Language. See the next subsection,
User Command Execution Sequence, for information on which user commands
execute which Language sections.
User commands are assigned to various keys on the keyboard. The most commonly
used commands are assigned to function keys and the rest are assigned to key
sequences that include the Escape or Control key. ACCELL/IDS comes with a set of
default key assignments.
See Appendix B, “Developer's Command Summary” card, for a list of the default key
sequences assigned to user and Generator commands. You may optionally reassign
user commands to different keys by altering the contents of the unicap file. See
Appendix B, “Setting Up the System”, for information on reassigning user commands.
User command execution sequence
The exact order of execution for Language sections in ACCELL/Language scripts
depends on the sequence of commands entered by the end user. However, there are
some general rules that apply to key user commands. These rules are outlined in the
following table.
84
Commands
Order of Language Section Execution
NEXT FORM
suspends current ON FIELD
executes on NEXT FORM of current form
initializes next form
executes INIT FIELD of next form
executes BEFORE FORM of next form
starts field execution with the first field
Commands
Order of Language Section Execution
PREV FORM
suspends current ON FIELD
executes ON PREVIOUS FORM of current form
executes AFTER ZOOM of current form
executes AFTER FORM RETURN of previous form
resumes suspended ON FIELD of previous form
NEXT FIELD
executes rest of current field’s ON FIELD
executes WHEN FIELD CHANGES of current field if necessary
executes AFTER FIELD of current field
resumes field execution with next field
PREV FIELD
executes rest of current field’s ON FIELD
executes WHEN FIELD CHANGE of current field, if necessary
executes AFTER FIELD of current field
resumes field execution with previous field
CLEAR TO FIND
evaluates CLEAR_TO_FIND expressions of target fields
FIND
executes BEFORE FIND of current form
executes OMFIND for each record found
executes AFTER FIND of current form
starts field execution with first field
CLEAR TO ADD
evaluates CLEAR_TO_ADD expressions of target fields
ABORT APP
interrupts current action
executes ON EXIT of current form
ends application by returning to system prompt
ADD/UPDATE
accepts data in current field
executes BEFORE ADD or before UPDATE of current form
execute AFTER ADD or AFTER UPDATE of current form
resumes execution of current field
DELETE RECORD
executes BEFORE DELETE of current form
executes AFTER DELETE of current form
finds a new current record
For a more detailed description of the sequence of execution for user commands, see
Chapter 10, Runtime Execution, and individual command descriptions in subsection
User Command Descriptions. See Chapter 7, ACCELL/Language sections, for
information on ACCELL/Language sections.
ACCELL/Manager
85
User command summary
The following summary of user commands is grouped by function. Detailed
descriptions of all the user commands appear in the next subsection, User Command
Descriptions, under the appropriate function headings.
Manager commands
MORE KEYFIELD HELP
REPAINT SCREENINTERRUPT
ABORT APPLICATIONSHOW ERRORS
HELP MENUEXPLAIN ERROR
EXIT HELP
Form commands
NEXT FORM
PREV FORM
Field commands
NEXT
PREV
NEXT
PREV
FIELD
FIELD
TAB
TAB
Screen Field Editing commands
REPLACE/INSERTLEFT EDGE OF WINDOW
MOVE LEFTRIGHT EDGE OF WINDOW
MOVE RIGHTLEFT EDGE OF DATA
UNREPLACE LEFTRIGHT EDGE OF DATA
DELETE CHARLEFT EDGE OF FIELD
DELETE CHAR LEFTRIGHT EDGE OF FIELD
DELETE LEFTCLEAR FIELD
DELETE RIGHTRECALL FIELD
Find commands
CLEAR TO FIND
FIND
86
Add/Update/Delete commands
CLEAR TO ADD
ADD/UPDATE
DELETE RECORD
Record commands
NEXT RECORDFIRST RECORD
PREVIOUS RECORDLAST RECORD
NEXT SET
PREV SET
Zoom commands
CANCEL ZOOM
ZOOM
Menu commands
MENU
MENU
MENU
MENU
SELECT
CANCEL
UP
DOWN
User command descriptions
This section provides detailed descriptions of all the ACCELL/IDS user commands.
Descriptions are grouped by function. If you are looking for a description of a
particular command, but are not sure which command group it belongs to, check the
user command summary in the previous section.
Manager commands
MORE KEY
Cycles through different sets of function key assignment labels,
displayed at the bottom of the screen.
REPAINT SCREEN
Restores the screen when the display has been disrupted.
ACCELL/Manager
87
ABORT APPLICATION
Cancels the current application, without saving your changes. The
command returns to the point in the system where the user entered the
application.
HELP MENU Puts the user in the ACCELL/IDS help subsystem. The help
subsystem is a tree-structured, menu-driven set of help windows
providing information about ACCELL/IDS commands.
The ACCELL/IDS HELP MENU command displays the main ACCELL/
IDS Help menu, along with information explaining how to use the Help
subsystem. From the main help menu, the user may return to the
application or go on to other Help menus that give more specific
information about commands. All Help menus act like normal
application menus; the end user selects options using function keys.
EXIT HELP
Returns to the point in the application where you entered the help
subsystem and resumes execution of the application.
FIELD HELP Displays the Help form associated with the current field. If the field
does not have a Help form an error message is displayed.
INTERRUPT Stops the current operation in progress, and prompts you that the
search has been interrupted. This is especially useful if an end user
accidentally issues a FIND that will search much of the database.
SHOW ERRORS
Switches the error information level between novice and intermediate.
See section 4.3, Error Handling, for a more detailed explanation of
information levels.
EXPLAIN ERROR
Calls up additional information about an error that has just occurred.
For example, if an error occurs which sounds a beep, you can give this
command to call up a one-line error message explaining the error and
then give the command again to display an error form with more
detailed information about that error.
88
Form commands
Form commands are used to move between forms or between fields on a single form.
The cursor will stop on fields that require the user to enter information.
NEXT FORM Displays the next form in the application and begins execution of that
form. This involves suspending execution of the current form or, in the
case of a new transaction, terminating the execution of all suspended
forms.
The NEXT FORM command does not cause any input to be accepted.
The user must enter ADD/UPDATE to save any changes before
pressing NEXT FORM
Alternately, you can add an UPDATE CURRENT RECORD statement
in the ON NEXT FORM Language section to save changes
automatically. In this case, you could use the
IS_CURRENT_RECORD_STORED$ system function to check
whether the user has saved the changes before performing the update.
PREV FORM Ends the current form's execution and resumes execution of the
previous form at the field last in use. The current form disappears from
the screen and the previously displayed form appears. On Standard
forms, PREV FORM executes the form's ON PREVIOUS FORM
section before leaving the form. Then, the AFTER FORM RETURN of
the previous form is executed before returning control to the field
where NEXT FORM originated.
On Zoom forms, PREV FORM executes the AFTER ZOOM Language
section and returns the user to the form from which the ZOOM was
performed. Then, the AFTER FORM RETURN of the previous form is
executed before returning control to the field where NEXT FORM
originated.The cursor returns to the field where the ZOOM originated.
If the RETURN KEY option has been specified in the ENABLE ZOOM
statement, the key value will be brought back to the original form and
filled in the field.
ACCELL/Manager
89
Field commands
NEXT FIELD and PREV FIELD
Accept new data entered into the current field and the move to the next
appropriate field. The appropriate field is determined by entries made
in the ACCELL/Generator or overriding entries made in a Language
script. If an entry is required on the current field and no data has been
entered, the command is not executed and an error message is
displayed. The entry is also checked against the legal values specified
for the DBMS Advanced Field Attributes. If the value is not valid, an
error message is displayed.
ACCELL/IDS responds to the NEXT FIELD command by executing the
FIELD Language for any display only fields between the current field
and the next field with STOP_ FOR_INPUT set to TRUE.
NEXT TAB and PREV TAB
Accept new data entered in the current field and then move the cursor
to the appropriate tab-stopped field. Any fields between the two tabstopped fields are skipped. Any Language associated with the skipped
fields is not executed. If NEXT TAB is used on the last tab-stopped
field, an error message is displayed and the cursor does not move.
Similarly, if PREV TAB is used and there is no previous tabbed field, an
error message appears and the cursor does not move.
Screen Field Editing commands
Input editing commands may be used any time the user is entering data. There are
two input editing modes–insert mode and replace mode.
The current mode is indicated by either insert or replace appearing in the system
area's first field. The default is Replace mode unless changed by the application. The
user may toggle back and forth between the modes by pressing REPLACE/INSERT.
Input editing command errors are indicated by a beep or an one-line message,
depending on the information level.
REPLACE CURRENT
Switches the current editing mode back and forth between Replace
90
and Insert. In Replace mode, any characters entered replace the
characters already in the field, beginning at the cursor position. In
Insert mode, any characters typed are inserted immediately before the
cursor.
MOVE RIGHT and MOVE LEFT
Move the cursor right or left one character position without disturbing
the contents of the field. If the cursor is at the edge of the field window,
the field contents will scroll horizontally one character position each
time this command is given. These commands are normally assigned
to the right arrow (!) and left arrow (z)keys, if they are available on your
terminal.
UNREPLACE LEFT
Moves the cursor left one position and restores the previously deleted
character. This command can only restore characters that were typed
over in Replace mode. Only characters that were replaced since the
last time the end user entered Replace mode may be restored with
UNREPLACE LEFT. Once the end user moves to a new field, the
replaced characters can no longer be restored.
DELETE CHAR
Deletes the character under the cursor and moves the rest of the field
one position to the left.
DELETE CHAR LEFT
Deletes the character to the left of the cursor and moves the rest of the
field one position to the left.
DELETE LEFT and DELETE RIGHT
Delete all characters to the right or left of the cursor on the current line.
DELETE FIELD RIGHT also deletes the character under the cursor.
After the end user presses DELETE FIELD RIGHT, the cursor is
placed one character to the right of the field's new right edge. DELETE
FIELD LEFT leaves the cursor on the field's new left edge.
RIGHT EDGE OF WINDOW and LEFT EDGE OF WINDOW
Move the cursor to the right or left edge of the field window. No
horizontal scrolling is performed. The contents of the field are
undisturbed.
ACCELL/Manager
91
RIGHT EDGE OF DATA and LEFT EDGE OF DATA
Move the cursor to the right-most or left-most non-blank character.
Horizontal scrolling occurs only if the field is longer than the window.
The contents of the field are undisturbed.
RIGHT EDGE OF FIELD and LEFT EDGE OF FIELD
Move the cursor to the field's right and left margins. These commands
differ from the field commands RIGHT EDGE OF FIELD and LEFT
EDGE OF FIELD in that they move the cursor to the limit of the field as
defined in the Generator. The limits of a field may extend beyond the
left-most or right-most non-blank character in the contents of the field.
CLEAR FIELD
Sets the current screen field value to all blanks and places the cursor
at the field's left edge. CLEAR FIELD is the equivalent of a LEFT
EDGE OF FIELD command followed by a DELETE FIELD RIGHT
command.
Since the screen field is filled with blanks, pressing RETURN after
CLEAR FIELD will cause an error in all field types except STRINGS
and DATES while in Add/Update mode. In Find mode, blanks are a
valid null search string and will not cause an error.
RECALL FIELD
Sets the field to its previous value, if there was one. This command will
not work if CLEAR FIELD has been pressed.
Find commands
All database searches use the database search commands described below. These
commands allow the user to enter Find mode and then select records from the
database that match defined criteria.
CLEAR TO FIND
Used to enter Find mode. In Find mode the user can enter search
criteria in screen fields.
The CLEAR TO FIND command fills all non-target screen fields with
blanks and then clears the selected set. The command also evaluates
92
any Clear to Find expressions set in Language sections to determine
each target field's default search range. CLEAR TO FIND executes the
ON CLEAR TO FIND Language section.
FIND
Carries out a database search using the search criteria entered by the
end user and/or specified in Language. ACCELL/IDS executes the
BEFORE FIND section and then searches the database.
The ON FIND Language section is performed once for each record
found. If there are no errors, the selected set is formed. After the Find
is finished, ACCELL/IDS executes the AFTER FIND section.
See Browse Feature, for information about how the selected set is
formed when the FIND_COUNT form attribute is set.
Add/Update/Delete commands
Database modification commands are used in Add/Update/Delete mode. Records
can be added, deleted, or updated using these commands.
For information about updating a field that is associated with an AFA “unique”
attribute, see “Update Current Record” in Chapter 8.
CLEAR TO ADD
Sets up a record with its fields set to their default values. This
command executes the ON CLEAR TO ADD Language section. The
default values are found for each field as follows:
•
If there is a Clear to Add expression in Language, it is evaluated
and the value is used, otherwise,
•
the DBMS default value is used. This is either the Advanced Field
Attribute default, if it exists, or the standard default: zero for
NUMERIC, FLOAT, AMOUNT, and TIME fields; null for STRING
and DATE fields.
Once the new record is initialized the user can move around the form
and enter new field values. The record established by CLEAR TO ADD
is not written to the database until the ADD/UPDATE command is
given.
ACCELL/Manager
93
ADD/UPDATE
Writes the current record to the database. If CLEAR TO ADD was used
to create the record, the record is added. Otherwise, ACCELL/IDS
assumes that the current record exists in the database and tries to
update the record.
In either case, ACCELL/IDS first executes the BEFORE ADD or
BEFORE UPDATE Language section, performs the designated add or
update, and then executes the AFTER ADD or AFTER UPDATE
Language section. Data in the current field is accepted as input before
the Add/Update is actually performed.
DELETE RECORD
Removes the current record from the selected set and the database.
DELETE RECORD executes the BEFORE DELETE section, performs
the actual delete and executes the AFTER DELETE section. Once a
record has been deleted, ACCELL/IDS makes a new record current.
The new current record is either the next record in the set or the
previous record, depending on whether the deleted record was the last
record of the selected set.
Record commands
Using the record commands, the user can move forwards or backwards within the
selected set, or move backwards or forwards by sets. The record commands can be
used only in Add/Update/Delete mode.
The order in which records appear is determined in one of two ways.
•
If the form contains an order-by field list, as specified in ACCELL/Generator,
then the records are displayed in sorted order. A new record will be placed at
the end of the list, not in sorted order, until the end user does another Find.
•
If there is no order-by field, the records are displayed in an arbitrary order.
For single-occurrence forms, the current record is the one displayed on the form. In
the case of multi-occurrence forms, the cursor is on the current record.
94
When the record commands are used to scroll through multi-occurrence forms,
ACCELL/IDS will usually leave two records from the previous set on the screen to
help the user maintain the context of the display.
All selected set commands display the current record number in the system area's
fifth field. The record count for the selected set is also updated by these commands.
When using the Browse feature of Find, if the user scrolls through the selected set to
the end boundary using NEXT RECORD or NEXT SET another group of records
equal to FIND_COUNT is added to the set. This select and add process occurs each
time the user passes the selected set's end boundary until no more records are found
that satisfy the search criteria.
Also, when using Browse, a LAST RECORD command will cause the Manager to find
all the remaining records and add them to the selected set.
See Browse Feature, for more information on use of the FIND_COUNT form attribute
and Browse.
When the end user issues any of the following commands, all changes made in the
current record since the last ADD/UPDATE are lost:
NEXT SET
PREV SET
NEXT RECORD
PREV RECORD
FIRST RECORD
LAST RECORD
NEXT RECORD and PREV RECORD
Make the next or previous record in the selected set the current record.
For single-occurrence forms, the current record is the one displayed on
the form; for multi-occurrence forms, the cursor is on the current
record.
When either command is used with multi-occurrence forms, the display
of records scrolls so that the next record comes into view.
ACCELL/Manager
95
NEXT RECORD produces an error when used on the last record of
the set. PREV RECORD produces an error when used on the first
record of the set.
NEXT SET and PREV SET
Refill the current set with other records from the selected set. With
NEXT SET the new set's first record becomes the current record.
PREV SET makes the new set's last record the current record.
When used with multi-occurrence forms, NEXT SET and PREV SET
display the next or previous screenful of records; these records
become the new current record set.
When used with single-occurrence forms, NEXT SET and PREV SET
have the same effect as NEXT RECORD and PREV RECORD
When used on the last set in the selected set, NEXT SETproduces an
error; PREV SET produces a similar error when used on the first set in
the selected set.
FIRST RECORD and LAST RECORD
FIRST RECORD makes the first record in the selected set the current
record; LAST RECORD makes the last record in the selected set the
current record. For regular forms, the current record is the one
displayed on the form; for multi-occurrence forms, the cursor is on the
current record. FIRST RECORD produces an error when used on the
first record of the set; LAST RECORD produces an error on the last
record of the set.
When either command is used with multi-occurrence forms, the display
is scrolled if the first or last record is not on the screen.
Zoom commands
Zoom commands allow a user to view a Zoom form associated with the current input
field. Zoom appears in the system area's fourth field when the cursor rests on a zoomenabled input field. Pressing ZOOM uses the Zoom form to display, and begins
execution of the Zoom form. Zoom forms can be exited by using the PREV FORM or
CANCEL ZOOM commands.
96
ZOOM
Displays a Zoom form for the current input field. ZOOM produces an
error when used on a field that is not zoom-enabled.
CANCEL ZOOM
Returns the user to the form on which the Zoom was performed. The
cursor is placed on the field where the Zoom originated. CANCEL
ZOOM differs from PREV FORM in that it does not execute the AFTER
ZOOM Language section and no key values are brought back to the
original form if RETURN_KEY was specified in the ENABLE ZOOM
statement. CANCEL ZOOM works only on Zoom forms.
Menu commands
To select a menu option, enter the number of the desired option at the prompt. You
can also move among menu and form listings as described below.
MENU UP and MENU DOWN
Move the cursor up or down a menu or form. These commands are
normally assigned to the up arrow and down arrow keys, respectively, if
they are available on your terminal.
MENU SELECT
Activates the menu option the cursor is currently positioned on. To
choose an option from an ACCELL/IDS menu, move the cursor to the
appropriate item and give this command.
MENU CANCEL
Cancels the menu and returns you to the previous form.
ACCELL/Manager
97
98
Chapter 5: ACCELL/Generator
5.1 Introduction to the ACCELL/Language
The ACCELL/Generator is an application generator used to create and maintain
forms used in ACCELL/IDS applications. Using the Generator, you can draw forms on
the screen, instantly change the size, shape, and location of form windows, define
and locate fields, set attributes, create help windows and default menus, and specify
the flow of forms and fields. You can also indicate which operations to allow on each
field and form and associate screen fields directly with the database.
The ACCELL/Generator is designed to work like an ACCELL/IDS application so that
you can easily switch between designing forms and running applications without
having to remember two different sets of commands.
Many applications can be created with the ACCELL/Generator alone. But ACCELL/
Language is also available if you need to add more logic and computational ability to
your application. Attributes specified in Language override those specified in the
Generator.
A series of convenient Generator forms is provided to simplify the task of creating
forms for your applications. An overview of the ACCELL/Generator structure is shown
in Figure 28.
99
Setting Tab
Forms
Session
Defaults
Edit
New Form
Your
Form
Video
Defaults
List of DB
Tables
Mark
Attributes
Form
Definition
Field
Definition
List of
Fields
from Target
Table
Advanced
Form
Definition
CHOOSE
NEXT
FORM
Figure 28. Overview of ACCELL/Generator Forms
The next section gives an overview of how each type of form is used in the forms
creation process.
100
5.2 Creating forms
Each form made with the Generator is stored in a separate file. An overview of the
steps for creating forms follows.
When you enter the Generator to create a form, the Form Definition form appears on
the screen. Form definition consists of filling in this form. Information entered includes
the name of the target table in the database to be used by the form, the operations
allowed on the form, the number of records (occurrences) displayed on the form, the
order in which to sort selected records, and the field execution order.
Specifying Next Form characteristics
To specify which forms will follow the form you are defining, you fill in the Choose Next
Form form. Information specified on this form includes the name of the next forms and
the transaction level at which those forms will run. Entering more than one next form
will automatically generate a menu at the appropriate point when the application runs,
letting the end user choose which form to execute next.
Sizing and locating the form window
In this step, you specify the size of the form window and its location on the physical
screen. This can be done any time after the form is defined.
Adding Form Trim
The Generator forms editor can be used to add letters, numbers, headings, or graphic
trim anywhere within the form window's boundaries. Other editing commands help
speed up the editing process and let you perform editing tasks such as moving trim
and fields around on the form.
ACCELL/Generator
101
To define screen field characteristics you press ADD FIELD and fill in the Field
Definition form. A field definition includes naming the field and specifying input
constraints, writing a For Your Information (FYI) message to display when the cursor
is positioned on that field, and specifying optional field parameters.
For standard forms, make sure that at least one of the fields on the form has the
STOP_FOR_INPUT parameter set to YES. If none of the fields are marked as
STOP_FOR_INPUT, the ACCELL/Manager will continuously loop through the form,
looking for a field to stop on. A Master Application form may have no fields with
Stop_For_Input set to yes (effectively skipping the form) if the first form is specified via
either the CHOOSE FIRST FORM language section or the NEXT FORM specification
in the Generator
More sophisticated field characteristics, such as video display attributes and display
justification, can be defined with the Advanced Field Definition form. This form is
called up by entering the NEXT FORM command from the Field Definition form.
Defining help forms
Help forms are used to provide specific information on individual fields, such as
required format or allowed abbreviations. You can make Help forms for any field within
a form by pressing ADD HELP while positioned on the field. Help forms are created
just like regular forms.
Multi-occurrence forms allow more than one record to be displayed on the screen at a
time. For multi-occurrence forms, you need to mark the specific part of a form that will
be repeated. The repeating area can include trim as well as screen fields.
102
Exiting ACCELL/Generator
When you issue the PREV FORM command from the form you are working on, you
are returned to the ACCELL/Environment menu or the operating system prompt,
depending on how you entered the Generator. If you have not saved all changes
made during the session, ACCELL/IDS asks if you want to continue to exit and
discard the changes.
The sections that follow outline in detail how to perform each of the steps just
described.
Help for the ACCELL/Generator
There are two ways to obtain help in the Generator. You can enter the ACCELL/IDS
HELP MENU command to display a list of all the Generator commands and their
functions. You can also obtain help for individual fields on the Generator forms by
issuing the FIELD HELP command while the cursor is positioned on a field; this
displays information specific to that field.
Entering the Generator
You can enter the Generator directly from the Environment or from the operating
system prompt. From the Environment, choose the Edit ACCELL/Generator Forms
option on the Application/Form Operation menu. When working from the operating
system prompt, make sure you are in the application's home directory, and use the
following syntax:
AGEN [–ai] form_name
For additional information on how to enter the Generator from the Environment, see
Chapter 3. For more information on the additional command parameters available
when entering the Generator from the operating system, see Chapter 9.
Form Definition consists of filling in information on the Form Definition form. When you
first enter the Generator to create a form, the Form Definition form appears as shown
in the following figure:
ACCELL/Generator
103
•
If you are creating a new form, some of the fields on these forms will be empty.
Others will be filled with default field values.
•
If you are editing an existing form, you must press NEXT FORM to call up the
appropriate Form Definition form; it does not appear automatically. You
change entries made on this form by typing new values over the old ones.
replace
stored
update
record 1 of 1
DEFINITION
FORM FORM
DEFINITION
Form Name. fcompany
:fcompany
Target Table:
Occurrences. : 1
Field Order.:ROW
Menu Label. :
File Name.
: fcompany.fq
Help Archive.: fcompany.hlp
Allow Target.: Find: YES Update: YES Delete: YES Add: YES
Sort Field
Ordering
#1:
#3:
#5:
#7:
ASCEND
ASCEND
ASCEND
ASCEND
Master Form: NO
Sort Field
#2:
#4:
#6:
#8:
Ordering
ASCEND
ASCEND
ASCEND
ASCEND
A YES indicates this is the Master Form.
A NO indicates this is a Standard Form.
Enter the name of the form.
F1-Prv Form
F2-Nxt Form
F5-Fld Help F10-More Key
Figure 29. ACCELL/Generator Form Definition Form
The following fields appear on the Form Definition form.
Form Name
Specifies the name of the form. Form names can contain up to 10
characters. The form name is filled in automatically based on the name
you specified when entering the Generator.
Target Table (optional)
Identifies the database table to be automatically referenced by the
104
form. Entry in this field is optional and no entry is allowed for Master
Application forms.
Issue a ZOOM command from this field to see the following form listing
all the database tables available to the application. To choose a target
table from this form, move the cursor to the table name with NEXT
RECORD. Then press PREV FORM to return the table name to the
Form Definition form.
replace
stored
update
record 1 of 1
TARGET TABLE NAMES
company
Form Name.
:
Target Table:
altaddr
Occurrences. : 1
Field Order.:ROW
orders:
Menu Label.
nvenry: fcompany.fq
File Name.
Items
Help Archive.:
fcompany.hlp
employee Find: YES Update: YES Delete: YES Add: YES
Allow Target.:
contact
leads
Sort Field
Ordering
Sort Field
Ordering
#1:
#3:
#5:
#7:
ASCEND
ASCEND
ASCEND
ASCEND
Master Form: NO
#2:
#4:
#6:
#8:
ASCEND
ASCEND
ASCEND
ASCEND
Use PREV FOPRM to select an entry, CANCEL ZOOM to exit.
F1-Prv Form
F2-Nxt Form
Figure 30. ACCELL/Generator Target Table Form
Occurrences Specifies the number of records that will appear on a multi-occurrence
form. The default entry for this field is 1 but you can optionally change
this number. If no number is specified, one record is displayed.
There is no need to change this field entry if you are not defining a
multi-occurrence form. See Marking Repeating Areas, for more
information on multi-occurrence forms.
ACCELL/Generator
105
Field Order
Specifies the order in which the cursor will move between the fields on
the form. The two entries allowed for this field are R for ROW or C for
COLumn. ROW indicates a left to right then top to bottom order;
COLumn indicates a top to bottom then left to right order. The default
field value is ROW.
Menu Label (optional)
Defines what text will appear on a form menu. Form menus are
automatically displayed when there is more than one possible next
form; they let the end user choose between two or more next forms.
Descriptions longer than the window width can be entered and
manipulated with the left and right arrow keys. However, for a single
column format, labels longer than 70 characters (for an 80-character
display width) are automatically truncated by the ACCELL/Manager.
For a two-column format (80-character display width), labels exceeding
35 characters are automatically truncated.
File Name
Specifies the pathname of the file the form is stored in. The file name is
automatically generated based on the name you choose for the form
and the operating system directory you are working in. Standard form
file names have the suffix .fq. Master Application form names have the
suffix .aq. You may optionally change the file name assigned by
ACCELL/IDS.
Help Archive Specifies the pathname of the archive that will store any Help forms
you create for this form. The help archive name is generated
automatically based on the name you choose for the form. Help
archives normally have the suffix .hlp. You may optionally change the
help archive name assigned by ACCELL/IDS.
Allow Target
Specifies the operations to be allowed on the form's target table: Find,
Update, Delete, and Add. The default value for these fields is YES. You
can optionally change any of these fields by typing N for NO to disallow
a specific operation. Find must be allowed for a database search to
take place.
Sort Field (optional)
Specifies the name of the target table field or fields to use when sorting
records retrieved from the database. Names of fields which are to be
106
used as sort keys should be entered in sort order. If nothing is
specified, records are retrieved from the database.
Ordering (optional)
Specifies the field order to use when sorting information retrieved from
the database. Information can be sorted in ascending or descending
order. The default value for this field is ASCENDING. Entries allowed in
this field can be either A for ascending or D for descending. The sort
field or fields will be sorted alphabetically or numerically depending on
the type of information they contain.
Master Form Indicates whether this form is the Master Application form for the
application. Each application must have one and only one Master
Application form. The ACCELL/Generator sets this field for the user.
The field is set to NO for standard forms, YES for Master Application
forms. Note that the ACCELL/Environment creates a default Master
Application form for you.
Saving the Form Definition
To save your form definition entries, press ADD/UPDATE. If you want to discard the
changes you just made, press PREV FORM without pressing ADD/UPDATE. When
you press PREV FORM, you'll be placed inside the forms editor, where you can draw
a new form or edit an existing form.
If there are any forms that will follow the form you just defined, you'll need to fill out the
Choose Next Form form. To continue to Choose Next Form, press NEXT FORM and
the Generator automatically updates your form definition.
Specifying NEXT FORM Characteristics
Next forms are all the forms in an application that immediately follow the current form.
If the form you are defining has any next forms, you need to specify the next form
ACCELL/Generator
107
names and transaction levels by filling in the Choose Next Form form. Press NEXT
FORM from the Form Definition form to call up the following Choose Next Form form:
replace
stored
update
record 1 of 1
CHOOSE NEXT FORM)S)
Form Name.
:
Target Transaction
Table:
Next
Form
Level
Occurrences.
: Name
1
Field Order.:ROW
Menu Label. :
1
File Name.
: fcompany.fq
Help Archive.: fcompany.hlp
Allow Target.: Find: YES Update: YES Delete: YES Add: YES
Sort Field
Ordering
#1:
#3:
#5:
#7:
ASCEND
ASCEND
ASCEND
ASCEND
Master Form: NO
Sort Field
#2:
#4:
#6:
#8:
Ordering
ASCEND
ASCEND
ASCEND
ASCEND
Enter the name of the form.
F1-Prv Form
F2-Nxt Form
F5-Fld Help
F10-More Key
Figure 31. ACCELL/Generator Choose Next Form form.
After you've entered one row of information on this form, press ADD/UPDATE to save
your entry and move the cursor to the next row.
Descriptions of all the fields on the Choose Next Form form follow.
Next Form Name
Names the next form or forms called from the current form by the
NEXT FORM command. Only Standard forms need to be listed here,
not Zoom or Help forms. You need to list the names of all the next
forms that follow the form you are working on.
Transaction Level
Sets the transaction level for the next form. Press FIELD HELP for a list
108
of the available transaction levels. Normally you specify one of the
CONTINUE TRANSACTION levels for next forms, but you could also
start a new transaction on the next form. See the description of the
Choose Next Form section, Chapter 7, for more information on
transaction levels. The default transaction level is 1.
Completing Choose Next Form definition
Before returning to the form you are defining, you can save the entry you made on the
Choose Next Form Specification form by pressing ADD/UPDATE. Alternately, you can
simply press NEXT FORM and the Generator will save the changes for you
automatically before going into the forms editor.
If you choose to exit Choose Next Form by pressing PREV FORM, you will lose the
last change you made unless you saved it with ADD/UPDATE.
Sizing and Locating Forms
You can change a form's physical screen location and its dimensions from within the
Generator. It is a good idea to size and locate the form before you define fields to
insure that there is enough room for all the fields on the form; this way you can also
see how the fields will look in relation to the actual size of the form.
Sizing forms
There are two commands for changing form size:
•
SIZE FORM changes the size of the form without changing the position of the
fields and trim inside the form. When you give this command, the cursor jumps
to the lower right corner of the form. You can then move the cursor to expand
or contract the form size.
The form cannot be made smaller than the area already defined by the form's
fields or trim. It can be enlarged within the limits allowed by the physical
screen. A beep sounds if you attempt to move the cursor beyond the edge of a
boundary or over existing trim. When you press SIZE FORM again, ACCELL/
IDS repaints your form in the correct size.
•
SIZE TRIM changes the size of the form as well as the positioning of its
contents. It works exactly like SIZE FORM except that any trim or fields in the
ACCELL/Generator
109
form are also moved; fields and trim maintain their spatial relationship with the
lower right corner of the form when moved.
Locating forms
Form location is changed by giving the MOVE FORM command from the form you are
creating. When you give this command the cursor moves to the upper left corner of
the form. You can then move the cursor to anywhere in the allowed physical screen
limits to mark the upper left corner of the form.
The first line and last two lines of the screen are reserved as the system display area.
The left and right limits are the edges of the terminal screen. ACCELL/IDS will not let
you move the form into reserved areas; it sounds a beep. Press MOVE FORM again
and ACCELL/IDS will repaint your form in the new location.
CENTER FORM can be used to center the form vertically and horizontally.
CENTER FORM HORIZON centers the current form horizontally.
CENTER FORM VERT centers the current form horizontally.
Adding form trim
Any area inside a form window not occupied by a field can be filled with trim. The term
trim refers to any alphanumeric characters or graphic symbols that are displayed each
time the form is called up. For example, a heading or label that precedes a field is
considered trim.
You enter trim by positioning the cursor and typing the desired information or graphic
decoration. Different portions of the trim can be displayed in different video modes by
changing the attributes for each heading or graphic element.
Displaying and resetting tab stops
The SET TAB STOPS command enables you to control tab settings. Each capital T on
the display indicates the position of a tab stop. You can change the settings by moving
the Ts, or by adding new ones where you wish to insert tab stops.
110
Changing the display mode of new trim
You can change how the trim appears on the screen as you type within with the SET
VIDEO DEFAULTS command. This command lets you choose any combination of
reverse video, blinking, underlining, or low intensity display characteristics by calling
up the following Video Defaults form:
replace
stored
update
record 1 of 1
VIDEO SETTINGS
Reverse. . . :
Blink. . . . :
Underline. . :
Low Intensity:
NO
NO
NO
NO
Should reverse video be enabled? - Yes or No.
F1-Prv Form
F2-Nxt Form
F5-Fld Help
F10-More Key
Figure 32. ACCELL/Generator Video Defaults Form
To activate any of the video display modes listed on the Video Defaults form, position
the cursor on the appropriate field and type Y for YES; repeat this for any other modes
you want to activate. Then press NEXT FORM to save your changes and return to the
form where you are working. Any trim that you type in now will appear in the video
settings you specified on the Video Defaults form.
ACCELL/Generator
111
Changing the display of existing trim
You can use the MARK VIDEO AREA command to change the display mode of trim
that you have already entered on a form. To use this command, first position the
cursor at the beginning of the trim area you want to change. Press MARK VIDEO
AREA and then move the cursor to the other end of the area you want to change.
Press MARK VIDEO AREA again. The following Mark Video Area form appears on
your screen.
replace
stored
update
record 1 of 1
MARK VIDEO AREA
Reverse. . . :
Blink. . . . :
Underline. . :
Low Intensity:
NO
NO
NO
NO
Should reverse video be enabled? - Yes or No.
F1-Prv Form
F2-Nxt Form
F5-Fld Help
F10-More Key
Figure 33. ACCELL/Generator Mark Video Area Form
To activate any of the video display modes listed on the Mark Video Area form,
position the cursor on the appropriate field and type Y for yes; repeat this for any other
modes you want to activate. Then press NEXT FORM to save your changes and
return to the form where you are working. The display of all the trim in the area you
designated will now appear in the new combination of video modes you specified on
the Mark Attributes form.
112
Alphanumeric characters
Numbers, letters, and punctuation are added to the screen simply by typing them in
the desired location. Use the Generator commands to move the cursor, change
editing modes, and delete characters. See section 5.3, under Generator Command
Descriptions, for a description of all the Generator commands. The HELP MENU
command calls up a form with information about the form editing commands.
Graphic trim
The GRAPHICS MODE command makes it possible to enter graphic symbols--for
example, box corners and horizontal and vertical lines as trim--by shifting the
keyboard into graphics mode. Graphics are painted onto the screen by typing the
keyboard keys that correspond to the appropriate characters. The following table
shows which keys are assigned to which characters.
Letter Symbol
Letter Symbol
Letter Symbol
Letter Symbol
Letter Symbol
A
D
G
J
M
B
E
H
K
N
C
F
I
L
O
NOTE:
You can type the graphics keys in either upper or lower case.
Using color graphics
ACCELL/IDS applications can use up to 16 colors on terminals that support local
mapping of video attribute combinations to color. Video attributes set in the Generator
may be mapped to various colors using the setup menus for your particular color
terminal. See the documentation accompanying the terminal for more information on
mapping video attributes to color in ACCELL/IDS.
ACCELL/Generator
113
The following table shows the video attribute combinations available in ACCELL/IDS:
Reverse
Blink
Underline
Low
Intensity
✔
✔
✔
✔
✔
✔
✔
✔
✔
✔
✔
✔
✔
✔
✔
✔
✔
✔
✔
✔
✔
✔
✔
✔
✔
✔
✔
✔
✔
✔
✔
✔
Terminals with built-in mapping capabilities and simple setup menus make it much
easier to map colors. For terminals that do not have these features, you can easily
map single video display attributes to colors by appending color command escape
sequences to single attribute command entries in your system unicap file. This gives
you four colors--one for each of the Reverse, Blink, Underline, and Low Intensity video
display settings.
After defining the characteristics of the form and any next forms, you can begin
defining fields on the form. To define a field, locate the cursor at the field's desired
position and issue the ADD FIELD command. If the cursor is located on an existing
field, the Field Definition form with the entry for that field appears and can be
modified. If no field is defined at that position, a blank Field Definition form appears.
114
NOTE:
At least one field on a standard form must have Stop For Input set to
YES. If no fields are set to Stop For Input, the ACCELL Manager
continuously loops through the form, looking for a field to stop on.
Likewise, if all fields are tab stop fields, at least one must have Stop
For Input set to YES. Otherwise, when the user presses TAB, the
Manager loops through the form, looking for a field to stop on.
The Field Definition form looks like the following:
replace
stored
update
zoom
record 1 of 1
COMPANY:
ADDRESS:
CITY:
STATE:
Field Name...:
MAIN PHONE: In Target Table:
CONTACT:
Field Length...:
Stop for Input.:
Required.......:
FYI Message....:
SALES REP#:
NAME:
PHONE:
FIELD DEFINITION
ZIP:
NO
0
YES
NO
Data Type......:
Window Width...: 0
Tab Stop.......: NO
Case Conversion: NONE
Enter a field name, or ZOOM for a list of fields.
F1-Prv Form
F2-Nxt Form
F5-Fld Help
F10-More Key
Figure 34. ACCELL/Generator Field Definition Form
The following fields are displayed in the Field Definition Form.
Field Name
ACCELL/Generator
Specifies the field name. The name must be distinct from other field
names on this form and can optionally be a database field name from
the target table. If you enter a name that is the same as a target
115
(database) field name, a Y (YES) is automatically filled in on the field
labeled In Target Table.
The Data Type and Field Length values for database fields are automatically assigned
according to the defaults for the data type of that field. Pressing ZOOM from this field
calls up the following list of available database field names to help in selecting an
appropriate name.
replace
stored
update
COMPANY:
ADDRESS:
record 1 of 9
TARGET TABLE FIELDS
CITY:
MAIN PHONE:
CONTACT:
Name
STATE: Type
ZIP:
SALES REP#:
NAME:
PHONE:
Width
co_address_2
co_address_1
STRING
30
STRING
30
co_city
STRING
24
co_key
NUMERIC
5
co_name
STRING
30
co_phone
STRING
14
co_sales_rep
NUMERIC
5
co_state
STRING
2
Use PREV FORM to select an entry, CANCEL ZOOM to cancel.
F1-Prv Form
F2-Nxt Form
F3-Sz Form
F4-Mv Form F5-Fld Help F10-More Key
Figure 35. ACCELL/Generator Target Table Form
In Target Table
Specifies whether or not the field in is the target database table. This
display-only field is automatically filled in with the appropriate value
after you enter a field name and press RETURN. Fields in the target
table (YES) are called database screen fields. Fields not in the target
table (NO) are called non-database screen fields.
116
Data Type
Indicates the ACCELL/IDS data type. The following data types are
available in ACCELL/IDS: STRING, NUMERIC, AMOUNT, DATE,
TIME, FLOAT, or BOOLEAN. You can select the appropriate data type
by typing the first letter of any of the available data types. If you are
defining a database screen field, the Data Type field is automatically
filled in with the data type for the database field when you save your
form entry.
Field Length
Specifies the number of characters that are accepted during input. If
you are defining a database screen field, the Field Length field is filled
in automatically with the database field length when you save your
form entry. If the application end user tries to type in more characters
than are allowed, an error message is displayed. The default value for
this field is set by the session defaults, displayed and modified using
the SET SESSION DEFAULT command.
Window Width
Determines the width of the field window that appears on the form.
This is a display-only field that is filled in when you save your form
entry. The value filled in is the default width for the field's data type. For
example, NUMERIC fields have a default Window Width of 5.
You can change the default setting from the form you are working on
with the SIZE FIELD LEFT and SIZE FIELD RIGHT commands. During
data entry, if Field Length is longer than Window Width, characters will
scroll horizontally to the left until the end of the input area is reached.
Stop for Input Indicates whether the cursor will stop at this field when the form is
executed. When set to NO, the cursor will skip over this field.
Acceptable entries for this field are N for NO and Y for YES. The
default setting is YES.
NOTE:
This does not control whether field language sections will execute.
Field language sections execute whether or not a field has
STOP_FOR_INPUT set to NO.
A form must have at least one field with STOP_FOR_INPUT set to
YES. Otherwise, when the user tries to run the form, the Manager
loops through the form, looking for a field to stop on.
ACCELL/Generator
117
Tab Stop
Specifies whether or not the field is a tab stop. The end user can reach
tab-stopped fields quickly when an application runs by pressing the
NEXT TAB and PREV TAB keys. When the user is tabbing through
fields, ACCELL/IDS skips any ACCELL/Language that applies to nontab fields. The allowed entries for this field are Y for YES and N for NO.
NO is the default setting.
If you have fields with Tab set to YES, make sure that at least one of
them has Stop for Input set to YES. Otherwise, when the user presses
TAB, the Manager continuously loops through the form, looking for a
field to stop on.
Required
Indicates whether, when positioned at the field, the user must enter
something in this field before the application can continue. It does not
apply if the user never enters the field. If set to YES, the application
end user must fill in the field for the application to proceed. Acceptable
entries for this field are N for NO and Y for YES. The default setting is
NO.
Case Conversion
Determines whether the information in the field will be displayed in all
UPPER CASE, all lower case, or as it was entered. Acceptable entries
for this field are U for UPPER, L for lower, or N for none. For example, if
you answer U for UPPER the characters typed in by the end user will
appear in all upper case. The default field value is none, for no case
conversion.
FYI Message Specifies the message to display when the cursor is positioned on the
field you are defining. This message appears on the bottom of the
screen when the application runs.
Exiting the Field Definition form
To leave the Field Definition form and save the information entered, issue the ADD
FIELD command again.
To leave the form and abandon the changes, issue the PREV FORM command
instead.
118
To define more advanced field characteristics, give the NEXT FORM command from
the Field Definition form. Your Field Definition form entry will be saved automatically.
Relocation fields
When you use the ADD FIELD command, the defined field is initially located where
the cursor is positioned. After a field is MOVE FIELD command.
To move a screen field, position the cursor anywhere on the field to be moved, issue
the MOVE FIELD command, and move the cursor to the new location. The field will
move with the cursor. When the location is satisfactory, give the command again. A
beep will sound if the new position overlays either an existing field or trim.
Deleting fields
You can remove fields by locating the cursor anywhere on the field and giving the
DELETE FIELD command. This clears that place on the form and erases any
characteristics defined for that field.
Issuing the NEXT FORM command from the Field Definition form ends regular field
definition and displays the Advanced Field Definition form. This form is used to define
more sophisticated screen field characteristics. Any fields on this form skipped by the
cursor are display-only fields and are automatically set by ACCELL/IDS.
ACCELL/Generator
119
The Advanced Field Definition form looks like this:
replace
stored/modified
update
zoom
record 1 of 1
COMPANY: SSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSS
SALES REP#: NNNNN
ADDRESS:
NAME:
ADVANCED FIELD DEFINITION
PHONE:
CITY: Field Name......:
STATE:
ZIP:
In Target Table.:NO
Data Type .....:
MAIN PHONE:
Field
Length....:0
Window Width...: 0
CONTACT:
Stop for input..:YES
Tab Stop.......: NO
Required........:NO
Case Conversion: NONE
FYI Message.....:
Help Form name..:
Help Archive....:fcompany.hlp
Updateable......:YES
Multi Valued....: NO
Display Format..:
Display Justify.: LEFT
Field Video Attributes
Reverse.....: NO
Underline...: NO
Blink.........: NO
Low Intensity.: NO
Enter a field name, or ZOOM for a list of fields.
F1-Prv Form F2-Nxt Form
F5-Fld Help
F10-More Key
Figure 36. ACCELL/Generator Advanced Field Definition Form
The first six lines on the Advanced Field Definition form are repeated from the Field
Definition form so that you can change the entries for these fields.
In addition, the Advanced Field Definition form contains the following fields
Help Form Name
Names a Help form to be associated with the field you are currently
positioned on. When running an application, the application end user
can issue the FIELD HELP command to display the appropriate Help
form. Help forms are optional. See Creating Help Forms, for
information on defining Help forms. The default Help form name is the
field name with the suffix .hlp appended to it.
120
Help Archive
Specifies the pathname of the file the Help forms are stored in.
ACCELL/IDS generates a help archive file name automatically based
on the form name and the directory where you are working; this name
can be changed if so desired.
Multi Valued
Indicates whether or not this field has a separate, distinct value for
each record in the selected set. Database screen fields are always
multi valued. This means Multi Valued is a display-only field for
database screen fields.
If Multi Valued is filled in with NO, the field you are defining will display
the same value for each record in the selected set. If Multi Valued is set
to YES, the field will hold a separate value for each record in the
selected set.
The following table shows the default values for Multi Valued based on
the relationship between the screen field and the form type.
Type of Field
Type of Form
Multi-valued Default
Database Screen field
All
YES (display-only field)
Non-database Screen
field
SIngle Occurrence
NO
Non-database Screen
Field
Outside repeating area
NO
on Multi-Occurrence form
Non-database Screen
filed
Inside repeating area on
YES
Since non-database screen fields are normally used to display the
results of a calculation or a database lookup, setting Multi Valued to
YES will allow you to perform the calculation or lookup only once, and
then save the results in the selected set.
When Multi Valued is set to NO, you must perform the calculation or
lookup every time the current record changes to see the correct value
on the screen. (You would do this in a WHEN FIELD CHANGES
Language section.)
ACCELL/Generator
121
Updateable
Specifies whether the field can or cannot be updated by editing,
adding, or deleting information. Acceptable entries for this field are Y
for YES and N for NO. YES is the default setting. This attribute can be
used with Stop for Input to let the user stop on a field and scroll or
zoom without changing the field's contents.
Display Justify
Specifies the justification of information that is displayed on forms: left,
right, or centered. The allowed entries are L for LEFT, R for RIGHT, C
for CENTER, or N for NONE. The default is LEFT justification.
Display Format
Specifies the display format for data types with more than one format.
For information, see DISPLAY in section “ACCELL Statement
Descriptions.”
Reverse
Turns the reverse video display for the field on or off. This attribute can
be combined with any of the other three video display attributes.
Acceptable entries for this field are Y for YES and N for NO; NO is the
default setting.
Blink
Turns blinking display for the field on or off. This attribute can be
combined with any of the other three video display attributes.
Acceptable entries for this field are Y for YES and N for NO. NO is the
default setting.
Underline
Turns underlining display for the field on or off. This attribute can be
Acceptable entries for this field are Y for YES and N for NO. The
default setting is NO.
Low Intensity Turns low intensity display for the field on or off. This attribute can be
Acceptable entries for this field are Y for YES and N for NO. NO is the
default setting.
122
Creating help forms
You can create a Help form for any currently defined field with the ADD HELP
command. Creating a Help form is just like creating a Standard form except that you
cannot define screen fields. Help forms are used only for displaying text.
Position the cursor on the field and press ADD HELP. Once the blank Help form
appears, you can size and locate the form as needed. Then type in any help
information you want to appear on the form. When finished, press NEXT FORM to
save your Help form and return to editing your Standard form. If you want to discard
the changes made to the Help form, press PREV FORM.
When the application is run, the Help form is called up in the location you specified
when the end user locates the cursor anywhere on that field and gives the FIELD
HELP command.
Forms that are used to display more than one target table record at a time are called
multi-occurrence forms. For multi-occurrence forms, you must mark the area to be
repeated for each record with the MARK REPEATING AREA DOWN command. This
command works with the Occurrences form attribute. The lines within the marked
area are repeated the number of times indicated by the Occurrences form attribute
when the form is executed. The area outside the repeating area operates normally.
The repeating area may include trim as well as screen fields. Each form can have only
one repeating area.
To mark a repeating area, position the cursor at the top line of the area and enter the
MARK REPEATING AREA DOWN command. Then move the cursor down to the
bottom of the repeating area and enter MARK REPEATING AREA DOWN again.
The SHOW REPEATING AREA command is used to preview the form. It displays the
non-repeating areas in reverse video. This command temporarily overrides any other
commands or settings that change the video mode for field and trim displays. To
ACCELL/Generator
123
return to normal display settings, give the command again or press NEXT FIELD. A
sample multi-occurrence form with SHOW REPEATING AREA active follows:
replace
form:
finventory
row 1 col:1
INVENTORY INQUIRY & MAINTENANCE
MAP:S
PART
DESCRIPTION UNIT
UNIT WEIGHT QUANTITY QUANTITY
NUMBER
PRICE COST (LBS)
ON HAND ON ORDER
NNNNN
SSSSSSSSSS AAAA
F1-Prv Form F2-Nxt Form F3-Sz Form
AAAA AAAA
NNNNN
F4_Mv Form F5-Fld Help
NNNNNNN
F10-More Key
Figure 37. Sample Multi-Occurrence Form in the Generator
124
Press SHOW REPEATING AREA again to return the display to normal. If you set
Occurrences to three, the sample form would appear as follows when the form
executes:
replace
stored
update
record 1 of 2
RECORDS FOUND
COMPANY: J. A. Donne & Associates
SALES REP#: 4
ADDRESS: 501 Broadway
NAME: A Karont
Suite 1050
PHONE: (612) 745-2301
CITY: St. Paul
STATE: MN ZIP: 60451
MAIN PHONE: (408) 340-7100
CONTACT:
INVENTORY INQUIRY & MAINTENANCE
MAP:
E Bishop
Marketing Manager
(408)
340-7160
MAP:
ITEM#
PART#
DESCRIPTION QTY PRICE EXTENSION
QTY SHIP STATUS
PART
UNIT
UNIT
WEIGHT QUANTITY QUANTITY
9
NUMBER DESCRIPTION PRICE COST (LBS)
ON HAND ON ORDER
10
11
5021
Oak Bookcase,
85.50 30.00
40.00
12
0
12
5022
Oak Bookcase, 155.95 50.00
60.00
7
6
13
14
MAP:
Press HELP to locate where you are, or RETURN to continue.
F4-Nxt Rec F5-Fld Help
F10-More Key
Figure 38. Multi-Occurrence Form with Three Occurrences
NOTE:
The ACCELL/Manager expands the form automatically to the correct
size. You can override the default Generator form position and number
of occurrences in ACCELL/Language.
NOTE:
Be sure to position the form in the Generator so the Manager has room
to display the correct number of occurrences. If not, the Manager will
truncate the form until it fits.
ACCELL/Generator
125
Setting session defaults
The Generator uses a set of defaults for form editing sessions. Session defaults affect
things like left and right margin, form length and width, and Help form
length and width. You can change the Generator defaults using the
SET SESSION DEFAULTS to generate the following Session Defaults
form:
replace
stored
update
record 1 of 1
FIELD DEFINITION
1
Left margine.......:
Form Length........: 15
Help Form Length...: 10
Numeric Field Size.: 5
Amount Field Size..: 7
Default Edit Mode.: REPLACE
Display Errors.....: NO
Right Margine.....:
Form Width........:
Help Form Width...:
String Field Size.:
Float Field Size..:
80
60
40
10
7
Specify the left margin for forms created in this session.
F5-Fld Help
F10-More Key
Figure 39. Session Defaults Form
To change an entry on this form, move the cursor to the appropriate entry with
RETURN and type the new value over the old one. Then press NEXT FORM to return
to the forms editor and your changes are saved automatically. You may optionally
press PREV FORM to discard your changes and return to the forms editor.t
NOTE:
126
The FYI line displays instructions to help you enter information on the
current form. FYI is handy to consult while moving between forms, or
while adding information to fields. For more information on display
errors, see section 4.3, Error Handling.
Editing new forms
When you are finished working with a form in the Generator, you may optionally call
up another form to work without leaving the Generator. Press EDIT
NEW FORM to call up the following Edit New Form form. Then type the
form name and press NEXT FORM. The specified form will appear and
you can begin working on it with the Generator.
replace
stored
update
zoom
record 1 of 1
EDIT ANOTHER FORM
Form Name:
NEXT FORM.
Enter a form name and press
Enter the name of the form to edit next and press NEXT FORM to continue.
F3-Prv Rec F4- Nxt
F5-Fld Help
F10-More Key
Figure 40. Edit New Form
Edit New Form can be used to edit existing forms or create new forms. If you would
like to work on the Master Application form, you need to specify the .aq suffix. There is
no need to specify suffixes for Standard forms; ACCELL/IDS automatically appends
the suffix to form names.
ACCELL/Generator
127
In addition to the form name, you can give the same arguments as you would from the
operating system prompt for the AGEN command. See section 9.3, ACCELL
Command Level Development, for information on working with the Generator from the
operating system prompt.
Exiting the Generator
Before you leave the ACCELL/Generator, be sure to save the form you have created
by giving the ADD/UPDATE command. The asterisk (*) on the top line of the system
area means that there are some changes that have not yet been saved.
NOTE:
If you don't save your changes with ADD/UPDATE, you will lose them
when you press PREV FORM or ABORT APPLICATION.
When you press PREV FORM from the form you are working on, you are returned to
either the ACCELL/Environment menu or the operating system prompt, depending on
how you entered the Generator.
128
5.3 Generator commands
The ACCELL/Generator commands used to edit forms are identical to input editing
user commands available in the ACCELL/Manager. Generator commands are usually
assigned to dedicated function keys but can also be issued using the alternate
command sequences designated on the Developer's Command Summary card, in
Appendix B.
For a list of default key assignments, issue the HELP MENU command from within
ACCELL/Generator. Note that the command key assignments can be reassigned
using the unicap utility. See Appendix B for information on customizing key
assignments.
Generator command summary
A list of ACCELL/Generator commands grouped by function follows. Descriptions of
all the commands appear in the Generator Command Descriptions section.
Note that standard ACCELL/Manager user commands, such as NEXT FIELD, PREV
FIELD, NEXT FORM, PREV FORM, ADD/UPDATE, EXPALIN ERROR, HELP MENU,
and FIELD HELP are also used in ACCELL/Generator. For a complete list of user
commands, see section 4.5, “User Commands”.
Form Commands
SIZE FORM
MOVE FORM
CENTER FORM
SIZE TRIM
Screen Field Commands
ADD FIELD
SIZE FIELD LEFT
SIZE FIELD RIGHT
ADD HELP
MOVE FIELD
DELETE FIELD
ACCELL/Generator
129
Cursor Motion Commands
UP
DOWN
MOVE LEFT
MOVE RIGHT
CURSOR LEFT
CURSOR RIGHT
WORD LEFT
WORD RIGHT
Editing Commands
SET VIDEO DEFAULTS
REPLACE/INSERT
CENTER LINE
CENTER ALL
UNREPLACE LEFT
DELETE CHAR
DELETE CHAR LEFT
DELETE LEFT
DELETE LINE
DELETE RIGHT
DELETE TRIM THIS LINE
INSERT LINE
MARK VIDEO AREA
Repeating Area Commands
MARK REPEATING AREA
SHOW REPEATING AREA
Miscellaneous Commands
SET TAB STOPS
ROW/COL DISPLAY
SET SESSION DEFAULTS
EDIT NEW FORM
ABORT GENERATOR
Graphics Commands
130
GRAPHICS MODE
ROUND LOWER LEFT CORNER
ROUND UPPER LEFT CORNER
ROUND LOWER RIGHT CORNER
ROUND UPPER RIGHT CORNER
SQUARE LOWER LEFT CORNER
SQUARE UPPER LEFT CORNER
SQUARE LOWER RIGHT CORNER
SQUARE UPPER RIGHT CORNER
CROSSED LINES
VERTICAL LINES
HORIZONTAL LINE
RIGHT TEE
LEFT TEE
TOP TEE
BOTTOM TEE
For a summary of all commands and their equivalent escape sequences, see
Appendix B.
Generator command descriptions
Most of the commands that follow work in the same basic way: You press them once
to activate them, and press them again to deactivate them. Once these commands
are activated, pressing them a second time saves any changes you’ve made and
returns you to the forms editor.
For example, if you press ADD FIELD and then fill in the Field Definition form,
pressing ADD FIELD a second time will save your entry and return you to the form
you're working on. Other examples of such commands are GRAPHICS MODE, ADD
HELP, and MOVE FIELD.
NEXT FROM will also save your changes and deactivate the command. If there is no
next form, you will be returned to the forms editor. Otherwise, the next Generator form
will be displayed.
Pressing PREV FROM will usually cancel On/Off commands and clear any changes,
unless you've explicitly saved them with ADD/UPDATE
ACCELL/Generator
131
Form commands
SIZE FORM
Enlarges or reduces the size of the form you are creating. After you
enter the command, the cursor jumps to the lower right corner of the
form.
You then use the arrow keys to change the size of the form. The form
size cannot be enlarged beyond the limits of the physical screen and it
cannot be reduced beyond the point where it overlaps any trim or fields
on the form. A beep will sound if you try to move the cursor into an
area that is off limits.
SIZE TRIM
Changes the size of the form as well as the positioning of its contents.
It works exactly like SIZE FORM except that any trim or fields in the
form are also moved; fields and trim maintain their spatial relationship
with the lower right corner of the form when moved.
MOVE FORM
Changes the form's location. After you give the command, the cursor
moves to the upper left corner of the form. You can then move the
cursor to the new location and give the command again; the form and
all its trim and screen fields will move to the new location.
CENTER FORM
Centers the form vertically and horizontally, including all its trim and
screen fields, in the middle of the screen.
CENTER FORM HORIZON
Centers the current form horizontally.
CENTER FORM VERT
Centers the current form horizontally.
Screen field commands
ADD FIELD
132
Lets you create screen fields and define their attributes. If no field is
defined at the location of the cursor, a blank Field Definition form
appears when you give this command. If the cursor is located on an
existing field, a Field Definition form with information on that field
appears and its entry can be modified.
Give the command again to save your changes and return to the forms
editor.
SIZE FIELD LEFT
Changes the window width of the field from the left edge. To use this
command, position the cursor anywhere on the field. Give the
command and the cursor will move to the left edge of the field window.
Move the cursor to the right or left as appropriate, and give the
command again. The field window display on the form changes sizes
as appropriate.
SIZE FIELD RIGHT
Changes the window width of the field from the right edge. To use this
command, position the cursor anywhere on the field. Give the
command and the cursor will move to the right edge of the field
window. Move the cursor to the left or right as appropriate, and give the
command again. The field window display on the form changes size
according to the position of the cursor.
ADD HELP
Lets you create a Help form for the screen field where the cursor is
currently positioned. The command is legal only when the cursor is on
a defined screen field.
If a Help form is not yet defined for that field, a default-sized blank Help
form appears. You can then alter its size and location and add trim.
If a Help form already exists for that field, the Help form is displayed
and you can modify it. Help forms can only contain trim, not screen
fields. All screen field commands are disabled when you are editing a
Help form.
MOVE FIELD
Lets you reposition a screen field within a form. To use this command,
you position the cursor on an existing screen field, issue the command,
move the cursor to the new location, and reissue the command.
ACCELL/Generator
133
ACCELL/IDS will not let you move a screen field so that it overlaps
another screen field or form trim.
DELETE FIELD
Deletes the screen field the cursor is currently positioned on. All field
characteristics defined for the field are also deleted. Any trim remains
on the line.
Cursor motion commands
UP
Moves the cursor up to the same column on the previous line. This
command is assigned to the up arrow key if one is available on your
terminal.
DOWN
Moves the cursor down to the same column on the next line. This
command is assigned to the down arrow key if one is available on your
terminal.
MOVE LEFT
Moves the cursor one character to the left. This command is assigned
to the left arrow key if one is available on your terminal.
MOVE RIGHT
Moves the cursor one character to the right. This command is assigned
to the right arrow key if one is available on your terminal.
CURSOR LEFT
Moves the cursor to the beginning of the word immediately to the left of
where the cursor is positioned. This command is convenient for quickly
moving backward across a line.
CURSOR RIGHT
Moves the cursor to the beginning of the word immediately to the right
of where the cursor is positioned. This command is convenient for
quickly moving forward across a line.
WORD LEFT Moves the cursor to the end of the word immediately to the left of
where the cursor is currently positioned. This command is convenient
for quickly moving backward across a line.
134
WORD RIGHT
Moves the cursor to the end of the word immediately to the right of
where the cursor is currently positioned. This command is convenient
for quickly moving forward across a line.
Editing commands
SET VIDEO DEFAUILTS
Changes the video mode display for trim that you are going to type in.
When you give this command, a menu of video display options
appears on the screen. You can select any combination of reverse
video, blinking, underlining, or low intensity display characteristics by
positioning the cursor on the field for each option and typing Y for Yes.
Press NEXT FORM to save your changes and return to the forms
editor.
The most recent video display settings determine the appearance of
characters you type on the form. You can change the settings back to
normal by calling up the Cursor Attributes menu again and answering
N for NO in all the fields.
REPLACE/INSERT
Switches between two input modes. In Insert mode, characters you
type are inserted immediately before the cursor; any trim and fields
following the cursor move to the right. Trim and fields cannot be moved
off the form. In Replace mode, you can type characters over existing
trim.
CENTER LINE
Centers the line where the cursor is positioned on the form. Both trim
and screen fields are centered.
CENTER ALL Centers all the trim and screen fields both vertically and horizontally on
the form.
DELETE LEFT
Deletes all trim and characters to the left of the cursor on the current
line.
ACCELL/Generator
135
DELETE RIGHT
Deletes all trim and characters to the right of the cursor on the current
line.
DELETE CHAR
Deletes the character under the cursor, moving the rest of the
information on the line one space to the left. This command does not
work if the cursor is positioned over a screen field.
DELETE CHAR LEFT
Deletes the character to the left of the cursor, moving the rest of the
line one space to the left. This command does not work if the cursor is
positioned over a screen field.
Deletes all trim on the line where the cursor is currently positioned. Any
fields defined on that line remain on the form.
DELETE LINE
Removes a line from the form at the current cursor position. Any
screen fields on the line are deleted as well.
INSERT LINE
Adds a blank line to the form at the current cursor position, and moves
all the lower lines down.
MARK VIDEO AREA
Lets you change the video mode for trim you have already typed in. To
use this command, position the cursor at the beginning of the trim area
you want to change and give the command. Then move the cursor to
the end of the trim area you want to change and give the command
again. The Mark Attributes menu appears on the screen.
You can select any combination of reverse video, blinking, underlining,
or low intensity display characteristics by positioning the cursor on the
appropriate fields on the menu and typing Y for YES. Save your
changes and return to the forms editor with the NEXT FORM
command.
136
When you return to the form you are working on, the trim area you
marked will be displayed in the selected combination of video mode
characteristics. You can change the video settings back to normal by
calling up the Mark Attributes menu and answering N for NO in all the
fields.
UNREPLACE LEFT
Works only in Replace mode. It moves the cursor one position to the
left and restores the previously displayed character.
Repeating Area commands
MARK REPEATING AREA DOWN
Lets you mark the repeating area of a multi occurrence form. The term
repeating area refers to one or more consecutive lines of your form that
you want to display a number of times. Marking an area not only
designates what trim to repeat, but also which fields to repeat with that
trim.
To use this command, position the cursor at the top of the area to be
marked. Give the command, move the cursor to the bottom of the
repeating area, and give the command again.
When the application runs, the trim and fields in the marked area are
repeated a specified number of times. The number depends on what
you specified on the Form Definition form in the Occurrences field.
For example, if you have designated five as the number of occurrences
and you have one field in your repainting area, five record values for
that field will be displayed on the form at a time. The areas of the form
outside the repeating area are displayed normally. See Marking
Repeating Areas, for more information on marking repeating areas.
SHOW REPEATING AREA
Lets you preview the form by displaying all repeating fields and trim in
normal video, while displaying non-repeating areas in reverse video.
This command overrides any other commands or settings that change
the video attributes of the fields.
ACCELL/Generator
137
Miscellaneous commands
SET TAB STOPS
Calls up the Setting Tabs form, which shows the current tab stop
settings. Each capital T on the display indicates the position of a tab
stop. You can change the settings by repositioning the capital Ts where
you want tab stops. Use PREV FORM to leave the form.
ROW/COL DISPLAY
Switches the display of cursor coordinates that appears in the upper
system area on and off.
Calls up a form with options that let you change the ACCELL/
Generator default settings for the current session. If you make any
changes on this form, save them and return to the forms editor by
pressing NEXT FORM or SET SESSION DEFAULTS. Press PREV
FORM to cancel your changes.
EDIT NEW FORM
Lets you edit a new form without leaving the Generator. When you give
the command, the Edit New Form form appears. Enter the name of the
form and press RETURN. The specified form will appear on your
screen. Before you give this command, you should save any changes
made to the current form with the ADD/UPDATE command.
For Master Application forms, you need to include the suffix after the
form name. ACCELL/IDS automatically appends the suffix to Standard
forms. You can also include with form names the same arguments
used when entering the Generator from the operating system prompt.
(See Chapter 9 for information on using the Generator from the
operating system prompt.)
ABORT GENERATOR
Cancels the current form, without saving your changes. The command
returns to the point in the system where the user created the form. This
command exits the form immediately and does not execute any
Language sections.
138
Graphics commands
GRAPHICS MODE
Switches the keyboard in and out of graphics mode. When in graphics
mode, each alphabetic key is assigned to a graphic character in the
line graphic character set, instead of standard alphabet letters. This
means you can add graphic trim to your form when in graphics mode
by pressing the appropriate keys on your keyboard. Give the command
again to leave graphics mode.
The following table outlines which graphic characters are assigned to
which alphabetic keys in graphics mode.
Letter Symbol
Letter Symbol
Letter Symbol
Letter Symbol
Letter Symbol
A
D
G
J
M
B
E
H
K
N
C
F
I
L
O
ACCELL/Generator
139
140
Chapter 6: ACCELL/Language overview
6.1 Introduction to the ACCELL/Language
The ACCELL/Language is a comprehensive fourth generation language that lets you
add high-level logic and computation capability to your application. It operates on
database tables and Generator forms, combining information from many different
tables into a single form.
ACCELL/Language scripts contain non-procedural sections, which in turn contain
statements. Each section is identified by a name indicating when the section is
executed. This means that you do not have to worry about the order of the sections.
For example, statements in a BEFORE FIND section are always executed before a
database search regardless of where the section appears in the script.
Each Language section is optional. If you do not include a section, the Manager
automatically performs a default action for you, based on your specifications in the
Generator.
Within each section, you can put as many statements as you want. Statement order is
important within sections and gives you procedural control when you want it.
The Language syntax is designed so that special symbols are optional (for example,
the following are optional: ; # $). This gives your script a neat, easy-to-read
appearance.
This section describes some of the general features of the ACCELL/Language;
variable and form attributes, ACCELL/IDS variables, name classes, system functions,
data types, and operators.
Chapter 7 of this manual explains the ACCELL/Language sections. Chapter 8
explains the ACCELL/Language statements.
141
6.2 Variables
This section describes ACCELL/IDS variable classes, use of variable names and
references, declaration of variables, scope of variables, determining variable types,
and variable assignment compatibility.
ACCELL/IDS Variable classes
ACCELL/IDS’s variables are more flexible than those in most languages. If you are
familiar with programming languages such as BASIC or COBOL, you probably think of
a variable as a named value with a specific type. Another way of thinking about
variables is to imagine a variable as a collection of properties or attributes. From this
point of view, BASIC and COBOL variables are collections of three attributes: name,
value, and type. Every ACCELL/IDS variable has these three attributes and many
more.
In addition, ACCELL/IDS variables may refer to one or more objects at the same time.
An ACCELL/IDS variable may refer to a field in a database record (a database
variable), to a field displayed on a form (a screen variable), a field stored in memory
(general variable), or to a combination of these.
142
Figure 41 summarizes the possible ACCELL/IDS variable classes, and the terms
used to describe them:.
Screen variable
Value on
the
Screen/Target
variable
General variable
Value in
memory
Target variable
Value from
database
Figure 41. ACCELL/IDS Variable Classes
Class
Description
General Variable
Does not refer to either a target field or a screen field
Screen Variable
Refers only to a screen field
Target Variable
Refers only to a target field
Screen/Target Variable
Refers simultaneously to a target field and a screen field
Variable names and references
A variable’s name determines what it references. A variable with the same name as a
screen field refers to the screen field (screen variable). A variable name identical to a
target field name refers to the target field (target variable). If a screen field has the
same name as a target field, a variable with the same name references both the
screen field and the target field (screen/target variable). A variable name distinct from
any currently defined target or screen field is a general variable.
All ACCELL/IDS variable names, no matter what they refer to, have the same form:
ACCELL/Language overview
143
[form_name:][$]variable_name
The form_name is optional and specifies which form the variable appears on; it affects
the variable’s scope and declaration and is discussed in the section Scope of
Variables on.
The $ helps ACCELL/IDS recognize that the character string following it
(variable_name) is the name of a variable.
When you specify the form name and include the $, the two work in concert: the $
immediately classifies the character string as a variable, and the form name reduces
the scope of ACCELL/IDS’s search. Using variables alone will cause the application
to run slower. Consistently using the $ with the form name will ensure faster
applications and guarantee that the application will be consistent with later ACCELL/
IDS releases.
The variable_name, itself, must begin with a letter or an underscore (_). The rest of
the name may consist of letters, digits, or underscores in any combination up to a total
of forty-four characters. ACCELL/IDS does distinguish between upper and lower case
letters in variable names. This means that the names $CONTACT_ADDRESS,
$contact_address, and $Contact_Address represent three different variables.
(ACCELL/IDS keywords, however, are not case sensitive.)
Variable declaration
In many programming languages (Pascal and C, for example), variables must appear
in an explicit declaration before they can be used. In other languages (for example,
BASIC and FORTRAN), the first use of a variable declares it. ACCELL/IDS’s main
method of declaring variables resembles BASIC and FORTRAN. A variable’s first
appearance in an ACCELL/IDS application implicitly declares it. Context and the
variable’s name determine the variable type and the object it identifies.
When you first declare a variable (usually the first time it appears), ACCELL/IDS sets
it to a special value denoted by UNDEFINED. A variable having the value
UNDEFINED may be tested or used in an assignment to another variable. The
variable may not participate in any other operations, such as computations.
144
Scope of variables
A variable’s scope is the range of forms from which it can be referenced. In ACCELL/
IDS, the scope of a variable is the form it is declared on and any successive forms.
That is, any variable appearing on a preceding form that is still active can be
referenced by the current form.
As noted earlier, a variable reference may include a form name as a prefix. For
example, the variable reference employee: $first_name indicates that first_name
appears on the form employee.
When ACCELL/IDS encounters a variable without a prefix, it must perform a check to
determine whether the variable appears on a previous form or is a new variable.
To determine whether or not the variable is new, ACCELL/IDS searches its list of
previous forms (the active form list) to see if the variable appears on any of those
forms. If the variable appears on a previous form, the current use of the variable is
treated as an instance of the old variable. If the variable is not found, its current use is
taken as a declaration.
It is good programming practice to use form name prefixes with variable names. The
use of the form name speeds up application execution by eliminating the search of the
active forms list. Using the form name can also prevent confusion and eliminate
inadvertent references to variables on other forms. For example, in the statement
SET count TO 0;
count refers to a local variable only if it does not appear on any other active form.
Using form name prefixes avoids any confusion as to which variable is being
referenced. Form name references allow you to use the same name on different forms
as in the two statements:
SET form1:count TO 0;
SET form2:count TO 1;
Another way to avoid referencing an old variable with a current name is to include the
variable in a LOCAL declaration. For example, the statement
LOCAL count;
145
guarantees that all references to count refer only to the current form. The general form
of the LOCAL statement is
LOCAL variable_list;
where variable_list is a sequence of variable names separated by commas.
Explicit references to variables on other forms may cause errors in two situations. An
error message is generated if the variable does not exist on the referenced form, or if
the referenced form is not active.
Determining variable type
In most programming languages a variable’s type is determined either by the
declaration it appears in (C, Pascal) or by the form of its name (BASIC, FORTRAN). In
ACCELL/IDS, a variable’s class affects how its type is determined. ACCELL/IDS uses
the following guidelines to determine variable type:
•
A general variable’s type is determined by the first value assigned to it. The
statement that follows concatenates two variables and assigns the result to the
general variable $EMP_FULL_NAME:
SET $EMP_FULL_NAME TO
$EMP_FIRST_NAME + $EMP_LAST_NAME
$EMP_FIRST_NAME and $EMP_LAST_NAME are string variables; thus, after the
assignment, $EMP_FULL_NAME is a string variable.
•
A screen variable’s type is determined by the ACCELL/Generator when the
user produces a form.
•
A target variable’s type is determined by the field in the database it refers to.
•
A screen/target variable has the same type as the corresponding database
field. The corresponding screen field must also have the same type.
NOTE:
146
A general variable’s type may be changed by assigning UNDEFINED
to it and then assigning a new value of a different type. With all other
variables, assignments made to the variable must be assignmentcompatible with the type.
Variable assignment compatibility
ACCELL automatically performs some type conversions in assignment statements
(SET and SET/SELECT). Data type combinations that are automatically converted
are assignment-compatible.
The table below shows which data types are assignment-compatible. The row
headings indicate the data type of the receiving variable. The column headings
indicate the data type of the value being assigned. Performing an assignment where
the resulting type is not defined in the table will produce a run-time error. Conversion
functions are available for some non-assignment compatible data types. See
ACCELL/IDS Type Conversion Functions.
To
Set
Numberic
Float
NUMERIC
NUMBERIC
NUMERIC* NUMERIC*
FLOAT
FLOAT
FLOAT
FLOAT
AMOUNT
AMOUNT
AMOUNT*
AMOUNT
BOOL
STR
DATE
TIME
Amount
Bool
Str
Date
Time
BOOL
STR
DATE
TIME
* indicates value is truncated
147
6.3 ACCELL/IDS attributes
In ACCELL/IDS, forms and variables are described by attribute lists. ACCELL/IDS
maintains such a list for every form in an application and for every variable on a form
or in a Language script. The values assigned to attributes determine the
characteristics of a form or variable. Attribute values can be directly tested and
manipulated by an ACCELL/IDS application, allowing developers to produce dynamic,
powerful scripts.
All ACCELL/IDS forms have the same set of attributes-the same elements in their lists
of characteristics. These attributes include where the form is displayed, the form
name, what the form’s next and previous fields are, and which database operations
are allowed.
A variable may have several different sets of attributes, depending on its class.
General variables have only a few attributes. Screen variables have the same
attributes as general variables plus a special set of screen attributes controlling such
things as case conversion and display format. Similarly, target variables possess a
unique set of target attributes. Screen/target variables have the attributes of general,
screen, and target variables.
Some attributes may be changed by Language scripts, but they are also manipulated
by ACCELL/IDS during execution. The following table shows a partial list of target
variable attributes and possible values for them. (These will be discussed in detail a
little later.)
Beginning values
Attribute
Attribute Value
Variable Name
$doc_name
Value
Fenster, Alexander
CLEAR_FIND_EXP
[A–M]*
SEARCH-RANGES
UNDEFINED
CLEAR_ADD_EXP
UNDEFINED
Notice that although the CLEAR_FIND_EXP has a value, the SEARCH_RANGES
attribute does not. When a CLEAR TO FIND is done, ACCELL/IDS evaluates the
148
CLEAR_FIND_EXP attribute, expands it into one or more search ranges, and assigns
those ranges to the SEARCH_RANGES attribute. After a CLEAR TO FIND, the
attribute list for $doc_name would look like this:
After CLEAR TO FIND
Attribute
Attribute Value
Variable Name
$doc_name
Value
Fenster, Alexander
CLEAR_FIND_EXP
[A–M]*
SEARCH-RANGES
[A–M]*
CLEAR_ADD_EXP
UNDEFINED
In this case, ACCELL/IDS evaluates the CLEAR_FIND_EXP and places the results in
SEARCH_RANGES. Note that the SEARCH_RANGES value can be changed by
other statements or user commands.
Similarly, when a CLEAR TO ADD is done, the Clear to Add expression
(CLEAR_ADD_EXP) is evaluated, and the Value attribute is changed accordingly.
After CLEAR TO ADD
Attribute
Attribute Value
Variable Name
$doc_name
Value
UNDEFINED
CLEAR_FIND_EXP
[A–M]*
SEARCH-RANGES
[A–M]*
CLEAR_ADD_EXP
UNDEFINED
Variable attributes
All ACCELL/IDS variables have two attributes in common: ACCELL_TYPE and
CLEAR_ADD_EXP. ACCELL_TYPE is a string indicating the ACCELL/IDS variable
type (e.g., NUMERIC, DATE, ...). CLEAR_ADD_EXP is the Clear to Add expression.
These are the only attributes that a general variable has besides its value.
149
The table below lists all of the general variable attributes. Settable attributes may
appear on either side of an assignment statement. Non-settable attributes can appear
only on the right hand side of assignment statements.
General Variable
Attribute Name
(type) Description
ACCELL_TYPE
(string) ACCELL variable type
CLEAR_ADD_EXP
(expression) Clear to Add expression
Settable
Yes
Notice that CLEAR_ADD_EXP is an expression and not a single value. When a Clear
to Add is done, ACCELL/IDS evaluates the Clear to Add expression and assigns the
resulting value to the variable.
Variable attribute names are not case sensitive since they are considered ACCELL/
IDS keywords. This means that CLEAR_ADD_EXP, Clear_Add_Exp, and
clear_add_exp all refer to the same attribute.
Values of an attribute can be referenced by using the variable name followed by a
colon and the attribute name:
[form_name:][$]variable_name:attribute
Target variable attributes
Through the target variable attributes, an application can gain access to information
about the database field linked to the target variable.
You may reference target variable attributes the same way as any other variable
attribute-use the variable name followed by a colon and the attribute name. For
example:
co-key: CLEAR_FIND_EXP
Target variable attribute names are not case sensitive. This means that DB_LENGTH,
Db_Length, and db_length all refer to the same attribute.
150
The following table lists the valid target variable attributes. Settable attributes may
only on the right-hand side of assignment statements.
Target Variable
Attribute Name
(type) Description
Settable
TARGET_FIELD
(string) Long name for database target table
field
DB_LENGTH
(numeric) database field length
CLEAR_FIND_EXP
(expression) Clear to Find expression
SEARCH_RANGES
(expression) current search criteria used in the Yes
FIND command
Yes
Note that CLEAR_FIND_EXP is an expression and not a single value. When a
CLEAR TO FIND is done, ACCELL/IDS evaluates the Clear to Find expression and
assigns appropriate values to the attribute SEARCH_RANGES.
Setting the CLEAR_FIND_EXP and SEARCH_RANGES target attributes allows the
developer to alter the composition of the search criteria that the ACCELL/Manager
uses when the user presses FIND.
To understand how to use these two attributes, it is necessary to describe the steps
that the ACCELL/Manager performs when the user presses FIND.
Before it can execute the FIND command, the ACCELL/Manager must be placed in
Find mode. Find mode tells the Manager that the user will be entering search criteria
on the current form. The search criteria are used to search the form’s target table for
matching records.
A form is in find mode after one of the following steps:
•
the end user presses CLEAR TO FIND
•
the ACCELL/Language specifies CLEAR TO FIND; e.g., NEXT ACTION IS
CLEAR_TO_FIND.
•
the ACCELL/Language sets the current form’s AUTO_FIND attribute to TRUE.
See Form Attributes.
•
the current form’s AUD_ON_ENTRY is set to FALSE, the default for this
attribute. See Form Attributes.
151
When the ACCELL/Manager enters Find mode, it performs a Clear to Find. Whether
called implicitly (within an ACCELL/Language script via AUTO_FIND/
AUD_ON_ENTRY) or explicitly (the user presses CLEAR TO FIND), the Clear to Find
is always performed.
When Clear to Find executes, the CLEAR_FIND_EXP attribute is evaluated. If
CLEAR_FIND_EXP is set, it contains the target variable’s initial search conditions.
CLEAR_FIND_EXP contains an expression, not a single value.
Sample CLEAR_FIND_EXP expressions are:
’5000-7500’
’Ch’
’5-75, 120-370, 400, 410, 420’
During the FIND operation, the SEARCH_RANGES attributes of the target variables
are used to determine which records to actually select. The SEARCH_RANGES
expression can be reassigned a new expression when the user enters new criteria on
the form.
The SEARCH_RANGES attribute may also be modified in the ACCELL/Language. An
ACCELL/Language script can assign a new expression to SEARCH_RANGES. Such
modifications will not appear on the form, but they will affect which records are
selected during the FIND. Once modifications to the SEARCH_RANGES are made in
the Language, the user cannot change the search criteria.
Screen variable attributes
Only variables that have the same name as a screen field (that are screen variables)
have screen variable attributes. Screen variable attributes are initialized in the
ACCELL/Generator.
The screen variable display formatting attributes provide flexibility in displaying data
on the screen. Formatting attributes affect the number of characters allowed in a
screen field (length), the number of leading and trailing characters permitted, and the
justification of information entered into the field.
152
A screen variable’s ACCELL/IDS type determines the variable’s default display and
input formats. (See the discussion of the DISPLAY and INPUT statements in the
ACCELL Statement Description section on for more information about default
formats.)
You can obtain or set the value of a screen variable attribute in the same way as any
other variable attribute-use the variable name followed by a colon and the attribute
name. For example:
SET S_NAME:DISPLAY_JUSTIFY TO ’RIGHT’
Screen variable attribute names are not case sensitive. This means that
LOW_INTENSITY, Low_Intensity, and low_intensity all refer to the same attribute.
The following tables list the valid screen variable attributes. Settable attributes may
only on the right-hand side of assignment statements.
Screen Variable
Attribute Name
(type) Description
FIELD_NAME
(string) screen field name
REQUIRED
(boolean) input required on field
Yes
UPDATEABLE
(boolean) field may be updated
Yea
FINDABLE
(boolean) field may have search value specified
Yes
MULTI_VALUED
(boolean) field is in the repeating area on a multioccurrence form
CASE_CONVERSION
(string) indicates any case conversion to be performed on
input; a value of UPPER maps all input to upper case
characters; a value of LOWER maps all input to lower case
characters; NONE performs no conversion
Yes
REVERSE
(boolean) reverse attribute on
Yes
BLINK
(boolean) blink attribute on
Yes
UNDERLINE
(boolean) underline attribute on
Yes
LOW_INTENSITY
(boolean) low intensity on
Yes
DATA_TYPE
(string) the type of data input/displayed
FIELD_LENGTH
(numeric) field length for input
DISPLAY_FORMAT
(string) the field’s display format; formats can be directly
assigned to the attribute; see the DISPLAY statement for a
discussion of display formats
Settable
Yes
153
Screen Variable
Attribute Name
(type) Description
Settable
DISPLAY_JUSTIFY
(string) a string containing one of the keywords LEFT,
RIGHT, or CENTERED to indicate display justification
Yes
ROW
(numeric) field origin row coordinate
Yes
COL
(numeric) field origin column coordinate
Yes
WINDOW_WIDTH
(numeric) number of characters on screen used for field
Yes
STOP_FOR_INPUT
(boolean) when set to true, the field becomes an input field
Yes
AUTO_ZOOM
(boolean) if enabled, zoom is automatically executed
Yes
FYI_MESSAGE
(string) information message displayed automatically
Yes
FYI_ROW
(numeric) row of FYI message origin
FYI_COL
(numeric) column of FYI message origin
TAB_STOP
(boolean) field is tab stopped
HELP_FORM_NAME
(string) name of field’s Help form
HELP_ARCHIVE
(string) path to Help form archive
HELP_FORM_ROW
(numeric) row number of Help form origin
Yes
HELP_FORM_COL
(numeric) column number of Help form origin
Yes
NEXT_FIELD
(string) the name of the next field to execute after this field
Yes
AUTO_ACCEPT
(boolean) when TRUE, causes automatic skipping to the
next field when the user fills up the current field
Yes
Yes
Form attributes
Each time ACCELL/IDS executes a form, all form attributes are set to their default
ACCELL/Generator settings, or the settings specified in the form’s script. Settings
specified in scripts take precedence over those specified in the Generator.
Form attributes appear in the following format in assignment statements:
[form:]attribute
form is the form name. The brackets indicate that form may be omitted if the attribute
is for the current form.
Form attribute names are not case sensitive. This means that ROW_ORIGIN,
Row_Origin, and row_origin all refer to the same attribute.
154
The table that follows lists all of the form attributes. The values of settable attributes
may be changed in scripts. Settable attributes may appear on either side of an
assignment statement. Non-settable attributes can only appear on the right hand side
of assignments.
Form
Attribute Name
(type) Description
Settable
ROW_ORIGIN
(numeric) upper left-hand corner of form row number
(absolute)
COL_ORIGIN
(numeric) upper left-hand corner of form column number
(absolute)
FORM_NAME
(string) name of form
HEIGHT
(numeric) number of rows form occupies
WIDTH
(numeric) number of columns form occupies
TARGET_TABLE
(string) name of target table (undefined if none)
CUR_NEXT_FIELD
(string) name of current next field
PREV_FIELD
(string) name of previous field on which input occurred
PREV_FORM
(string) name of previous form
FIND_ALLOWED
(boolean) Find allowed for duration of form
Yes
UPDATE_ALLOWED
(boolean) Update allowed for duration of form
Yes
DELETE_ALLOWED
(boolean) Delete allowed for duration of form
Yes
ADD_ALLOWED
(boolean) Add allowed for duration of form
Yes
MENU_LABEL
(string) label displayed in CHOOSE NEXT FORM or
CHOOSE FIRST FORM statement on menu
OCCURRENCES
(numeric) maximum number of occurrences of repeating
area
Yes
AUD_ON_ENTRY
(boolean) if TRUE then Add mode is default, else Find
mode; overridden by AUTO_FIND attribute
Yes
CLEAR_AFTER_AU
(boolean) if TRUE an implicit Clear to Add is done after an
Add
Yes
AUTO_COMMIT
(boolean) if TRUE, each Add/Update operation is logged, all Yes
locks downgraded to SLOCKS, and the current transaction
continues
FIRST_FIELD
(string) name of the first field to be executed
Yes
AUTO_FIND
(boolean) executes a FIND command after the BEFORE
FORM section is completed
Yes
FIND_COUNT
sets size of group of records to be added to selected set
Yes
Yes
155
6.4 ACCELL/IDS name classes
ACCELL/IDS uses many different names, each of which must be distinguished in
some way. Part of identifying a name is determining its class-what kind of name it is.
The sections below list the various name classes, their characteristics, and what
ACCELL/IDS uses to determine a name’s class. ACCELL/IDS relies extensively on
context to determine a name’s class. If ACCELL/IDS cannot determine the class from
the context, it assumes the name is a form name.
A name can be in more than one class, depending on the context. For example, a
target table name (database name) can also be a form name.
Database names
All target table names and names of target table fields are classified as database
names. These names are case sensitive, and use the form table_name.field_name, or
# field_name.
NOTE:
The symbol # is short for the table name followed by a period. Either #
or the table name and a period must precede emp_department and
emp_job_code, since they are database field names.
ACCELL/IDS names
All ACCELL/IDS system functions and system variables are classified as ACCELL/
IDS names. These names are case sensitive: they must be in lower case. a system
function or system variable name is always followed by a special suffix character: the
dollar sign ($), e.g., current_date$().
Language keywords
All ACCELL/IDS keywords such as SET, TO, NEXT, and WHERE are classified as
keyword names. Only context distinguishes keyword names from form and user
names. Keyword names are not case sensitive. This means that where and set are
equivalent to WHERE and SET.
156
Attribute names
All variable and form attributes are classified as attribute names. These names are
not case sensitive. They are treated as reserved words for the purpose of
distinguishing between different name classes.
Form names
All form and application names are classified as form names. These names are
distinguished from keyword and user names by context only. Form names are case
sensitive.
User names
All user-defined names, including user functions, screen fields, target fields, and
general variables, are user names. These names are case sensitive and may be
preceded by a special character ($) that identifies them as user names. If no special
character is included, then they are distinguished from other name classes by context.
The following table indicates which names are case sensitive and which are not:
Name class
Case sensitive
Database names
Yes
ACCELL/IDS names
Yes
Language keyword
No
Attribute names
No
Form names
Yes
User names
Yes
A general rule for determining case sensitivity is that all ACCELL/IDS reserved words,
including attribute names, are not case sensitive. All other names are case sensitive.
157
6.5 ACCELL/IDS system functions and variables
ACCELL/IDS provides a set of system functions that, among other functions, allow
you to include non-printing characters in strings, get the current date and time, obtain
information about the current record, and get information about the user’s name and
group. There are also several string functions that help you handle string information
more efficiently.
ACCELL/IDS also provides functions to convert data of one type to another type.
These functions are listed separately in the ACCELL Type Conversion Functions
section.
ACCELL/IDS system variables let you test and change the internal state of the
ACCELL/Manager. Applications can change system variable values by using SET
statements.
ACCELL/IDS system functions
The following section briefly defines and summarizes each ACCELL/IDS system
function.
aud_mode$()
158
Description:
Determines if the current mode of operation is Add/Update/Delete
mode.
Arguments:
none
Returns:
TRUE
if the current mode of operation is Add/Update/Delete
mode
FALSE
if the current mode of operation is not Add/Update/
Delete mode; in this case the current mode of operation
is Find mode. This function is useful in the ON NEXT
FORM (or ON PREVIOUS FORM) section to determine
the current mode of operation from which a NEXT
FORM (or PREV FORM) command was issued.
Related Functions:
is_current_record_stored$(), record_is_current$(),
current_record_count$()
Example:
ON NEXT FORM
IF NOT ( aud_mode$() ) THEN
BEGIN
SET acct:$acctno:SEARCH_RANGE TO ’100’
NEXT ACTION IS FIND
END
AFTER FIND IF ( record_is_current$() ) THEN
NEXT ACTION IS NEXT FORM
would set the search range for the account numbers to 100 only if the current mode of
operation was Find mode. If the search located records, the application would then
move to the next form.
beep$(beep_count)
Description:
Makes the user’s console beep by sending ASCII bell characters. This
function is used to notify the user of some special event such as an
error message, invalid action, or important task.
Arguments:
beep_count
Returns:
none
the number of bell characters to send to the terminal
Example:
IF finventory:$nv_q_on_hand = 0 THEN
BEGIN
beep$(3)
DISPLAY ’No more items in inventory -- Time to reorder!’
FOR FYI_MESSAGE WAIT
END
159
would send three ASCII bell characters to the user’s console when the item’s quantity
on hand in inventory reaches zero.
char_code_to_str$(ascii_val)
Description:
Translates an ASCII value into a single character string. This function
is used primarily to include non-printing characters in strings.
Arguments:
ascii_val
Returns:
Single character for ASCII value ascii_val
the decimal ASCII value to be translated. This value
must be an integer in the range 0 to 127 (valid ASCII
values).
Related Functions:
str_to_char_code$()
Example:
SET ctrlC TO char_code_to_str$(3)
would assign the ASCII representation of ^c (CTRL c) to the ACCELL/IDS variable
ctrlC.
clip_str$(string)
Description:
Removes leading and trailing blanks from a string. This function does
not remove embedded blanks. This function is useful for removing
extra blanks from a database string field.
Arguments:
string
Returns:
The clipped string (string with leading and trailing blanks removed)
string from which to remove leading and trailing blanks
Example:
DISPLAY clip_str$(’
160
2167 E. Main St.
’)
would display the string ‘2167 E. Main St.’ in the FYI message line.
close_message_file$()
Description:
This function closes a previously opened message file. Only one
message file can be open at a time. See the description for the
ACCELL/IDS system function get_message$() for a complete
description of message files.
Arguments:
none
Returns:
none
Related Functions:
get_message$(), open_message_file$()
Example:
See example for ACCELL/IDS system function
get_message$()
current_date$()
Description:
Obtains the current date from the operating system.
Arguments:
none
Returns:
The current date as stored by the operating system. This date is in the
same format as the ACCELL/IDS data type DATE.
Related Functions:
current_time$()
Example:
IF fleads:$ld_date_found = UNDEFINED THEN
SET fleads:$ld_date_found TO current_date$()
would assign the current date to the ld_date_found variable if this variable was
undefined.
161
Description:
Determines the number of records in the selected set.
Arguments:
none
Returns:
While in Find mode, the return value will be zero. After completing a
successful find, the return value will reflect the number of records
selected from the database. The return value will then be adjusted
accordingly if adds and deletes are completed. Note that immediately
after a CLEAR TO ADD command, the return value is not adjusted.
Since a CLEAR TO ADD command entered from Find mode would
result in a return value of zero, current_record_count$() cannot be
used to determine ACCELL/IDS’s current mode of operation.
Related Functions:
current_record_num$()
is_current_record_stored$()
Example:
IF ( current_record_count$() = 0 ) THEN
DISPLAY ’Search found no records, please re-enter search criteria’
would determine if a FIND has successfully located matching records.
Description:
Determines the relative number of the current record within the
selected set.
Arguments:
none
Returns:
The relative number of the current record within the selected set. If no
records have been selected, this function returns zero (0).
Related Functions:
162
Example:
ON NEXT RECORD
IF ( current_record_num$() = (current_record_count$() )
THEN
NEXT ACTION IS CLEAR_TO_ADD
would determine if the current record was the first record of the selected set.
current_time$()
Description:
Obtains the current time from the operating system.
Arguments:
none
Returns:
The current time as determined by the operating system. This time is in
the same format as the ACCELL/IDS data type TIME.
Related Functions:
current_date$()
Example:
IF time_entered = UNDEFINED THEN
SET time_entered TO current_time$()
would assign the current time to the time_entered variable if this variable was
undefined
flush_to_disk$()
Description:
This function causes the ACCELL/Manager to call the operating
system system function sync(). The sync() function causes the
operating system to write the current user memory buffers to disk.
Calling flush_to_disk$() flushes all previously unwritten buffers out to
disk so that all file modifications up to that point are saved. For more
163
information on sync(), refer to your operating system Reference
Manuals.
Arguments:
none
Returns:
none
Example:
If the CHOOSE NEXT FORM statement specifies START TX
RECORD_CONSISTENCY or START TX SET_CONSISTENCY, you may want to call
flush_to_disk$() first to ensure all information for the current transaction has been
saved.
ON NEXT FORM
flush_to_disk$()
get_message$(msgnum)
Description:
This function obtains a message from the current message file. A
message file is a file you can create to store your application
messages. This file assigns an integer number to each message
string. Using a message file instead of embedding the messages in
your code significantly reduces memory usage at runtime as well as
simplifying code maintenance.
Lines in the message file have the format:
#### | xxxxxxxxxxxxxxxxxx
where ‘####’ is the line’s message number and ‘xxxxxxxxxxxxxxxxxx’ is the
message text. The delimiter is any character following the first blank. In this
example, the delimiter is ‘|’. The get_message$() function looks for a line in the
message file that begins with the number msgnum. A message file must be
opened with the open_message_file$() function before get_message$() can
extract messages.
Arguments:
164
msgnum
the integer message number of the message to be
retrieved from the message file
Returns:
The message text which corresponds to the line in the message file
whose message number is msgnum.
Related Functions:
open_message_file$(), close_message_file$()
Example:
$UNIFY/unifymsgs is an example of a message file.
Example:
Message
98
99
100
101
file /usr/apps/messages segment:
| Invalid entry, please try again!
| Inventory number out of range
| Record not updated!
| Record updated and stored!
Language segment:
IF ( open_message_file$(’/usr/apps/messages’) = 0 ) THEN
BEGIN
DISPLAY get_message$(100) FOR FYI_MESSAGE WAIT
close_message_file$()
END
This Language segment displays the message:
Record not updated!
in the FYI message line.
getenv$(string)
Description:
Obtain the value of an environment variable in the user’s environment.
Arguments:
string
Returns:
Returns the value of an environment variable. The value returned is a
string.
the name of the environment variable whose value is
needed.
165
Example:
Useful to determine values in the user’s environment before deciding
what actions to take.
SET path_name TO getenv$(’DBPATH’)
would get the value of the environment variable DBPATH and assign this value to the
ACCELL/IDS variable path_name.
glob_str_compare$(string,mask)
Description:
This function compares a string with a string mask. See String
Comparison Masks, for more information on glob_str_compare$() and
search masks.
Arguments:
string
string to compare
mask
a string containing the characters of the search pattern
TRUE
if the string matches the mask
FALSE
if the string does not match the mask
Returns:
Related Functions:
reg_exp_str_compare$()
Example:
This example displays ‘Matched String!’ when the variable a_strng
contains a string of three digits.
IF ( glob_str_compare$(a_strng, ’[0-9][0-9][0-9]’) ) THEN
DISPLAY ’Matched String!’ FOR FYI_MESSAGE WAIT
group_id$()
Description:
166
Obtain the user’s group ID number from the operating system groups.
This function allows you to take advantage of the security groups
already set up by the operating system. You can take actions in your
applications based upon the operating system group which the
particular user belongs to.
Arguments:
none
Returns:
The integer value of the user’s group ID number.
Related Functions:
group_name$()
Example:
IF ( group_id$() > 6 ) THEN
DISPLAY ’You do not have permission to view this field’
group_name$()
Description:
Obtains the name of the user’s group from the operating system
groups. This function allows you to take advantage of the security
groups already set up by the operating system. You can take actions in
your applications based upon the operating system group which the
particular user belongs to.
Arguments:
none
Returns:
The string value of the user’s group name. The group name is the
name of the group of the user running the application.
Related Functions:
group_id$()
Example:
IF ( group_name$() = ’payroll’ ) THEN
UPDATE employee
SET #emp_salary TO femployee:$new_salary
WHERE #emp_name = femployee:$emp_lname
167
Description:
Determines if there is a record in the database (the target record) with
the same field values as the current current record. This function is
useful for determining whether you need to update a record.
Arguments:
none
Returns:
TRUE
there exists a target record with contents identical to the
current record. In this instance, an ADD/UPDATE
command will not change the field values in the target
record because the current record and the target record
are exactly the same.
FALSE
the current record has not been stored. An ADD/
UPDATE command will affect the target record. After
the ADD/UPDATE, the target record will be updated
with the current record field values. Changing form
context (for example, with PREV FORM) may cause the
new field values in the current record to be lost unless
they are stored in the database.
Related Functions:
Example:
ON PREVIOUS FORM
IF ( NOT is_current_record_stored$() ) THEN
last_command$( )
Description:
168
The last_command$() system function returns a numeric value
indicating the last ACCELL/IDS user command executed. When
checking the last_command$() return value, use the return value
names in your 4GL script. These return value names are listed in the
Return Status column of Figure NO TAG.
To use the last_command$() function, you must use the ACCELL/IDS
preprocessor statement, #include, to include the header file
command.h in your 4GL script. This header file contains definitions for
the last_command$() return value names. It is located in the include
directory of the ACCELL/IDS release.
NOTE:
The last_command$() function does not return a value for user
commands initiated with the NEXT ACTION command. This function
only returns the value when the end user issues a user command.
Arguments:
none
Returns:
A NUMERIC value-see the following table for a list of return value
names.
last_command$() Return Values
Return status
Last user command
CMD_PFRM
PREV FORM
CMD_NFRM
NEXT FORM
CMD_PFLD
PREV FIELD
CMD_NFLD
NEXT FIELD
CMD_PTAB
PREV TAB
CMD_NTAB
NEXT TAB
CMD_CTOF
CLEAR TO FIND
CMD_FIND
FIND
CMD_ZOOM
ZOOM
CMD_CNZM
CANCEL ZOOM
CMD_CTOA
CLEAR TO ADD
CMD_ADUP
ADD/UPDATE
CMD_DLRC
DELETE RECORD
CMD_NREC
NEXT RECORD
CMD_PREC
PREV RECORD
CMD_NSET
NEXT SET
CMD_PSET
PREV SET
169
last_command$() Return Values
Return status
Last user command
CMD_FREC
FIRST RECORD
CMD_LREC
LAST RECORD
CMD_EXIT
ABORT APPLICATION
CMD_MNSL
MENU SELECT
CMD_MNCN
MENU CANCEL
Example:
#include "command.h"
:
:
/* Reject the LAST RECORD command but allow NEXT RECORD
and NEXT SET */
ON NEXT RECOR
IF ( last_command$() = CMD_LREC ) THEN
REJECT OPERATION
ELSE
DISPLAY ’Moving to next set of records’
The ON NEXT RECORD 4GL section executes when the user commands NEXT
RECORD, NEXT SET and LAST RECORD execute. This code sample uses REJECT
OPERATION to reject the LAST RECORD command. The NEXT RECORD or NEXT
SETS would still execute the statements in ON NEXT RECORD. Note the #include
statement to include the last_command$() header file, command.h.
open_message_file$(filename)
Description:
170
This function opens a file of messages. If a message file is already
open, open_message_file will close it, first. Messages are stored, one
per line, in a special format. Multiple message files can exist. However,
only one message file can be open at a time. See the explanation of
the ACCELL/IDS system function get_message$() for a more complete
description of message files.
Arguments:
filename
string which contains the full pathname of the message
file to open
Returns:
0 - if the message file is successfully opened; otherwise, the value of
errno is returned
Related Functions:
close_message_file$(), get_message$()
Example:
See example for ACCELL/IDS system function
get_message$().
pad_str_left$(string, padstr, length)
Description:
This function pads the left side of a string with a specified character.
Arguments:
string
The string to pad
padstr
The character to pad the left of the string with. If the pad
string is null, string remains unchanged. If the pad string
contains more than one character, the first character of
the string is used as the pad character.
length
The desired length of the padded string. If the pad
length is less than the string argument, then string
remains unchanged.
Returns:
The padded string
Related Functions:
pad_str_right$()
Example:
SET str TO ’four’
171
IF ( pad_str_left$(str, ’x’, 10) = ’xxxxxxfour’ ) THEN
DISPLAY ’Left padded string with length of 10’ FOR
FYI_MESSAGE
pad_str_right$(string, padstr, length)
Description:
This function pads the right side of a string with a specified character.
Arguments:
string
The string to pad
padstr
The character to pad the right of the string with. If the
pad string is null, string remains unchanged. If the pad
string contains more than one character, the first
character of the string is used as the pad character.
length
The desired length of the padded string. If the pad
length is less than the string argument, then string
remains unchanged.
Returns:
The padded string
Related Functions:
pad_str_left$()
Example:
SET str TO ’four’
IF ( pad_str_right$(str, ’x’, 10) = ’fourxxxxxx’ ) THEN
DISPLAY ’Right padded string with length of 10’ FOR
FYI_MESSAGE
172
push_shell$()
Description:
Allows the user to access the operating system shell from within an
ACCELL/IDS application. The operating system environment variable
SHELL determines which type of shell is started. To exit this shell, the
user types ‘exit’ (^d, or the shell terminate command).
Arguments:
none
Returns:
none
Example:
IF (user_response = ’Y’ ) THEN
push_shell$()
record_is_current$()
Description:
Determines if there is a current record in the application. A current
record is the target record currently displayed on a form.
Arguments:
none
Returns:
TRUE
if there is a current record: when you have done a FIND
and found records. If the current record has modified
some of the target record fields but has not yet been
stored with , record_is_current$() still returns TRUE.
FALSE
if there is no record current. This function returns
FALSE after an unsuccessful find, immediately
following a command (there is no target record), or
when there is a set on a form with no target table.
Example:
ON NEXT FORM
IF NOT record_is_current$() THEN
173
REJECT OPERATION
reg_exp_str_compare$(string, mask)
Description:
Enables regular expression checking on a string. It compare a string
with a special string mask. The mask contains a regular expression
that defines the valid string patterns.
For a more complete description of the search mask, see String
Comparison Masks.
The use of regular expressions provides a complete string
specification notation that greatly exceeds the capability of
glob_str_compare$.
Arguments:
Returns:
string
the string to perform the regular expression checking on
mask
a string containing the regular expression.
1
the string matches the mask
0
the string does not match the mask
-1
failure; possibly due to insufficient memory
-2
malformed expression
Related Functions:
glob_str_compare$()
Example:
IF ( reg_exp_str_compare$(emp_name, ’Jo[â]n’) = 1 ) THEN
DISPLAY ’Matched string!’ FOR FYI_MESSAGE WAIT
sleep$(amount)
Description:
174
Suspends the application execution for a specified period of time.
Arguments:
amount
Returns:
none
the number of seconds to suspend the execution.
Example:
DISPLAY ’Welcome to the ACCELL Application’ FOR FYI_MESSAGE
sleep$(10)
status$()
Description:
Obtains the status of the outcome of the last database, pipe, or lock
operation in the application.
Arguments:
none
Returns:
Refer to The status$() Function for a more complete description of this
system function.
Example:
INSERT INTO EMPLOYEE
IF ( status$() <> 0 ) THEN
DISPLAY ’Cannot Insert the Record’ FOR FYI_MESSAGE WAIT
strlen$(string)
Description:
Determines the number of characters in a string.
Arguments:
string
Returns:
The number of characters in a string.
the string whose characters you want to count.
Example:
FIELD TITLE
ON FIELD
INPUT
IF ( strlen$(title) > 30 ) THEN
BEGIN
175
DISPLAY ’Title too long-abbreviate to 30’ FOR
FYI_MESSAGE WAIT
RESTART ON FIELD
END
str_to_char_code$(char)
Description:
Translates a single string character into an ASCII value.
Arguments:
char
Returns:
The returned ASCII value is an integer in the range 0 to 127 (valid
ASCII values).
the string character to be translated.
Related Functions:
char_code_to_str$()
str_to_date$(string)
Description:
Translates a string to an ACCELL DATE value. Leading white space
characters such as spaces and tabs are skipped during the translation.
Arguments:
string
Returns:
The date value of the string. This value is in the DATE data type format.
the string containing the date to be translated. The date
in the string must be in the format determined by the
DATETP environment variable. The default DATETP
setting is MM/DD/YY. See Chapter 9.2, Environment
Variables, for more about DATETP.
Example:
SET newdate TO str_to_date$(’1/1/88’)
will set newdate to 01/01/88.
when the DATETP environment variable is set to the default format.
176
str_to_time$(string)
Description:
Translates a string to a time value. Leading white space characters
such as spaces and tabs are skipped during the translation.
Arguments:
string
the string with the time to be translated. The time in the
string must be in the form:
HH:MM
where "HH" is a two-digit (or one-digit for hours less
than 10, e.g., 9:36) hour and "MM" is a two digit number
of minutes. A twenty-four-hour clock is assumed.
Returns:
The time value of the string. This value is in the ACCELL TIME data
type format.
Example:
SET newtime TO str_to_time$(’15:30’)
str_to_val$(string)
Description:
Translates a string to a numeric value. Leading white space characters
such as spaces and tabs and spaces are skipped during the
translation. The function quits when it encounters the first non-digit
character (except for the ".", "-", or "+" characters).
Arguments:
string
Returns:
The numeric value of the argument string. If the argument string
contains a decimal point, then the returned value is a floating point
number (FLOAT). Otherwise, the returned value is an integer
(NUMERIC). If the string argument cannot be converted to a numeric
value or is null, this function returns zero.
the string with the character representation of the
number to be translated.
Related Functions:
177
val_to_str$()
Example:
SET num_val TO str_to_val$(’ 91’)
substr$(string, startsub, endsub)
Description:
Obtains a substring from a string.
Arguments:
string
The string which contains the needed substring
startsub
starting position within string where the needed
substring begins
endsub
ending position within string where the needed
substring ends
Returns:
The substring within string specified by the startsub and endsub
arguments.
Example:
SET area_code TO substr$(emp_phone, 2, 4)
SET local_phone TO substr$(emp_phone, 7, 14)
where emp_phone is a string variable of length 14. It contains the phone number in
the form: (xxx) yyy-yyyy (xxx is the area code and yyy-yyyy is the local phone
number).
system$(command string)
178
Description:
Allows the user to execute a shell command from within an application.
The screen is cleared both before and after execution of command
string.
Arguments:
command string
the string containing the command to be executed.
Returns;
0
for successful execution
-1
if function was called incorrectly
Related Functions:
push_shell$()
Example:
system$(’vi totals’)
user_id$()
Description:
Obtains the user’s ID number from the operating system user IDs.
Arguments:
none
Returns:
The user ID number of the user currently running the application.
Example:
/* To include id of employee who added a record to a file */
BEFORE ADD
SET emp_uid TO user_id$()
user_name$()
Description:
Obtains the user’s name from the operating system login names.
Arguments:
none
Returns:
The user name of the user currently running the application.
Example:
/* To include name of employee who added a record to a file */
BEFORE ADD
SET emp_name TO user_name$()
179
val_to_str$(value)
Description:
Translates a numeric value to a string.
Arguments:
value
Returns:
The string value of a number. No leading or trailing spaces are
included in the returned string.
the number to convert. This number may be either an
integer or a floating point value.
Related Functions:
str_to_val$()
Example:
SET char_val TO val_to_str$(91)
yesno$(yes_no_mesg, default_val)
Description:
This function displays a prompt message on the FYI line and then
retrieves the user response.
Arguments:
yes_no_msg string for question to display on FYI line
default_val
integer value to control the default response to the
question possible values:
1: Default response is "YES"
0: Default response is "NO"
-1: No default (The user must type in a response).
These can be modified, for example, to "Y" and "N", by
modifying the unifymsgs file (messages 3114 and
3115).
Returns:
180
TRUE
if the user’s response to the yes_no_msg prompt is
either "yes" or "YES"
FALSE
if the user’s response to the yes_no_msg prompt is
either "no" or "NO"
Example:
ON NEXT RECORD
IF ( NOT (is_current_record_stored$() ))
THEN BEGIN
IF ( yesno$(’You are about to loose your record changes? Do you
want them saved?’,-1))
THEN BEGIN
DISPLAY ’Updating...’ for FYI_MESSAGE
DISPLAY ’Record Updated’ for FYI_MESSAGE
END
END
THE status$() FUNCTION
The status$() system function is used in ACCELL Language to verify the success or
failure of the last DML (Data Management Language) operation. You would check
status$() to see if DML statements such as SELECT, INSERT, UPDATE, DELETE,
and SLOCK, were successful.
The following list contains the status$() returns. In general, a positive return denotes
at least partial success, a zero return denotes complete success, and negative return
values indicate that an error(s) has occurred and the operation was not completed.
NOTE:
AFA is used as an abbreviation for ACCELL/DBMS’ Advanced Field
Attributes feature.
As an example, the following ACCELL/Language code fragment uses the status$()
function to check whether or not the given part number was found in the inventory
table:
FIELD itm_stock_number
ON FIELD
INPUT
181
SET sdesc, fitems:$itm_price_qtd TO
SELECT #nv_description, #nv_unit_price
FROM nvntry
WHERE #nv_number = fitems:$itm_stock_number
IF status$() < 0 THEN
/* if not on file do over */
BEGIN
beep$(1)
DISPLAY ’Invalid Part Number. Try again.’
RESTART ON FIELD
END
182
Return
value
Description of status
8
Conflicting XLOCK(s)
7
Lock granted, but automatically promoted to a table lock
6
Environment variable not found
5
No record current to supply default value
4
A field is inaccessible
3
Default value conversion error
2
No record current for field
1
Bad AFA environment variable in format
0
Success
–1
Bad AFA list found doing an ADD/UPDATE
Return
value
–2
Domain check failed
–3
Duplicate value found in a No-duplicates B-tree while adding
–4
Attempt to store a duplicate key
–5
Unable to create the sort/merge file
–6
Unable to open the sort/merge file
–7
Key field(s) were required and not specified
–8
Interrupted search
–9
Too many active scans
–10
Not applicable
–11
Attempt to reference a nonexistent record
–12
Record was already deleted
–13
Couldn’t open selection file
–14
No read permissionon record
–15
Key can’t be changed due to references to it
–16
No more space in database to add record
–17
Error creating the selection file
–18
The selection table is full (too many search criteria)
–19
No write permission on record
–20
Internal system error
–21
Find not allowed
–22
Update not allowed
–23
Delete not allowed
–24
Add not allowed
–25
Out of memory
–26
Returned data may be invalid. It was read without first doing a lock
–27 to –34
Undefined status values
–35
No records were selected
–36
Some of the fields in record not updated
–37
None of the records were updated
–38
None of the records were deleted
–39
Partial update, some records were not updated
–40
Partial deletion, some records were not deleted
183
Return
value
184
–41
Record was not updated
–42
Record was not deleted
–43
None of the records were locked
–44
Partial lock, some records were not locked
–45
Unable to acquire lock due to conflict
–46
Not applicable
–47
There was n undefined database field in a INSERT/UPDATE/SELECT
–48
An illegal ACCELL/IDS to DBMS data type conversion
–49
‘scnid’ is not found
–50
Feature not yet implemented
–51
Name of field/table does not exist
–52
Attempt to enter search item in selection table failed
–53
Unknown database type
–54
Bad DBMS length
–55
Combination field not allowed
–56
Tried to free a NIL pointer to a database value
–57
atoxx: Internal conversion error
–58
End of scan (records not found)
–59
Invalid table ID
–60
Invalid record ID
–61
Not applicable
–62
Server is not connected
–63
IPC read error
–64
IPC write error
–65
Could not connect to server
–66
Not applicable
–67
Not applicable
–68
Not applicable
–69
The record was not inserted. Check for valid rference values for explicit
erelationships.
–70
Illegal argument encountered
–71
Could not get the incode of the database
–72
Attempt to start a new transaction without ending previous one
Return
value
–73
Transaction logging error
–74
There is no default value for the field
–75
Error in retrieving default value for a field on insert for field whose value is not
specified.
–76
There is no value associated with this field
–77
Illegal test specified in scan
–78
The referenced field is not a combined field
–79
There was a bad uss function return
–80
Transaction being committed has no locks
–81
There is no room in the active transaction list
–82
Invalid transaction ID
–83
Failed to close a file
–84
Error opening B-tree
–85
Fatal error in B-tree access; rebuild
–86
Hash key error
–87
Request was not a demotion request
–88
Internal locking inconsistency
–89
Lock manager initialization failed
–90
Out of shared memory
–91
Mismatch between the lock manager code and the shared memory data structures
(incompatible versions)
–92
Could not attach shared memory at the appropriate address
String comparison masks
This subsection explains the metacharacters that can be used in a
glob_str_compare$() and reg_exp_str_compare$() mask.
Although the glob_str_compare$() function provides a much more limited range of
pattern matching than reg_exp_str_compare$(), it is included in the ACCELL/IDS
system functions so that you can maintain compatibility with previously written
applications.
NOTE:
The metacharacters may work differently in the two functions.
185
Masks for the glob_str_compare$() function
The glob_str_compare$() function allows you to compare a string with a string mask.
The characters are defined below:
*
An asterisk matches any string, including the null string.
For example, ‘John*’ matches the strings ‘John’, ‘Johnson’, etc.
?
A question mark matches any single character.
For example, ‘dat?’ matches ‘date’ and ‘data’, but not ‘dates’.
[]
The character class brackets match any character that is a member of
the class. The class is those characters in brackets.
For example, ‘code[12]A’ matches ‘code1A’ and ‘code2A’ only.
-
A dash in brackets specifies a range of characters to match.
For example, ‘[M-O]dept’ matches ‘Mdept’, ‘Ndept’, and ‘Odept’ only.
NOTE:
All ordinary characters (all characters except *, ?, [, ], -, and › match
themselves.
Masks for the reg_exp_str_compare$() function
The reg_exp_str_compare$() function allows you to adopt a powerful pattern
matching notation for strings. You can use regular expression notation to describe a
precise pattern mask to use during string comparison.
The characters are defined below:
[]
The character class brackets match any character that is a member of
the class. The class is made up of the characters in the brackets.
^
186
A caret in brackets negates the character class. It must
be the first character after the "[".
For example, ‘[âbc]’ recognizes any character except
‘a’, ‘b’, and ‘c’.
-
A dash in brackets specifies a range of characters. The
dash can only be included as a member of the class
when it is the first character or last character of the
class.
For example, ‘[-a]’ matches ’-’ or ’a’, or, ‘[a-c]t’ matches
’at’, bt’, and ’ct’
.
A period matches any character. (This is equivalent to the ? character
in glob_str_compare$().)
*
An asterisk matches the previous regular expression zero or more
times.
For example, ‘a*’ matches the null string or the strings ‘a’, ‘aa’, ‘aaa’,
etc.
+
A plus symbol matches the previous regular expression one or more
times. This feature is supplied to ACCELL/IDS through the operating
system; you will not be able to use this notation if your operating
system does not support this type of regular expression.
For example, ‘[a-z]+’ matches any lower case alphabetic string of any
length equal to or greater than 1.
{}
Braces indicate repetition of the previous regular expression. This
feature is supplied to ACCELL/IDS through the operating system; you
will not be able to use this notation if your operating system does not
support this type of regular expression.
{}
Braces indicate repetition of the previous regular expression.
m
An integer in braces matches the previous regular
expression m times. The integer must be less than 256.
For example, ‘a{3}’ matches "a" three times, which
matches only the string ‘aaa’.
187
m,
An integer and a comma in braces match the previous
regular expression m or more times.
For example, ‘b{1,}’ matches "b" one or more times,
which matches the strings ‘b’, ‘bb’, ‘bbb’, etc.
m,n
An integer, comma, and another integer in braces
match the previous regular expression at least m but not
more than n times. Both of the integers m and n must
be less than 256.
For example, ‘c{1,2}’ matches "c" at least one but not
more than two times, which matches the strings ‘c’ or
‘cc’.
()
The parentheses are used for grouping. Grouping allows repetition
operators to work on each character or an entire subexpression.
For example, the regular expression ‘(ab){1,2}’ matches the strings ‘ab’
and ‘abab’.
NOTE:
All ordinary characters (all characters except [], ^, -, ., *, +, {}, (), and ›
match themselves.
Using the reg_exp_str_compare$() function can greatly simplify the pattern mask you
need to use.
For example, if you wanted to set the legal values for a telephone number and the
telephone number field has the general format "222-3333", you would need the
following pattern masks for the glob_str_compare$() and reg_exp_str_compare$()
functions:
glob_str_compare$(phone,
’[0-9][0-9][0-9]-[0-9][0-9][0-9][0-9]’)
reg_exp_str_compare$(phone, ’[0-9]{3}-[0-9]{4}’)
188
ACCELL/IDS system variables
ACCELL/IDS provides a set of system variables that you can use in your ACCELL/
Language scripts. ACCELL/IDS system variables let you test and change the internal
state of the ACCELL/Manager. Applications can change system variable values by
using SET statements in ACCELL/Language scripts.
Currently, ACCELL/IDS system variables are accepted in both upper and lower case
by the ACCELL/IDS linker. A future ACCELL/IDS update will allow these variables to
be entered only in lower case. To avoid having to revise your Language scripts in the
future, use lower case for all ACCELL/IDS system variables.
add_allowed$
Description:
Indicates if the access level allows Add operations. The access level is
initialized by the user access code when the user starts up the
ACCELL Manager. See Chapter 9.3, under Setting Up End User
Access to an Application for more information on the user access
code.
This variable may be reset in ACCELL/Language to override the Add
permission of the user access code. The variable can also override the
application forms’ Add operation permission set up in the ACCELL/
Generator (in the Form Definition form ) whose value is stored in the
ADD_ALLOWED form attribute.
Values:
TRUE
if user is allowed to add new records to the database
FALSE
if user is not allowed to add new records to the
database
Example:
IF (group_id$() > 10) THEN
SET add_allowed$ to TRUE
189
delete_allowed$
Description:
Indicates if the access level allows Delete operations. The access level
is initialized by the user access code when the user starts up the
code.
This variable may be reset in ACCELL/Language to override the Delete
application forms’ Delete operation permission set up in the ACCELL/
Generator (in the Form Definition form) whose value is stored in the
DELETE_ALLOWED form attribute.
Values:
TRUE
if user is allowed to delete existing records from the
database
FALSE
if user is not allowed to delete existing records from the
database
Example:
SET delete_allowed$ to TRUE
find_allowed$
Description:
Indicates if the access level allows Find operations. The access level is
initialized by the user access code when the user starts up the
code.
This variable may be reset in ACCELL/Language to override the Find
application forms’ Find operation permission set up in the ACCELL/
Generator (in the Form Definition form) whose value is stored in the
FIND_ALLOWED form attribute.
190
Values:
TRUE
if user is allowed to search for records in the database
FALSE
if user is not allowed to search for records in the
database
Example:
SET find_allowed$ to TRUE
info_level$
Description:
Indicates the user’s information level setting. The information level is
initialized to the Novice level. See Chapter 4.3, under Information
Levels for more information on user information levels.
This variable may be reset in ACCELL/Language to change the user
information level.
Values:
0
to set the user information level to "Novice" (default
value)
1
to set the user information level to "Intermediate"
2
to set the user information level to "Expert"
If set to other values (for example, 3 or -2), information
and error messages are deactivated.
Example:
BEFORE FORM
SET info_level$ to 2
update_allowed$
Description:
Indicates if the access level allows Update operations. The access
level is initialized by the user access code when the user starts up the
191
ACCELL Manager. See Setting Up End User Access to an Application
in Chapter 9.2 for more information on the user access code.
This variable may be reset in ACCELL/Language to override the
Update permission of the user access code. The variable can also
override the application forms’ Update operation permission set up in
the ACCELL/Generator (in the Form Definition form) whose value is
stored in the ADD_ALLOWED form attribute.
Values:
TRUE
if user is allowed to update existing records in the
database
FALSE
if user is not allowed to update existing records in the
database
Example:
SET update_allowed$ to TRUE
192
6.6 Data types
ACCELL/IDS supports seven data types:
NUMERIC
Numeric data, no decimal point
FLOAT
Floating point data
AMOUNT
Floating point value containing an integral number of basic currency
units, such as pennies
BOOL
Boolean data
STRING
String data
DATE
Number of days from a base date. Numeric value.
TIME
Number of hours and minutes since midnight. Numeric value. The
format is HH:MM
In addition, there is an internal ACCELL/IDS value, UNDEFINED, used for fields and
variables without values.
ACCELL/IDS automatically converts between these types and the standard DBMS
data types whenever data moves to or from the database. ACCELL/IDS also
automatically converts data types in some statements when the types are
assignment-compatible. See the assignment-compatibility chart, Chapter 6.2,
Variables under Variable Assignment Compatibility. All other conversions must be
performed by using the conversion functions described in ACCELL Type Conversion
Functions on.
193
The following table lists the internal storage types, the corresponding DBMS data
types, and the maximum precision for each ACCELL/IDS data type:
ACCELL
storage type
Maximum
precision
NUMERIC (1–4)
NUMERIC (5–9)
long
9 digits
FLOAT
FLOAT
double
17 digits, up to 9 of
which are decimal
places
AMOUNT
AMOUNT (1–7)
double
11 digits plus 2
decimal places
BOOL
n/a
long
STRING
STRING
point to char
256 bytes
DATE
DATE
LDATE
long
1900 thru 2075
TIME
TIME
long
ACCELL type
DBMS type
NUMERIC
NOTE: The maximum precisions in this table are machine dependent. The table values
assume 32-bit twos complement integers and 64-bit floating point values.
ACCELL type conversion functions
ACCELL/IDS provides the functions below to convert from one data type to another.
These functions force ACCELL/IDS to treat particular values as if they had types other
than their assigned type.
date_to_mdy$(date,num_month, num_day,num_year)
Takes a value of type DATE (date) and returns three NUMERIC values corresponding
to the month, day, and year. The year is returned as a four-digit number.
mdy_to_date$(num_month,num_day,num_year)
Takes three NUMERIC arguments corresponding to month, day, and year, and returns
a DATE value for the date. The year must be given as a four digit number. For
example, you would use 1986 and not 86.
194
to_amount$(argument)
Must have a NUMERIC or FLOAT argument. Returns an AMOUNT value.
to_bool$(argument)
Must have NUMERIC as an argument. If the argument is 0, FALSE will be returned if
the argument is 1, TRUE will be returned; any other value will cause an error.
to_date$(argument)
Must have a NUMERIC as an argument. ACCELL/IDS date values extend the range
of DBMS date values.
to_float$(argument)
Must have a NUMERIC or AMOUNT argument. Returns a FLOAT value.
to_num$(argument)
Can have any argument type but STRING. If the argument is a FLOAT or AMOUNT, it
must be in the range between -2#! and +2#!-1 and it will be truncated. If the argument
is a BOOL, then FALSE will return 0 and TRUE will return 1. If the argument is DATE
or TIME, any value is legal and the inverse of the to_date$ or to_time$ functions will
be performed.
to_time$(argument)
Must have a NUMERIC argument. All integers are permitted and are interpreted as
the number of minutes since midnight.
195
6.7 Operators
All standard arithmetic, relational, and logical operators are available in ACCELL/IDS.
ACCELL/IDS performs some automatic type coercion as needed before performing
the operations. The resulting type is determined by the operand types and the
operation. See the tables for each operator for information about specific types.
The operator symbols and their definitions are summarized below.
Assignment Operator
In ACCELL/IDS the SET expression is the assignment operator. For example:
SET $count to 1
Arithmetic and Concatenation Operators
+
addition, concatenation, unary plus
-
subtraction, unary minus
/
division
*
multiplication
%
modulus
Bitwise Operators
~
bitwise ones complement
&
bitwise AND
|
bitwise inclusive OR
^
bitwise exclusive OR
Relational Operators
196
<
less than
>
greater than
<=
less than or equal to
>=
greater than or equal to
=
equal to
<>
not equal
Logical Operators
NOT
logical negation
AND
logical and
OR
logical or
Precedence and Associativity
The next table shows the precedence and associativity rules for all ACCELL/IDS
operators. Those operators on the same line have the same precedence; rows appear
in order of decreasing precedence.
Operator
Associativity
()
left to right
+ – NOT (unary)
right to left
*/%
left to right
+ – (binary)
left to right
,< <= > >+ = <>
left to right
&
left to right
^
left to right
AND
left to right
OR
right to left
SET
left to right
197
Operator
Associativity
Each operator works on only a subset of the possible type combinations. The tables in
the following sections show the type that results from performing each of the
operations. A blank entry in the table indicates an illegal combination of operand
types. Using an illegal combination will produce a runtime error. The left-hand column
indicates the type of the first operand. The column headings indicate the type of the
second operand. The table for the assignment operator (SET) appears in the Variable
Assignment Compatibility section on.
Arithmetic and concatenation operators
Addition/Concatenation
expr1 + expr2
Numeric
Float
Amount
NUMERIC
NUMERIC
FLOAT
AMOUNT
FLOAT
FLOAT
FLOAT
AMOUNT
AMOUNT
AMOUNT
AMOUNT
AMOUNT
Bool
Str
Date
Time
DATE
TIME
BOOL
STRING
STR
DATE
DATE
TIME
TIME
TIME
Note that any addition involving FLOAT and NUMERIC values produces a FLOAT
result. Any addition involving an AMOUNT value produces an AMOUNT result. A
NUMERIC result is produced only by the addition of two NUMERIC values.
The addition operator acts as a concatenation operator between STRING items.
Concatenation can only be performed on STRING values. NUMERIC values can be
added to TIME (value added is taken as number of minutes) and DATE (value added
is taken as number of days) values.
198
Subtraction
expr1 - expr2
Numeric
Float
Amount
NUMERIC
NUMERIC
FLOAT
AMOUNT
FLOAT
FLOAT
FLOAT
AMOUNT
AMOUNT
AMOUNT
AMOUNT
AMOUNT
Bool
Str
Date
Time
BOOL
STRING
DATE
DATE
TIME
TIME
NUMERIC
NUMERIC
Note that any subtraction involving FLOAT and NUMERIC values produces a FLOAT
result. Any subtraction involving an AMOUNT value produces an AMOUNT result. A
NUMERIC result is produced only by the subtraction of two NUMERIC values.
Subtraction performed on DATE items produces a NUMERIC result that is the number
of days between the two dates. Similarly, subtracting TIME values produces a
NUMERIC result that is the number of minutes between the times. NUMERIC values
can be subtracted from DATE (value subtracted is number of days) and TIME (value
subtracted is number of minutes) values.
Multiplication
expr1 * expr2
Numeric
Float
Amount
NUMERIC
NUMERIC
FLOAT
AMOUNT
FLOAT
FLOAT
FLOAT
AMOUNT
AMOUNT
AMOUNT
AMOUNT
AMOUNT
Bool
Str
Date
Time
BOOL
STRING
DATE
TIME
199
Multiplication can only be performed on NUMERIC, FLOAT, and AMOUNT values.
Any multiplication involving AMOUNT values produces an AMOUNT result.
Multiplications involving NUMERIC and FLOAT values produce FLOAT results.
Division
expr1 / expr2
Numeric
Float
Amount
NUMERIC
NUMERIC
FLOAT
AMOUNT
FLOAT
FLOAT
FLOAT
AMOUNT
AMOUNT
AMOUNT
AMOUNT
AMOUNT
Bool
Str
Date
Time
BOOL
STRING
DATE
TIME
Division can only be performed on NUMERIC, FLOAT, and AMOUNT values. Division
involving both NUMERIC and FLOAT values produces a FLOAT result. Any division
involving an AMOUNT value produces an AMOUNT result. Division by zero produces
a runtime error.
Modulus
expr1 % expr2
Numeric
NUMERIC
Float
Amount
Bool
Str
Date
Time
NUMERIC
FLOAT
AMOUNT
S
BOOL
STRING
DATE
TIME
200
The first expression (expr1) may be negative.
Modulus operations can only be performed on NUMERIC values.
Unary minus
- expr
Unary minus is legal on NUMERIC, FLOAT, and AMOUNT operands and yields the
type of its operand.
Unary plus
+ expr
Unary plus may be used to indicate a positive value with NUMERIC, FLOAT, and
AMOUNT operands. ACCELL/IDS assumes that all unsigned values are positive.
Relational operators
expr1 ( = | < > | > | >= | < | <= ) expr2
The tables for the various relational operators are similar enough that they can be
presented in one composite table.
STRING values are compared character by character until the ends of the strings are
reached or two characters differ. When two characters differ, the string containing the
character with the smaller ASCII code value is ‘‘less than’’ the other string. The effect
is an alphabetic ordering except that capital letters are ‘‘less than’’ lower case letters.
A string that is identical to only the first part of a second string will also be ‘‘less than’’
the second string.
Numeric
Float
Amount
NUMERIC
BOOL
BOOL
BOOL
FLOAT
BOOL
BOOL
BOOL
AMOUNT
BOOL
BOOL
BOOL
Bool
Str
Date
Time
NOTE:* Only ‘ = ’ and ‘ < > ’ are legal with boolean operands.
201
Numeric
Float
BOOL
Amount
Bool
Str
Date
Time
BOOL*
STRING
BOOL
DATE
BOOL
TIME
BOOL
NOTE:* Only ‘ = ’ and ‘ < > ’ are legal with boolean operands.
Logical operators
expr1 ( AND | OR ) expr2
NOT expr
The logical operators are only legal on BOOL operands and always produce a BOOL
result. AND represents logical AND, OR represents logical OR, and NOT represents
logical negation. Expressions are evaluated from left to right until a result can be
determined for the entire expression.
Note that ACCELL/IDS quits evaluating an expression containing logical operators as
soon as it can determine the value of the entire expression. Because of this, some
operations in a statement may not be performed.
Bitwise operators
expr1 ( & | | | ^ ) expr2
~ expr1
The bitwise operators are only legal on NUMERIC operands and always produce a
NUMERIC result. ‘ & ’ represents bitwise AND, ‘ | ’ represents bitwise inclusive or, ‘ ^ ’
represents bitwise exclusive or, and ‘ ~ ’ represents ones compliment.
The following tables show the effects of the operators on a single bit in A and a single
bit in B for all possible combinations of bits. Remember that these are bitwise
operators. This means that in the first table the operation is performed on the first
202
operand’s first bit and the second operand’s first bit, and then on successive pairs of
bits.
A
B
A&B
A|B
A^B
0
0
0
0
0
0
1
0
1
1
1
0
0
1
1
1
1
1
1
0
A
–
0
1
1
0
A
203
204
Chapter 7: ACCELL/Language sections
7.1 Introduction
This chapter contains descriptions of all the ACCELL/Language sections. Look
through this chapter to see what Language sections are available and to get a sense
of the relationships among them. When writing your applications, come back to this
part of the manual and read about each of the Language sections you are using. For
more information, see Appendix A, ACCELL/Language Grammar under How to Use
the Grammar and Language Sections.
ACCELL/Language scripts for an application consist of various sections, such as an
Application control section, Form control sections, and Field control sections. All
Language sections are optional. If a Language section is left out, ACCELL/IDS uses
default values specified in the ACCELL/Generator as necessary.
The Application control section enables you to execute statements before or after the
application runs. Language in the Application control section can be used, for
example, to establish a user's identity or to display final statistics. This section can
only appear in the Master Application form's Language script.
Form control sections are broken down into smaller sections containing statements
executed before the form is started, when a NEXT FORM command is given, after a
FIND has been performed, and so on. The Form Language sections also contain
sections for controlling specific form fields. Each Field control section is broken down
into sections executed as the user moves to the field, when the field value changes,
and so on.
205
MASTER FORM
BEFORE APPLICATION
AFTER APPLICATION
CHOOSE FIRST FORM
STANDARD FORM
.
.
.
APPLICATION
STANDARD FORM
.
.
.
STANDARD FORM
BEFORE FORM
AFTER FORM RETURN
AFTER ZOOM
ON PREVIOUS FORM
ON NEXT FORM
CHOOSE NEXT FORM
ON CLEAR TO FIND
BEFORE FIND
ON FIND
AFTER FIND
BEFORE UPDATE
AFTER UPDATE
DEFORE DELETE
AFTER DELETE
ON CLEAR TO ADD
BEFORE ADD
AFTER ADD
ON NEXT RECORD
ON PREVIOUS RECORD
ON EXIT
FIELD
.
.
.
FIELD
.
.
.
INIT FIELD
BEFORE FIELD
ON FIELD
AFTER FIELD
WHEN FIELD CHANGES
FIELD
FORMS
LANGUAGE SECTIONS
Figure 42. ACCELL/IDS forms and language sections
Most ACCELL/Language statement may appear in any Language section. However,
the INPUT statement is usually restricted to the ON FIELD Language section. For
specific exceptions, see Appendix C, ACCELL/IDS Error Messages, ACPL error
numbers 2916, 2719, 2924-2929, and 2932.
In summary, the script for an application may consist of an Application control section
and Form control sections. Each Form section breaks down into further subsections
such as BEFORE FORM, ON NEXT FORM, BEFORE FIND, BEFORE ADD and into
a series of Field control sections. Each Field section breaks down into sections such
as BEFORE FIELD, ON FIELD, and WHEN FIELD CHANGES.
206
7.2 Master Application Form control section
Every application includes a unique Master Application form that is either generated
automatically or provided by the developer. Advanced developers can use the optional
Language section associated with this form to provide additional application control.
This section describes the Master Application form control section and its
subsections. Beginning developers may want to skip this part for now, and continue
with the section Standard Form Control Section.
The Master Application form script can be used to establish global variables that are
available to any form in the application. Variables appear in the script as [appl_name:]
variable_name. This is possible because the Master Application form remains on the
active form list throughout application execution. In addition, the Master Application
form script can be used to perform operations before or after the application executes.
The Master Application script contains a required header and optional BEFORE
APPLICATION, AFTER APPLICATION, CHOOSE FIRST FORM, and FIELD
sections. Sections such as BEFORE ADD are not allowed because the Master
Application form does not have a target table. A Master Application form may,
however, get information from database tables.
ACCELL/Language sections
207
The figure that follows illustrates the execution of the Master Application Language
sections.
Start of application
Executes
BEFORE APPLICATION
CHOOSE FIRST FORM
replace
not stored
find
COMPANY:
ADDRESS:
SALES REP#:
NAME:
PHONE:
CITY:
MAIN PHONE:
CONTACT
STATE:
ZIP:
MAP:
Enter the first line of street address.
F1-Prv Form
F2-Nxt Form F3-Find
Executes
AFTER APPLICATION
End of application
Figure 43. Master Application Language section execution
NOTE:
208
In the descriptions, an asterisk (*) indicates an item that may appear
once or more, or not at all. Parentheses are not part of the header but
instead indicate repeated elements. Brackets indicate optional
elements.
Application header
The application header section is required. Each part of the header is described
below.
The APPLICATION statement names the application. It has the following syntax:
APPLICATION application_name;
The REQUIRED FORMS clause lists all forms that must be included in the
application. It has the following syntax:
REQUIRED FORMS form_name IN 'archive_name.fa'
[, form_name IN 'archive_name.fa' ]* [;]
where form_name is the name of a form that is in the application archive
archive_name. The suffix .fa and the single quotes must be included in the IN clause.
The REQUIRED FORMS clause is required if the application contains any Standard
form Language scripts, and must be included even if a form does not have a .fs file.
Before application section
The BEFORE APPLICATION section can be used to establish a user's identity, deny
entry to the application, initialize application totals, establish security constraints, or
anything else done before an application begins. If present, BEFORE APPLICATION
executes as soon as the application is initialized, and before any forms are executed.
Local variables for all subsequent forms may also be defined in the BEFORE
APPLICATION section or in a BEFORE FORM section.
After application section
The AFTER APPLICATION Language section can be used to perform actions at the
end of an application, such as updating counts, displaying messages, displaying
summary statistics, or any kind of final operation.
If present, the AFTER APPLICATION section executes after the user selects the EXIT
option from an ACCELL/IDS menu, or after a NEXT ACTION IS EXIT is executed.
209
NOTE:
This section is not executed when the user issues an ABORT
APPLICATION command. To make sure this section is always
executed, remove the ABORT APPLICATION command from the
unicap file.
CHOOSE FIRST FORM section
The CHOOSE FIRST FORM section is identical to the CHOOSE NEXT FORM
Language section, except that it can appear only in a Master Application form. See
Choose Next Form, for a description of CHOOSE NEXT FORM.
Other language sections
The Master Application form script may also contain the following Language sections
that do not require a target table:
FIELD
ON NEXT FORM
ON PREVIOUS FORM
AFTER FORM RETURN
ON EXIT
AFTER ZOOM
BEFORE FORM
210
7.3 Standard form control section
The bulk of any application consists of Standard forms that you create in the ACCELL/
Environment. These forms may have ACCELL/Language scripts associated with
them. This section describes Standard form Language scripts and their sections.
A Standard form Language script contains a form declaration, a series of sections
applying to the form such as BEFORE FORM, ON NEXT FORM, and Language
sections for individual fields.
The Standard form Language script can be used to specify conditions unique to a
particular form, such as the table accessed by the form and the variables local to the
form. It is also used to determine when to execute the next form and to establish
conditions such as transaction level under which the next form will be executed.
The figure that follows shows how form control sections are executed in response to
NEXT FORM and PREV FORM user commands.
211
replac
not stored
find
COMPANY:
ADDRESS:
SALES REP#:
NAME:
PHONE:
NEXT
FORM
CITY:
MAIN PHONE:
CONTACT
STATE:
PREV
FORM
ZIP:
MAP:
Enter the first line of street address.
F1-Prv Form F2-Nxt Form F3-Find
Suspends current
ON FIELD
Executes
ON PREVIOUS
FORM
AFTER ZOOM
(if returning from zoom form)
AFTER FORM RETURN
Resumes suspended
ON FIELD
Suspends current
ON FIELD
Executes
ON NEXT FORM
INIT FIELDS
BEFORE FIELD
ON FIELD (for first field)
replace
not stored
ORDER#:
TERMS
find
NO RECORDS FOUND
ENTERED
FILL CODE:
SHIP VIA:
SHIP TO ABOVE ADDRESS:
MAP:
Enter the date or RETURN for
F1-Prv Form
F2-Nxt Form F3-Find
Figure 44. Form control language execution
212
Form declaration
The form declaration identifies the form, specifies the table, if any, with which the form
works, and declares any variables local to the form. A form declaration has the
following format:
FORM form_name [ TARGET_TABLE table_name ]
[ LOCAL variable_list ] [;]
The form_name after the keyword FORM is the form's identifier. The form name must
match that of an existing form created with the ACCELL/Generator.
The TARGET_TABLE clause associates the script with a database table.
TARGET_TABLE causes automatic declaration of any local variables having the same
name as the target table fields. The TARGET_TABLE clause is required if the form
references a table and must refer to the same table as the form. The Language
Compiler uses the TARGET_TABLE clause to establish some variable references and
to check for syntax and semantic errors.
The LOCAL clause lists the names of variables that will be considered local to this
form. The effect of the clause is to treat all variables in the list as if they were prefixed
with the form's identifier, form_name.
Applications run more efficiently if local variables are explicitly declared in the LOCAL
clause or implicitly declared local by using the form name as a prefix. Either method
saves time by eliminating the active forms list search performed when ACCELL/IDS
encounters a variable without a form name prefix. Because the runtime search is
eliminated, all references to variables declared LOCAL refer to the local variable, even
if the identifier appears on another form. Note that target field variables are implicitly
local. See section 6.2, Variables, under Scope of Variables, for more information.
Variables declared LOCAL on the current form can be referenced by successive
forms.
The following sections list and describe all of the form control sections.
213
BEFORE FORM section
The BEFORE FORM Language section can be used to perform any necessary
initializations–any necessary form set up–before a form begins. The BEFORE FORM
Language section executes after the form is initialized, but before any fields are
executed.
ON NEXT FORM section
The ON NEXT FORM section, if present, contains statements performed when the
application user issues a NEXT FORM command. Execution occurs before the
CHOOSE NEXT FORM Language section is done and the form is left. This section
can be used to keep an unauthorized user from going to the next form, or to perform
checks on the state of the form, or to save any uncommitted changes made by the
user.
ON PREVIOUS FORM section
The ON PREVIOUS FORM Language section, if present, contains statements
executed when the user enters a PREV FORM command. Execution occurs before
the form is deactivated.
This section can be used to perform any necessary operations before returning to the
previous form. For example, a REJECT OPERATION statement in this section could
be used to keep the user from returning to the previous form until they had met some
specified condition, or entered all required data.
AFTER FORM RETURN section
The AFTER FORM RETURN Language section is executed when a PREV FORM
command is executed on a form. This section is contained in the form that you are
returning to with PREV FORM. You may be returning from either a ZOOM or a NEXT
FORM command. Both master and standard forms can contain this Language
section. For example:
/* In this Order/Items application, returning from a next form
signifies that you are done with an order. */
214
FORM forders
TARGET_TABLE order
AFTER FORM RETURN
IF ( yesno$( 'Enter a new order?' , -1) ) THEN
BEGIN
NEXT ACTION IS CLEAR TO ADD
END
AFTER ZOOM section
The AFTER ZOOM section appears on the Zoomed-To form, and executes when a
user issues a PREV FORM command on a Zoom form. The section can be used to
set global variables or values as a way of bringing additional information back from
the zoomed-to form.
CHOOSE NEXT FORM section
The CHOOSE NEXT FORM Language section executes in response to a NEXT
FORM user command. CHOOSE NEXT FORM is executed after the ON NEXT
FORM section is finished.
The only statement allowed in the CHOOSE NEXT FORM section are one or more
NEXT FORM statements:
WHEN logical_expression] transaction_level USING (form | EXIT)
For example:
/* */
CHOOSE NEXT FORM
WHEN group_name$() = 'clerks' START TX RECORD_CONSISTENCY
USING data_entry;
WHEN group_name$() = 'supervsrs' START RECORD_CONSISTENCY
USING administr;
NOTE:
Clerks will have a data_entry form as the next form; supervisors will
have an administrative form as the next form.
215
The individual parts of this statement are described below.
WHEN expressions
[WHEN logical_expression]
When the CHOOSE NEXT FORM section is executed, ACCELL/IDS evaluates the
WHEN expression for each NEXT FORM statement. The WHEN expression must
have a Boolean value (TRUE or FALSE) or it will cause an error. NEXT FORM
statements without a WHEN expression are treated as if they had WHEN expressions
with a TRUE value.
•
If only one NEXT FORM statement has a true WHEN expression then the
form specified in that expression is the next form.
•
If more than one WHEN expression is true, ACCELL/IDS displays a menu
listing the possible forms.
•
If none of the WHEN expressions are true, ACCELL/IDS tells the user that
there is no next form.
Transaction levels
transaction_level
ACCELL/IDS applications may run on multi-user systems where more than one
person may be using the database at any one time. Thus a mechanism is necessary
to keep one user's database operations from interfering with another user's
operations. ACCELL/IDS controls access to parts of the database by organizing
operations into transactions that control parts of the database until the operation is
finished. A transaction may consist of single or multiple forms.
When a transaction is finished, all locks on records or sets of records are released, an
entry is written in the transaction log, and a new transaction may be started.
One user's transactions cannot make use of information entered by other users that
has not yet been committed (added/updated) to the database. Uncommitted changes
include all information added or changed within the current unfinished transaction.
Other users cannot read this information because ACCELL/IDS retains an exclusive
lock (XLOCK) on added, modified, or deleted records until the transaction is finished.
216
ACCELL/IDS applications can run at one of two transaction levels: current record
consistency or set consistency. The transaction level specified in the NEXT FORM
statement sets the transaction level at which the next form runs.
Current record consistency guarantees that the transaction's current record cannot be
modified by another transaction. This is done by putting a shared lock (SLOCK) on the
current record. Other transactions, however, can modify records in the selected set
other than the current record.
Set consistency allows other transactions to read this transaction's selected set, but
no other transaction may modify records in the set. Set consistency puts a shared lock
(SLOCK) on each record in the selected set.
Which transaction level to use depends on how the form is used, whether it is a
single-occurrence or a multi-occurrence form, and how much concurrence you want
to allow. In general, single-occurrence forms should have a transaction level of record
consistency; multi-occurrence forms should have a transaction level of set
consistency.
Along with specifying the transaction level, the transaction level clause also
determines whether the execution of the next form starts a new transaction, continues
the current transaction, or starts the transaction over again.
Below is a list of valid NEXT FORM transaction level clauses:
CONTINUE TX RECORD_CONSISTENCY continues the current transaction with
current record consistency. The new form is added to the active form list.
CONTINUE TX SET_CONSISTENCY continues the current transaction with selected
set consistency. The new form is added to the active form list.
START TX RECORD_CONSISTENCY begins a new transaction with current record
consistency. All locks held by the previous transaction are released and the active
form list is cleared (all active forms are deactivated). The new form becomes the first
form on the new active form list. Other transactions may not change this transaction's
current record. This is done by putting a shared lock on the current record. Records in
the selected set other than the current record may be changed by other transactions.
START TX SET_CONSISTENCY begins a new transaction with selected set
consistency. All locks held by the previous transaction are released and the active
217
form list is cleared (all active forms are deactivated). The new form becomes the first
form on the new active form list. Other transactions may read this transaction's
selected set but may not modify the records. This is done by putting a shared lock on
each record in the selected set.
RESTART TX begins by performing the same actions as the COMMIT TX statement:
all locks are changed to shared locks (SLOCKs) and the transaction is logged.
Downgrading the locks allows other transactions to read the records held by the
transaction.
In addition, the RESTART TX clause removes all forms occurring after the next form
from the active forms list. For example, suppose there are five active forms. If a NEXT
FORM with RESTART TX is done from the fifth form to the second form, then the
third, fourth, and fifth forms would be removed from the active forms list. The current
record and the selected set remain the same as they were before the RESTART TX.
RESTART TX can only be used in a NEXT FORM to an active form. If the specified
next form is not active, an error is displayed.
RESTART TX is convenient for entering significant amounts of information across
several forms while maintaining control over the selected set.
The AUTO_COMMIT attribute and the COMMIT TX statement both affect transaction
handling. See Chapter 6.3, under Form Attributes, and Chapter 8.2, ACCELL/IDS
Statement Descriptions, for more information.
ON EXIT section
The ON EXIT Language section can be used in both the Master Application form and
a Standard form. The ON EXIT section is executed on a Master Application form
when:
218
•
the EXIT clause is used with the CHOOSE FIRST FORM Language section in
the Master Application form
•
the PREV FORM command is issued from the Master Application form
•
The ON EXIT section is executed after the ON PREVIOUS FORM section (if
present)
•
the ABORT APPLICATION command is issued from the Master Application
form
The ON EXIT section is executed on a Standard form when:
•
the NEXT ACTION IS EXIT statement is used in the Standard form
•
the ABORT APPLICATION command is issued from the Standard form
•
the USING EXIT clause is used with the CHOOSE NEXT FORM statement in
the Standard form Language script.
When one of the above conditions exists, only the ON EXIT section of the current form
is executed; any ON EXIT sections in other forms will not be executed. This code
section can be used to perform activities specific to the current form before leaving the
application. It can also disable an exit from the current form. For example:
/* The use invoked the ABORT APPLICATION command from the
Order form but is not permitted to leave the application
from this form. */
FORM forders
ON EXIT
DISPLAY 'You cannot exit this application from this form!'
REJECT OPERATION
Find Language sections
The Find Language sections are executed whenever a FIND command is given. Note
that a FIND can be requested by the user, or done automatically if the form's
AUTO_FIND attribute is set to TRUE. Find mode is entered whenever a CLEAR TO
FIND is done and is the only user mode where FIND is permitted. When performing a
Find, ACCELL/IDS searches the target database table for all records meeting the
specified search criteria.
Any field with an undefined value is ignored as a search criteria during a Find.
Records meeting the search criteria become part of a new selected set. The selected
set may be empty if no acceptable records are found. The previous selected set is
discarded when Find mode is entered.
219
BEFORE FIND is the first Find Language section executed; it may specify additional
search criteria, initialize totals, counts, and similar actions. The ON FIND section is
executed once for each acceptable record found. The AFTER FIND section is
executed after the records are found, but before control is returned to the user. The
user is notified of how many records were found before ACCELL/IDS leaves Find
mode.
If an error occurs during a Find, the user remains in Find mode. The new selected set
may contain only partial results of the Find, especially if another user has an exclusive
lock (XLOCK) on records that would otherwise have been included.
220
Figure 45 illustrates Find section execution in response to the FIND user command.
replace
not stored
find
COMPANY:
ADDRESS:
SALES REP#:
NAME:
PHONE:
CITY:
MAIN PHONE:
CONTACT
STATE:
ZIP:
MAP:
CLEAR
TO FIND
FIND
Enter company name.
Executes
BEFORE FIND
Executes
AFTER FIND
Creates selected set
from the records found
and displays the first
record. Executes ON
FIND SECTION FOR EACH
RECORD FOUND.
Executes
ON CLEAR
TO FIND
Displays CLEAR TO FIND
values in the form’s
field. Enters
ADD/UPDATE/DELETE mode.
Figure 45. Find Section Execution
BEFORE FIND section
The BEFORE FIND Language section is executed just before ACCELL/IDS begins
the database search. The BEFORE FIND section can be used to initialize totals, set
up variables for aggregate functions, and specify additional search criteria.
221
In the BEFORE FIND section, additional search criteria are specified by setting the
SEARCH_RANGES attribute of appropriate variables. Note that setting variable
values at this point will not establish search criteria, because search ranges, specified
via SEARCH_RANGES, and not variable values, are used in selecting records.
ON CLEAR TO FIND section
The ON CLEAR TO FIND Language section is executed following a CLEAR TO FIND
command. The CLEAR TO FIND command can be either explicit, requiring the user to
press CLEAR TO FIND, or implicit, in which case an implied CLEAR TO FIND is
executed when you are in the BEFORE FORM Language section and the default
mode is Find.
The CLEAR TO FIND command occurs only on forms that have target tables. The
command notifies ACCELL/IDS that search criteria for a database search on the
target table is about to occur. Since target tables cannot be associated with the
Master Application form, the ON CLEAR TO FIND section can only be used for
Standard forms.
NOTE:
Do not use the NEXT ACTION IS CLEAR TO FIND statement in the
ON CLEAR TO FIND Language section. NEXT ACTION IS CLEAR TO
FIND will create an infinite loop in the code.
For example:
/* Finds only records with order numbers > 500 */
FORM forders
TARGET_TABLE orders
ON CLEAR TO FIND
SET forders:$ord_num:CLEAR_FIND_EXP TO 500 =>
ON FIND section
The ON FIND section contains statements executed for each record that meets the
search criteria. This section is executed before control is returned to the user, after
executing a FIND. The ON FIND section can be thought of as a loop that executes
once for each record found. Within the ON FIND section, each newly found record is
222
treated as if it were the current record. This means that each record can be processed
as it is found, using the target variables to obtain the record field values.
The ON FIND section can be used to increment counts and to calculate totals.
In addition, the REJECT RECORD statement, which can only be used in this section,
can be used to prevent a record from being added to the selected set. A rejected
record is also excluded from the total of current_record_count$(). For example, in a
Find on a table of employee information, REJECT RECORD could be used to prevent
inspection of a particular employee's record.
AFTER FIND section
The AFTER FIND Language section is executed immediately after ACCELL/IDS
completes the database search, even if the find is unsuccessful.
This section can be used to display or test any totals or counts calculated during the
find. Such totals and counts can be displayed by assigning values to screen variables
in this section.
For example, the system function current_record_count$() could be used to
determine and display how many records had been found. The application could also
perform different actions depending on how many records were found.
Add Language sections
The Add Language sections are executed when the user issues an ADD/UPDATE
command while in Add/Update/Delete mode. These Language sections are executed
only if a current record created by a CLEAR TO ADD is present.
All new records are added to the end of the selected set. Records added or updated
are exclusive locked (XLOCK) until the transaction is committed. On multi-occurrence
forms, a CLEAR TO ADD displays the last form full of the selected set. The new
record is displayed using the CLEAR TO ADD defaults.
NOTE:
The ACCELL/DBMS automatically provides referential integrity
constraints and ensures uniqueness for all primary keys.
223
ACCELL/DBMS automatically performs key field checking and
prohibits operations that would violate referential and key constraints.
For example, because of the referential integrity constraints, a record
that refers to another record can be Added/Updated only if the
referenced record already exists.
Additional data dictionary level validity constraints may be specified for
fields (Advanced Field Attributes), thus ensuring data consistency.
224
Figure 46 shows Add and Update Language execution in response to the ADD/
UPDATE user command.
replace
not stored
find
COMPANY:
SALES REP#:
ADDRESS:
NAME:
PHONE:
CITY:
MAIN PHONE:
STATE:
CONTACT
ZIP:
MAP:
CLEAR
TO ADD
ADD/
UPDATE
Enter company name.
Executes
BEFORE ADD
or
BEFORE UPDATE
Executes
AFTER ADD
or
AFTER UPDATE
Adds the new record to
the database
or
Modifies the current
record in the database
Executes
ON CLEAR
TO ADD
Displays CLEAR TO ADD
values in the form’s
field. Enters
ADD/UPDATE/DELETE mode.
Figure 46. Add/Update language execution
BEFORE ADD section
The BEFORE ADD section is executed immediately before beginning the requested
Add.
225
BEFORE ADD can be used to log the user who added specific records, to provide
additional security constraints, to verify that the user does want to do an ADD/
UPDATE and to perform additional validity checking. An Add operation can be aborted
by using the REJECT OPERATION statement in this section.
ON CLEAR TO ADD section
The ON CLEAR TO ADD section executes whenever the user presses CLEAR TO
ADD or an implicit Clear to Add is performed.
This Language section provides an alternative to using the Clear to Add expression
(CLEAR_ADD_EXP attribute) to set a variable's default value.
AFTER ADD section
The AFTER ADD section is executed immediately after completion of the requested
Add, even if the Add is unsuccessful.
AFTER ADD can be used to count records added, to update totals, or to perform
validity checking.
Check the status of an Add operation in this section and be sure to notify the user if it
has failed.
Update Language sections
The Update Language sections are executed when the user issues the command
while in Add/Update/Delete mode. It is only executed if the current record is present in
the database.
NOTE:
226
The ACCELL/DBMS automatically provides referential integrity
constraints and ensures uniqueness for all primary keys. ACCELL/
DBMS automatically performs key field checking and prohibits
operations that would violate referential and key constraints. For
example, because of the referential integrity constraints, a record that
refers to another record can be Added/Updated only if the referenced
record already exists.
NOTE:
Figure 46, shows Add and Update Language execution.
BEFORE UPDATE section
The BEFORE UPDATE section is executed immediately before the requested update
is performed.
BEFORE UPDATE can be used to log which users modified specific records, to
provide additional security constraints, to verify that the user does want to do an Add/
Update, and to perform additional validity checking. The update operation can be
aborted by using the REJECT OPERATION statement in this section.
AFTER UPDATE section
The AFTER UPDATE section is executed immediately after the requested Update is
completed.
AFTER UPDATE can be used to count the number of records modified, to update
totals.
Delete Language sections
The Delete Language sections are executed when the user issues a DELETE
RECORD command while in Add/Update/Delete mode.
ACCELL/IDS performs a delete only if there is a current record selected from the
database; all Delete Language sections are executed regardless of the outcome of
the DELETE RECORD command.
227
The figure that follows illustrates Delete Language execution in response to the
DELETE RECORD user command.
replace
not stored
find
COMPANY:
ADDRESS:
SALES REP#:
NAME:
PHONE:
CITY:
MAIN PHONE:
CONTACT
STATE:
ZIP:
MAP:
DELETE
Enter company name.
F1-Prv Form
F2-Nxt Form F3-Find
Executes
AFTER DELETE
Executes
AFTER DELETE
Deletes the current record from the
selected set and the database, and
displays the next record in the set
Figure 47. Delete Language Execution
BEFORE DELETE section
The BEFORE DELETE section is executed immediately before the requested Delete
is performed.
228
The BEFORE DELETE section can be used to reject the DELETE RECORD
command or to query the user before performing the deletion.
AFTER DELETE section
The AFTER DELETE Language section is executed immediately after completion of
the requested Delete, even if the Delete is unsuccessful.
AFTER DELETE can be used to count records deleted, to update totals.
Record Language sections
Record Language sections can be used to insure that the current record has been
updated before the user is allowed to move to the previous or next record in a
selected set.
The two record language sections, ON NEXT RECORD and ON PREVIOUS
RECORD, may affect performance. Consider carefully the effect on runtime
performance if you write extensive code in these sections. Record language sections
execute each time the user moves between records within a selected set. These
sections execute after the user issues the selected set command NEXT RECORD,
PREV RECORD, FIRST RECORD, LAST RECORD, NEXT SET, or PREV SET, and
before the current record changes and the screen is updated.
ON NEXT RECORD section
The ON NEXT RECORD Language section is executed whenever the user issues one
of the following record commands:
NEXT RECORD
NEXT SET
LAST RECORD
This language section can only be used for Standard forms.
If the user enters a NEXT RECORD command and there is no next record, the ON
NEXT RECORD section still executes.
229
NOTE:
Do not use the NEXT ACTION IS NEXT RECORD statement in the ON
NEXT RECORD Language section. NEXT ACTION IS NEXT
RECORD will create an infinite loop in the code.
For example:
FORM forders
TARGET_TABLE orders
ON NEXT RECORD
IF ( NOT is_current_record_stored$ () )THEN
BEGIN
DISPLAY 'WARNING! The current record has not been
updated
REJECT OPERATION
END
ON PREVIOUS RECORD section
The ON PREVIOUS RECORD Language section is executed whenever the user
issues one of the following record commands:
PREV RECORD
PREV SET
FIRST RECORD
This language section can only be used for Standard forms.
If the user enters a PREV RECORD command and there is no next record, the ON
PREV RECORD section still executes.
NOTE:
Do not use the NEXT ACTION IS PREVIOUS RECORD statement in
the ON PREVIOUS RECORD Language section. NEXT ACTION IS
PREVIOUS RECORD will create an infinite loop in the code.
For example:
FORM forders
TARGET_TABLE orders
230
ON PREVIOUS RECORD
IF ( NOT is_current_record_stored$ () )THEN
BEGIN
DISPLAY 'WARNING! The current record has not been updated
REJECT OPERATION
END
Field Language sections
Field Language sections can be used to initialize field attributes and values, control
and perform input to screen fields, and process input values.
231
Figure 48 shows Field Language execution in response to the NEXT FIELD and
PREVIOUS FIELD user commands.
replace
not stored
find
COMPANY:
ADDRESS:
SALES REP#:
NAME:
PHONE:
ADD/
UPDATE
CITY:
MAIN PHONE:
CONTACT
STATE:
ZIP:
MAP:
CLEAR
TO ADD
Enter company name.
F1-Prv Form
F2-Nxt Form F3-Find
Executes for current field
any remaining ON FIELD
WHEN FIELD CHANGES
AFTER FIELD
Executes for next field
BEFORE FIELD
ON FIELD
Figure 48. Field Language execution
NOTE:
In Find mode, only the INIT FIELD section is executed.
INIT FIELD section
The INIT FIELD Language section is executed after the form's initialization but before
the BEFORE FORM Language section. This section should be used to initialize those
field attribute values that are not expected to change during the form's execution. The
232
form can also be used to override the default field attribute values set by the ACCELL/
Generator.
Because the order in which fields are initialized is undefined, use of arbitrary
Language statements in this section is not recommended.
BEFORE FIELD section
The BEFORE FIELD section is executed upon initializing all fields, and upon initial
processing of a given field in the form's field-to-field progression. This section is
executed either just before input to a field or when the user issues a PREV FIELD
command. User input is not allowed during execution of this section.
This section can be used to initialize appropriate variables. It is also possible to
prevent input by setting the field's STOP_FOR_INPUT attribute to FALSE in this
Language section.
ON FIELD section
The ON FIELD section is executed immediately after the BEFORE FIELD section, if
the BEFORE FIELD section occurs. ON FIELD is the only section that can include an
INPUT statement. This section is normally used to get user input and perform
checking before accepting input.
Input checking can be done in the ON FIELD section by using appropriate conditional
and RESTART ON FIELD statements. If a field does not have an explicit ON FIELD
section, ACCELL/IDS performs an implicit INPUT. If you use the ON FIELD section
you must include an INPUT statement.
To allow for user input, the WHEN FIELD CHANGES Language section is not
executed until the ON FIELD section is finished. ACCELL/IDS
NOTE:
NEXT FORM and ZOOM commands suspend execution of the ON
FIELD section. ACCELL/IDS.
NOTE:
ON FIELD executes whether or not STOP FOR INPUT is set.
233
AFTER FIELD section
AFTER FIELD is executed as the final processing action for a given field in a form's
field-to-field progression. It is normally used to process accepted input data. AFTER
FIELD can be used to redisplay data entered in a different format or to set default
values if the user enters nothing in the field. However, it cannot be used to restart
input if a validity check fails.
WHEN FIELD CHANGES section
The WHEN FIELD CHANGES Language section executes every time the value of the
screen field changes. The execution of ON FIELD temporarily delays execution of
WHEN FIELD CHANGES until after ON FIELD is finished. No INPUT statements are
allowed in this section.
Do not do anything in this section that changes the field's value. Changing the value
will produce an infinite loop. For example, the following statement produces an infinite
loop if it appears in the WHEN FIELD CHANGES section of the employee_age field
Language:
SET employee_age TO UNDEFINED;
The WHEN FIELD CHANGES section can be used to calculate the value for a
dependent screen field, as in calculating the extension (price times quantity) if either
price or quantity change. The section can also be used to perform operations such as
displaying fields from other database tables when the value of a reference field
changes. An example of this would be selecting the customer's name and address
from the customer table when the customer number in the orders table changes.
234
Chapter 8: ACCELL/Language
statements
8.1 Introduction
An ACCELL/IDS application consists of a set of forms and a set of optional ACCELL/
Language scripts. Each script must be associated with a form, and usually consists of
one or more sections, such as AFTER ADD or ON FIELD. These sections contain
ACCELL/IDS statements of three types: database statements, screen statements,
and control statements.
Database statements directly manipulate records and fields in the database. Records
can be selected, updated, inserted, deleted, or locked. Database statements form the
Data Manipulation Language or DML, a subset of the ACCELL/Language. The syntax
of the DML is based on SQL, the industry-standard database query language.
Screen statements control the display of application information on the screen.
Control statements select the sequence of forms, modify variables, get user
responses to prompts, and change the flow of control. Other control statements–the
external function and pipeline statements–make it possible to extend ACCELL/IDS by
writing your own functions in C or by transmitting information to external files or
programs.
The following sections describe the three kinds of statements. Detailed descriptions of
the statements appear in alphabetical order in the ACCELL/IDS Statement
Descriptions section. For more information on statements, see Appendix A, ACCELL/
Language Grammar, under Statements.
235
Database statements
ACCELL/IDS database statements let you write Language statements to select and
modify records in tables.
SQL (Structured Query Language) is the industry standard database language,
developed as part of IBM's System R research project. ACCELL/IDS's DML
statements are compiled to produce extremely efficient intermediate code, unlike
many fourth generation language products that interpret the statements during
execution.
ACCELL/IDS database statements may select and operate on a single record or a set
of records. Sets of records are manipulated by statements using the WHERE clause.
The SET/SELECT statement description explains the use of the WHERE clause.
In addition, locking options (XLOCK, SLOCK, and UNLOCK) can be set in some
database statements to protect records and tables.
There are two ways in which records are changed in an ACCELL/IDS application: by
user commands and by ACCELL/Language statements. User commands such as
FIND, ADD/UPDATE and DELETE RECORD allow the user to manipulate the
database and immediately see the results.
Database changes made through Language statements will be invisible to the user
unless you make provisions to notify the user of changes. When writing applications,
be sure to tell the user about all important database changes made by Language
statements.
All database fields referenced in a single database statement must come from the
same table. Note that this does not limit a form to manipulating a single table–different
statements can manipulate different tables.
The following is a functional listing of the database DML statements:
236
SET/SELECT
Assigns database field values from selected records to ACCELL/IDS
variables.
Changes specified field values in the current target record.
UPDATE
Changes specified field values in a single record or a set of records.
INSERT
Adds a new record to a specified table.
DELETE CURRENT RECORD
Deletes the current target record.
DELETE
Deletes a record or set of records from a specified table.
XLOCK, SLOCK, AND
UNLOCK
Protects selected records (XLOCK, SLOCK) or unlocks (UNLOCK)
previously locked records.
Selecting records
ACCELL/IDS lets you manipulate sets of records or single records. In statements that
work with sets of records, the set is specified by the database table name and the
WHERE clause. The WHERE clause is a logical expression that usually contains
tests on database field values. For example, the following UPDATE statement will
retrieve all records from the employee table that have a job code of “REP”.
UPDATE employee SET #emp_department TO 'SALES' WHERE #emp_job_code =
'REP';
As the records are retrieved, the department field will be set to “SALES” and the
record will be written back out to the database. ACCELL/IDS performs the update on
every record in the table that meets the conditions in the WHERE clause.
Database statement effects
Although database statements can modify the selected set of any active form in the
application, this is not a good practice. Future releases of ACCELL/IDS may disallow
modification of another form's selected set. Such changes are invisible to the user
because the Manager is unaware of changes made this way and, consequently, does
not update the screen. Good application design requires that the user be notified of all
database changes.
Database statement errors
Database statement errors must be handled by the application. This can be done by
using the system function status$() to test the result of a database statement. See the
description of status$() in Chapter 6.5, ACCELL/IDS System Functions and Variables.
ACCELL/Language statements
237
Locking specifications
Lock statements and specifications (XLOCK, SLOCK, and UNLOCK) let you specify
additional protection for records. Locking statements protect records your application
is using from the actions of other transactions. Any statements in your application,
however, can modify records locked by your application.
ACCELL/IDS performs some automatic record locking. The current record always has
a shared lock. Any record that has been added or modified by the current transaction
has an exclusive lock. In addition, transaction level settings automatically set some
locks. See Choose Next Form section, for more information about transaction levels
and locking, and Chapter 9.6, Transaction Control and Locking, for a complete
description of transaction level and locking interaction.
The ACCELL/IDS DBMS and the ACCELL/Manager interact with DBMS utilities and
XLOCK as follows:
The DBMS utilities ...
XLOCK the ...
BUDS
IDXMNT
REDB
REKEY
REPLAY
REPOINT
SCOM
database
DBLOAD (insert, update)
SQL (delete)
specified tables
If the database utility cannot get the XLOCK, someone else is using the table or
database. In this case, the utility does not start. See XLOCK, for more information on
ACCELL/IDS locking.
Screen statements
Screen statements control the display of information and get user responses to
prompts. The table below lists the screen statements by functional group:
238
Screen statements
DISPLAY EXPRESSION
Displays an expression in a screen field window or on the FYI
message line.
DISPLAY TRIM
Displays a copy of a form's trim at a specified screen position.
ERASE TRIM
Erases the last instance of displayed trim for a specific form and
position.
REFRESH SCREEN
Forces ACCELL/IDS to update the screen if any part of the screen
has changed since the last time information was written to it.
REFRESH SCREEN repaints the entire screen. Simulates the
REPAINT user command
REPAINT SCREEN
Repaints the entire screen. Simulates the REPAINT user command.
User Response statement
INPUT
Enables the developer to determine the point in the ON FIELD section
where an input will be allowed. Can only be used in the ON FIELD
Language section.
Control statements
Control statements test values, make assignments to non-target variables, control the
sequence of forms processing, change the flow of control, enable calls to external C
functions, and write information to external files or processes.
The table below lists the control statements by functional groups. With the Flow of
Control statements, you can conditionally execute blocks of statements or repeat
statement blocks under various conditions. Descriptions and flowcharts for each Flow
of Control statement appear in the ACCELL/IDS Statement Descriptions section.
239
Assignment statement
SET
Assigns a specific value (including UNDEFINED) to an ACCELL/IDS
variable or ACCELL/IDS attributes.
Flow of Control statements
IF
Conditionally executes a statement or block of statements.
WHILE
Repeats a statement or block of statements while a condition is met.
FOR
Repeats a statement or block of statements. Similar to WHILE, and
also provides for initializing and incrementing.
REPEAT
Repeats a statement or block of statements. Similar to FOR and
WHILE except that the termination condition is tested at the end of the
loop.
SWITCH
Selects one of several possible actions.
RESTART
Restarts the ON FIELD section. Used when bad input is detected.
Reject statements
REJECT RECORD
Prevents a record form being added to the selected set. May only be
used in the ON FIND section.
REJECT OPERATION
Keeps a user command from being executed. May only be used in the
following sections: BEFORE FIND, BEFORE UPDATE, BEFORE
DELETE, BEFORE ADD, ON NEXT RECORD, ON PREVIOUS
RECORD, ON CLEAR TO FIND, ON PREVIOUS FORM, ON NEXT
FORM, and ON EXIT.
Commit statement
COMMIT TRANSACTION
Marks the current transaction as completed in the ACCELL/DBMS
Transaction Log. The statement starts a new transaction and retains
all locks except that exclusive locks are downgraded to shared locks.
Next Action statement
NEXT ACTION
240
Simulates a user command from inside the application. Can be used
to do a FIND, PREV FORM, NEXT RECORD, PREV RECORD,
CLEAR TO ADD, CLEAR TO FIND or ABORT APPLICATION.
Form sequence control statements
CHOOSE FIRST FORM
Determines the first form in an application. Actually a Language
section rather than a statement.
CHOOSE NEXT FORM
Determines from a standard form the next form to execute. Actually a
Language section rather than a statement.
ENABLE ZOOM
For the current field, enables calling up a Zoom form.
DISABLE ZOOM
Disables the Zoom form for the current field.
External functions and pipe statements
EXTERN STATEMENT
Declares an external function written in the C language.
CREATE PIPELINE
Creates a pipeline to write information from the application to a series
of programs.
WRITE PIPELINE
Writes information to a created pipeline.
CLOSE PIPELINE
Closes a pipeline, ensuring that any remaining information is
transmitted to the external process. Closes external files and halts
processes in the pipeline.
241
8.2 ACCELL/IDS statement descriptions
This section contains complete descriptions, including syntax listings, for all of the
ACCELL/Language statements. The descriptions appear in alphabetical order.
Sample statements are provided with each description to demonstrate how the
statement can be used.
Anywhere that statement appears in the syntax listings, you may use a single
statement or a statement block. A statement block consists of the keyword BEGIN
followed by a series of statements and terminated with the keyword END. Semicolons
may be used to terminate statements.
An asterisk (*) in a statement description indicates an item that may appear zero or
more times. A plus sign ( + ) follows an item that appears one or more times. Neither
the asterisk nor the plus sign are part of the statement.
A vertical bar ( | ) indicates alternative elements. For example, (item1|item2|item3)
means you can use one of the elements item1, item2, or item3.
Parentheses are used to enclose lists of alternatives. Neither the parentheses nor the
vertical bars are part of the statement except where noted.
Brackets ([ ]) enclose optional statement elements. Brackets are not part of the
statement syntax.
Upper case words indicate statement keywords. Although keywords appear in upper
case, you may use either upper or lower case in your applications.
Lower case words indicate parts of the statement you supply when you use the
statement.
NOTE:
242
The sample statements in this section assume that you are familiar
with the tutorial application and that you have the tutorial database
design for reference.
CHOOSE FIRST FORM and CHOOSE NEXT FORM
CHOOSE FIRST FORM
[ WHEN logical_expression] transaction_level
USING (form_name|EXIT)*
NOTE:
transaction_level and USING are required in CHOOSE FIRST FORM
and CHOOSE NEXT FORM statements.
CHOOSE NEXT FORM
[[ WHEN logical_expression] transaction_level
USING (form_name|EXIT)] *
logical_expression
An expression that evaluates to TRUE or FALSE. The expression is
evaluated to see if the form specified by form_name is a candidate
next form. The expression may include any of the ACCELL/IDS
relational and logical operators.
transaction_level
Specifies whether or not to start a new transaction and at what level.
The element used must be one of the following:
CONTINUE TX RECORD_CONSISTENCY,
CONTINUE TX SET_CONSISTENCY,
RESTART TX,
START TX RECORD_CONSISTENCY,
START TX SET_CONSISTENCY.
form_name
The name of the next form. Either a string expression or a form name.
CHOOSE FIRST FORM and CHOOSE NEXT FORM are both statements and
Language sections. Each consists of a section heading (CHOOSE FIRST FORM,
CHOOSE NEXT FORM) and one or more NEXT FORM statements.
CHOOSE FIRST FORM and CHOOSE NEXT FORM determine which form is
executed next. You can also set NEXT FORM in AGEN; CHOOSE FIRST/NEXT will
override any NEXT FORM specification made in the ACCELL/Generator. CHOOSE
FIRST FORM is used only in the Master Application form Language script and
determines the first form executed in the application. CHOOSE NEXT FORM is used
in a Standard form Language script and determines the next form executed.
Notice that CHOOSE FIRST FORM and CHOOSE NEXT FORM also establish the
beginning and end of transactions through the transaction level clause. See the
description of the CHOOSE NEXT FORM language section in Chapter 7, ACCELL/
Language sections, for more information about transaction levels.
243
If EXIT is used instead of a form name, ACCELL/IDS executes the ON EXIT section
for the current form (if one exists), and then ends the application.
Sample statements
CHOOSE FIRST FORM
WHEN user_name$() < > 'Alexander'
START TX RECORD_CONSISTENCY
USING EXIT;
WHEN user_name$() = 'Alexander'
USING first_form
CHOOSE NEXT FORM
WHEN company_name = 'Allied Amalgamated'
CONTINUE TX SET_CONSISTENCY
USING company_form
In the first example, the statements get the user's name from the operating system
using the user_name$ function. If the user's name is any name other than Alexander,
the application exits. The effect of the statements is to keep anyone with the wrong
user name from running the application.
In the second example, the next form selected would be company_form when
company_name is equal to Allied Amalgamated. For company names other than
Allied Amalgamated, the user would get the message:
There is no next form.
CLOSE PIPELINE
CLOSE PIPELINE variable
variable
A standard ACCELL/IDS variable name containing the identifier of an
open pipeline.
Closes the pipeline identified by the variable. Pipelines must be closed before the
application ends in order to avoid loss of data.
Sample Statement
244
CLOSE PIPELINE $pipe1;
This statement closes the pipeline identified by $pipe1. Before closing the pipeline,
any remaining data is transmitted to the waiting file or process. See Write Pipeline, for
examples of all of the pipeline statements.
COMMIT
COMMIT TX
The COMMIT TX statement writes an end transaction entry in the ACCELL/DBMS
Transaction Log and ends the current transaction (see the ACCELL/DBMS Reference
Manual for more information about transaction logging). A new transaction is started.
All locks are retained, but all exclusive locks (XLOCKs) are downgraded to shared
locks (SLOCKs).
The form attribute AUTO_COMMIT also can be used to log transactions. See the
Form Attributes section, for more information.
CREATE PIPELINE
CREATE PIPELINE variable program_name_list
[OUTPUT [IS] string_expression] ;
program_name_list
A series of program names, separated by commas. The program names form
a standard operating system pipeline.
string_expression
The pathname of the data file to receive output from the last process in the
pipeline. May be a string constant or string variable.
variable
A standard ACCELL/IDS variable to receive the identifier of the opened
pipeline.
Creates a pipeline to send information out of the application to a program or a series
of programs. When ACCELL/IDS executes the statement, it creates a pipeline, stores
an identifier in the variable, and transmits any data from corresponding WRITE
PIPELINE statements to the programs in the program name list.
Optionally, ACCELL/IDS sends the output from the last program to a data file
identified by the OUTPUT IS clause.
245
The value of the variable must remain unchanged until the pipeline is closed. The
programs in the list represent a standard operating system pipe. That is, the output of
the application goes to the first program. The output of the first program becomes the
input to the second program, and so on. If literal program names rather than variables
are used, each program name must be enclosed in single quotes.
Use CLOSE PIPELINE to ensure that all data has been written to the file or process.
Sample Statement
CREATE PIPELINE $pipe_one 'RPT script -','lpr';
This statement creates a pipeline to the report generator RPT. The RPT package
receives its formatting commands from script and the report information from the
standard input (indicated by the minus sign). The output of RPT is sent to the line
printer spooler, lpr.
Note that command line arguments for a program in the pipeline must be part of the
same string as the program name. (See the description of WRITE PIPELINE for
examples of all of the pipeline statements.)
DELETE
DELETE CURRENT RECORD ;
DELETE table_name [WHERE logical_expression];
logical_expression
Any expression that evaluates to TRUE or FALSE. The expression is
evaluated to determine whether or not to delete a given record. A logical
expression may include any of the ACCELL/IDS relational and logical
operators.
table_name
The identifier of a database table containing records to be deleted.
In the first form, the DELETE statement removes the current record from the
database. A new current record is then chosen.
The second form of the DELETE statement removes the record or records from the
database identified by the WHERE clause.
Notice that using the WHERE clause makes the DELETE statement operate on a set
of records; all records that satisfy the WHERE conditions are deleted. If no WHERE
246
clause appears, the second form of the statement deletes all of the records in the
table. Use the system function status$ to test the results of a DELETE statement.
All deleted records remain locked until the transaction is committed and an UNLOCK
is executed.
Sample Statement
DELETE text WHERE #tx_lead = fleads:ld_key ;
This statement deletes all records in the table text that meet the condition in the
WHERE clause. In the tutorial application, this statement would delete the text lines
for the current lead displayed on the Text form. Recall that the database enforces
referential integrity constraints and does not allow deletion of a parent record when a
subordinate record still exists. In this example, the Text record must be deleted before
the Lead record. The # symbol is short for the table name followed by a period.
#tx_lead could also have been written text.tx_lead.
DISABLE ZOOM
DISABLE ZOOM TO form_name ;
form_name
The name of the Zoom form. It is either a string expression or a form name.
The DISABLE ZOOM statement disables zooming from the current field to the
specified Zoom form. Disabling an already disabled Zoom does not produce an error.
Sample Statement
DISABLE ZOOM TO fsalesrep;
This statement disables a zoom to the fsalesrep form for the current field. This feature
could be useful, for example, in an INIT FIELD section, where an ENABLE ZOOM is
executed once for a form. Then, DISABLE ZOOM could be used to turn the zoom off.
DISPLAY
DISPLAY [expression]
[FOR (screen_field | FYI_MESSAGE)]
247
[WAIT] [USING format_expression]
[DISPLAY_JUSTIFY [IS] (LEFT | RIGHT | CENTERED |
string_expression set to 'LEFT'/'RIGHT'/'CENTERED')] ;
expression
The ACCELL/IDS expression to display in the specified screen field or FYI
message area. Can be any valid expression–for example, a string, a numeric
constant, or a numeric expression.
format_expression
A series of format characters, enclosed in single quotes, to control the display
of the expression. Format expressions can be written for values of any data
type. Other formats are controlled by environment variables. See the following
discussion for more information.
screen_field
The name of the screen field in which to display the value of the expression.
The default is the current screen field.
string_expression
A string variable or string constant set to 'LEFT', 'RIGHT', or 'CENTERED'.
The DISPLAY statement displays an expression in a screen field window or in the FYI
message area.
NOTE:
Screen variable attributes are not applied to the displayed expression.
The format of the displayed value must be explicitly stated in the
USING and DISPLAY_JUSTIFY clauses of the DISPLAY statement.
If expression is omitted, ACCELL/IDS displays the current value of screen_field. If
neither the FOR nor the FYI_MESSAGE clauses appear, ACCELL/IDS uses the
current field. Using a non-screen field name in the DISPLAY statement is an error.
If used, the WAIT clause causes the application to pause until the user presses
RETURN. The WAIT clause should be used with the FYI_MESSAGE option to make
sure the user sees the message.
The DISPLAY_JUSTIFY option specifies left or right justification, or centering.
DATE format is determined by the setting of the environment variable DATETP. The
default format for the date is MM/DD/YY. This may be changed by making an
assignment to DATETP. See Chapter 9.2, Environment Variables for more information
about environment variables.
The default time format is HH:MM. The time is given according to a twenty-four-hour
clock.
248
The USING option determines how values of any data type appear in the field
window. If the USING clause is omitted, ACCELL/IDS uses a default format for
amount and numeric values.
The format_expression in the USING clause consists of an AMOUNT, NUMERIC,
FLOAT, or STRING format. A format expression consists of format codes for each digit
in the number or character in the string.
The table below describes the valid format codes that can be used for AMOUNT,
NUMERIC, and FLOAT values:
Format
language
Description
#
print digit or blank
&
print digit or zero (print leading zeros)
*
print digit or * (asterisk fill)
$
print digit or $ or blank (floating $)
+
print digit or + or blank (floating +) — prints only for positive values
–
print digit or – or blank (floating –) — prints only for negative values
(
print digit or ( or blank — prints only for negative values
)
print digit or ) or blank — prints only for negative values
,
print , or blank
.
print . or blank
NOTE: A negative sign (-) displays only if specified in the format. If not specified, the negative value
will display without any sign. However, the negative value will be stored in the database as a negative
For a value of 0 (zero), the ones digit is displayed, as well as ¢ (cents) for amounts.
For example:
Format
Displayed value
***
**0
###
_ _0
##.##
_0.00
#.##
0.00
**.&&
*0.00 or *0.45 (for .45)
NOTE: Underscores (_) indicate leading blanks
249
The following table shows how different formats display the number 1,246.75:
Format
Displayed value
&&&&&&.&&
001246.75
$$,$$$.&&
$1,246.75
$$$,$$$,&&
_$1,246.75
***,***.&&
**1,246.75
$##,###.&&
$ 1,246.75
(##,####.&&)
__1,246.75
NOTE: Underscores (__) indicate leading blanks
FLOAT expressions can also be displayed using the printf format syntax. This format
is exactly like the operating system printf function. See the Direct HLI Programmer's
Manual for more information on printf. The format specification has the following
syntax:
%[-][minimum field width][.][precision]f | e | g
Items enclosed in square brackets ([]) are optional. A list of items separated by the
vertical bar ( | ) indicates that you must choose one of the items in the list. The percent
sign ( % ) is required.
The optional minus sign (–) before the conversion specification indicates that the
result is to be left justified in the field width. The minimum field width is a number
indicating the minimum number of print positions in the result. If the result has fewer
characters, it will be padded with blank spaces to fill up the field width.
precision is the number of digits to appear after the decimal point. If precision is 0, no
digits after the decimal point are printed, and the decimal point is not printed either.
The conversion characters (f, e, and g) have the following meanings:
250
f
The field is converted to decimal notation in the style [–]ddd.ddd, where the number of
digits after the decimal point is equal to the precision specification.
e
The field is converted in the style [–]d.ddde-+dd, where there is one digit before the
decimal point and the number of digits after is equal to the precision specification.
g
The field is converted in style f or style e, whichever gives full precision in minimum space.
The following examples illustrate how various printf (FLOAT) format expressions affect
output:
Format
Value
Result
‘%10.2f’
12.3
“
12.30”
‘%10.2f’
123.456
“
123.46”
‘%12.4e’
123.456
“ 1.23456e+02”
‘%10.4g’
123.456
“ 123.4560”
‘%8.4g’
123456789
“1.23e+08”
STRING expressions can also be formatted with the USING option. The character
format codes for STRINGs are as follows:
Format Code
Description
%
print character
^
print the complete string value
X
print the character X
\\
print a backslash \
\\%
print a percent sign %
\\^
print a caret sign ^
\\X
print the character X
The following examples illustrate how character format codes can affect STRING
output:
Format
Value
Result
none
Invalid part number
“Invalid part number”
‘%%%%%%%%%%%’
Part Number
“Part Number”
‘ERROR–^’
Invalid Item
“Error–Invalid Item”
‘^\\%’
23
“23%”
251
Sample Statement
DISPLAY
DISPLAY
DISPLAY
DISPLAY
'Press any key to continue' FOR FYI_MESSAGE WAIT
current_date$() FOR fleads:ld_next_date
current_date$()
current_time$()
DISPLAY 'status = ' +
val_to_str$(status$())
for fyi_message
wait
The first statement prints the message in the FYI message area and pauses until the
user presses RETURN.
The next two statements use the function current_date$ to get the date from the
operating system and display it. The statement with the FOR clause displays the date
in the field ld_next_date on the form fleads. The other statement displays it on the
current screen field.
The next statement displays the current time using the ACCELL/IDS function
current_time$() to get the time from the operating system.
The final statement displays 'status=', followed returned by the status$ string system
function
NOTE:
You must concatenate strings (+) into a single expression to print two
fields of information for an fyi message.
DISPLAY TRIM
DISPLAY TRIM [FOR form_name ] [AT position] [WAIT];
252
form_name
The form whose trim is to be displayed. Either a string expression or a form name.
This cannot be a Help form name.
position
The row and column number for the upper left corner of the displayed trim. A
position consists of the row number, a comma, and the column number, all
enclosed in parentheses. Any numeric expression can be used for row and column
numbers. The position may be preceded by an “at” symbol (@) to indicate absolute
rather than relative coordinates (relative to the current form's origin).
The DISPLAY TRIM statement creates and displays a copy of a form's trim. Each
execution of the statement creates a new copy of the trim. The statement only
produces a copy of the trim–it does not display a true form.
If you omit the FOR clause, the statement displays the current form's trim.
A “commercial at” symbol (@) in front of the position indicates absolute coordinates
measured from the upper left corner of the screen. Without the `àt'' symbol, the
coordinates are relative to the origin of the last form. If the AT clause is left out,
ACCELL/IDS uses the specified form's most recent position. That is, ACCELL/IDS will
write over the current form if you display the current form.
If used, the WAIT clause displays the message:
Press RETURN to continue
on the FYI message line and causes the application to pause until the user presses
the return key. When the user presses the return key, the trim is automatically erased.
DISPLAY TRIM is one of the few instances when a form can alter a part of the screen
not within the form window. The window created for the new trim is controlled by the
current form. If the window is not erased by an appropriate ERASE TRIM statement, it
will be automatically erased when the user exits the current form. The trim may also
be erased by another form being written over it.
Sample Statements
DISPLAY TRIM FOR fitems;
DISPLAY TRIM FOR err_form AT @(3,10) WAIT;
The first statement displays the trim for the form fitems. In the Tutorial, if used in the
BEFORE FORM section of the forders script, this statement would give the user a
better idea of what forms are used in order entry.
The second statement displays a developer-supplied error window (the form err_form)
beginning at row 3, column 10 and waits for a user response before erasing the trim to
continue. Notice that the form coordinates are absolute coordinates.
253
ENABLE ZOOM
ENABLE ZOOM
[RECORD_CONSISTENCY | SET_CONSISTENCY]
TO form_name [AT position]
[REPEATED numeric_expression]
[RETURN KEY] ;
form_name
The name of the Zoom form. Either a string expression or a form name.
numeric_expression Any expression or variable that evaluates to a numeric value. Here, the numeric
expression determines how many occurrences of a multi-occurrence form will
appear at one time.
position
The row and column number for the upper left corner of the displayed trim. A
position consists of the row number, a comma, and the column number, all
enclosed in parentheses. Any numeric expression can be used for row and
column numbers. The position may be preceded by an “at”' symbol (@) to indicate
absolute rather than relative coordinates (relative to the current form's origin).
The ENABLE ZOOM statement sets optional parameters and enables zooming to the
specified Zoom form. Enabling an already enabled Zoom does not produce an error.
All the parameters are reset each time this statement is executed.
To enable the Zoom capability on screen fields when you initialize your screen form in
Find mode, you must specify ENABLE ZOOM from within the field's INIT FIELD
Language section. If you do this in BEFORE FIELD, it is enabled only in ADD/
UPDATE/DELETE mode. Be sure not to use the DISABLE ZOOM statement in any
code section for fields that you wish to Zoom from in Find mode.
For the field you Zoom from, the field attributes Stop for Input and Updatable must be
set to yes.
For example:
BEFORE FORM
SET AUD_ON_ENTRY TO FALSE
FIELD cust_name
INIT FIELD
ENABLE ZOOM to cust_rec
254
The RECORD_CONSISTENCY and SET_CONSISTENCY options determine the
transaction level for database operations performed from the Zoom form. The
transaction level is set to the level for the previous form when the application returns
from the Zoom form. If the transaction level is omitted, the Zoom form executes at the
same level as the current form.
The AT clause determines the location of the form's upper left corner. If omitted, the
Zoom form has the same origin defined for it within ACCELL/Generator. An error
occurs if there is not enough room for the form on the screen.
measured from the upper left corner of the screen. Without the “at” symbol, the
coordinates are relative to the origin of the last form.
The REPEATED option temporarily resets the number of occurrences for a multioccurrence form. It is not an error to use this clause on forms that are not multioccurrence forms: ACCELL/IDS simply ignores the option.
The RETURN KEY option lets you bring key values back to a form from the Zoom
form. Only the key on the Zoom form can be brought back automatically. If a key
consists of more than one field, the first value in the first Zoom form key field is
displayed in the form field at which the zoom was performed.
Successive key fields are displayed in successive form fields in key field order. Thus,
a screen field is required for each part of the key. Key field order is specified in the
database design. ACCELL/IDS handles RETURN KEY errors normally except that
any fields not yet processed are discarded.
If RETURN KEY is specified but there is no key to return, input resumes on the
current form's current field. Similarly, if the user presses CANCEL ZOOM, no value is
returned.
Sample Statement
FIELD co_sales_rep
BEFORE FIELD
ENABLE ZOOM TO fsalesrep RETURN KEY
255
This statement, in the BEFORE FIELD section of the fcompany form enables a zoom
to the fsalesrep form from the co_sales_rep field and on PREV FORM the sales
representative key is returned.
The zoom is disabled by the following statement:
DISABLE ZOOM TO fsalesrep
ERASE TRIM
ERASE TRIM [FOR form_name ] [AT position];
form_name
The name of the form whose trim is being erased. It is either a string expression or a
form name.
position
The row and column number for the upper left corner of the displayed trim. A position
consists of the row number, a comma, and the column number, all enclosed in
parentheses. Any numeric expression can be used for row and column numbers. The
position may be preceded by an “at” symbol (@) to indicate absolute rather than
relative coordinates.
The ERASE TRIM statement erases the last instance of trim displayed at the
specified position. If trim has been displayed several times on top of itself, ERASE
TRIM erases only the most recently created trim.
If the FOR and AT clauses are omitted, ERASE TRIM erases the last trim displayed.
measured from the upper left corner of the screen. Without the “at” symbol, the
coordinates are relative to the origin of the last form.
If there is no AT clause, ACCELL/IDS uses the location of the form's most recent
occurrence. Instances of form trim are identified by position and form name. Using the
ERASE TRIM statement when there is no displayed trim is an error.
An error message is generated if the AT clause specifies a position at which there is
no trim.
Sample Statement
ERASE TRIM FOR fitems;
256
This statement erases the trim for the fitems form at the last place it was displayed.
Statements to display and erase trim can be used to produce custom Help forms that
appear under program control. To display such a screen, use a DISPLAY TRIM
statement in the BEFORE FIELD section. The form will remain on the screen until the
user moves to another field if you put an ERASE TRIM statement in the AFTER
FIELD section.
EXTERN
EXTERN C (type_spec | VOID) FUNCTION
function_name ([formal_parameter_list]);
formal_parameter_list
A list of ACCELL/IDS variables indicating how many parameters are passed to
a developer-written C function. The maximum number of parameters is 31.
Variable names are separated by commas. A variable in the parameter list that
is set in the function must be preceded by the keyword RESULT.
function_name
The name of the developer-written function. The form and length of the name
depend on the local C compiler.
type_spec
The ACCELL/IDS type of the function value. Valid types are NUMERIC,
FLOAT, AMOUNT, BOOL, STRING, DATE, and TIME.
The EXTERN statement makes it possible to call a developer-supplied function
written in C. The function can return a value like a standard ACCELL/IDS function or
return values through variables in the parameter list.
If the keyword VOID is used rather than a type_spec, ACCELL/IDS assumes the
function does not return a value.
See Chapter 9.4, User Functions, for complete information about writing and
incorporating functions.
Sample Statement
EXTERN C FLOAT FUNCTION
paycalc(principal,rate,term)
This declaration defines an external function named paycalc that has as arguments
principal, rate, and term. It returns a FLOAT value.
257
In an application, a call to paycalc might look like
SET answer TO paycalc(10000,12,48);
This statement calls the function paycalc which uses the values 10000, 12, and 48.
paycalc returns a value that is assigned to the variable answer. The returned value is
a FLOAT.
EXTERN statements must be the first statements in a language script.
FOR
FOR ([first_expression];
[logical_expression];
[second_expression]) statement
first_expression
Any valid ACCELL/IDS expression. The expression is evaluated once at the
beginning of the loop.
logical_expression
Any ACCELL/IDS expression that evaluates to TRUE or FALSE. The expression
is evaluated at the beginning of each loop iteration. The loop ends when the
expression becomes FALSE.
second_expression
Any valid ACCELL/IDS expression. This expression is evaluated at the end of
each loop iteration. See the discussions of IF and WHILE.
statement
Any valid ACCELL/IDS statement. Note that this includes statement blocks, as
well as single statements.
The FOR statement executes statement as long as the logical_expression is TRUE.
At the beginning of the FOR statement, ACCELL/IDS performs a one-time evaluation
of the first expression. Next, it evaluates the logical_expression. If the
logical_expression is TRUE, the statement executes, the second_expression is
evaluated, and ACCELL/IDS again evaluates the logical_expression. This sequence
continues until logical_expression is FALSE. When the logical_expression is FALSE,
the FOR statement ends. The FOR statement is equivalent to the following WHILE
loop:
first_expression;
WHILE logical_expression;
BEGIN
statement;
258
second_expression;
END
You can use a FOR loop or a WHILE loop depending on your programming style and
personal preference.
The following flowchart illustrates the execution sequence of the FOR statement:
FOR
EVALUTE
FIRST
COMPANY
EXPRESSION
IS LOGICAL
EXPRESSION
TRUE?
NO
YES
DO THE
STATEMENT
COMPANY
OR BLOCK
EVALUATE
SECOND
COMPANY
EXPRESSION
Figure 49. Execution sequence of FOR statement
259
Sample Statement
FOR (SET $index TO 1; $index < 100;
SET $index TO $index + 1)
DISPLAY index;
This statement displays the numbers 1 through 99 in the current screen field.
IF
IF logical_expression THEN statement
[ ELSE statement ]
logical_expression
Any ACCELL/IDS expression that evaluates to TRUE or FALSE.
statement
Any valid ACCELL/IDS statement. Note that this includes statement
blocks, as well as single statements.
The IF statement conditionally executes a statement or block. ACCELL/IDS evaluates
the logical_ expression and, if it is TRUE, the statement or block following THEN is
executed. If the logical_expression is FALSE, the statement following THEN is
skipped; if there is an ELSE, its statement or block is executed when
logical_expression is TRUE.
260
The following flowcharts illustrate the execution sequence of the IF statement:
IF
NO
IS
LOGICAL
EXPRESSION
TRUE?
YES
DO THE
STATEMENT
OR BLOCK
AFTER THE
WORD THEN
CO M PAN Y
Figure 50. IF statement execution, No ELSE clause
261
IF
NO
IS
LOGICAL
EXPRESSION
TRUE?
YES
DO THE
STATEMENT
OR BLOCK
AFTER THE
WORD THEN
DO THE
STATEMENT
OR BLOCK
AFTER THE
WORD ELSE
Figure 51. IF statement execution with ELSE clause
Sample Statement
IF forders:ord_terms = UNDEFINED THEN
SET forders:ord_terms TO `2% 10, net 30 days'
This statement is used in the forders form Language script to set the order terms to
the default value of '2% 10, net 30 days' if the user does not enter a value for it.
INPUT
INPUT
262
The INPUT statement retrieves information the user types into the current field. Input
is allowed only for screen variables. Up to 256 characters may be entered. The INPUT
statement is used only in an ON FIELD section.
On input to a Boolean field, only ``Y'' and ``N'' are allowed. Boolean field input is not
case sensitive.
Information entered using an INPUT statement can be tested and the user required to
re-enter it using a combination of IF, RESTART ON FIELD, and DISPLAY statements.
RESTART ON FIELD lets you redo input by restarting the ON FIELD Language
section. The DISPLAY statement can be used to display an appropriate error
message explaining why the input must be reentered.
The INPUT statement is affected by the current value of the field's attributes. For
example, if a field's STOP_FOR_INPUT attribute is set to NO, the INPUT statement
cannot be executed.
Sample Statement
FIELD sc_name_field
ON FIELD
INPUT;
IF (NOT namechk($sc_name_field)) THEN
BEGIN
DISPLAY 'Letters, blanks, apostrophes, hyphens only'
FOR FYI_MESSAGE WAIT;
RESTART ON FIELD;
END;
This section receives input from the field sc_name_field. After an entry is made, the
input value is passed to a user function, namechk. If namechk returns FALSE–the
input is not valid–then the section displays an error message and restarts the ON
FIELD section. Note the use of the WAIT option on the DISPLAY statement. Without
the WAIT option, the error message would appear, but would not remain on the
screen long enough for the user to read it.
263
INSERT
INSERT INTO table_name
[(] db_field_name_list [)]:
expression_list
db_field_name_list
A list of target fields separated by commas. This list contains the fields in
the new record that will have values assigned to them. Any fields not in
the list are assigned the DBMS default values.
expression_list
A list of ACCELL/IDS expressions separated by commas. The
expressions are evaluated and the values are assigned to the
corresponding fields in db_field_name_list.
table_name
The name of a database table. The new record is added to this table.
The INSERT INTO statement adds a new record to the specified table. The statement
assigns the first value in expression_list to the first target field, the second value to the
second field, and so on until the end of the list. ACCELL/IDS then inserts the record
into the table. The expressions must be assignment compatible with the DBMS type of
the data fields. Assignments are made to all record fields whether specified or not.
If the expression list is shorter than the database field list, ACCELL/IDS assigns the
corresponding DBMS default value to the field. The expression list must include a
value for the key field.
Use the system function status$ to test the result of an INSERT.
NOTE:
The parentheses around db_field_name_list are optional but are part
of the statement.
Sample Statement
INSERT INTO stock
#st_number, #st_description, #st_unit_price:
2000, 'Stool, Artists', $49.95;
This statement would assign the values 2000, `Stool, Artists', and $49.95 to the
variables st_number, st_description, and st_unit_price. These variables would then be
used to make a new entry in the database table stock. Because st_number is a key
field, an error would occur if an item with stock number 2000 is already in the table.
264
NEXT ACTION
NEXT ACTION [IS] action_keyword;
action_keyword
One of the keywords listed below. Used to simulate the corresponding
user command from within the application.
The NEXT ACTION statement simulates a user command from inside the application.
NEXT ACTION can be used to force execution of a user command without having to
rely on the user to press a key. NEXT ACTION can only be used to perform the
following actions:
FIND
NEXT FORM
PREV FORM
NEXT RECORD
PREV RECORD
CLEAR TO ADD
CLEAR TO FIND
ABORT APPLICATION
The EXIT option starts execution of the AFTER APPLICATION section, if one exists,
and then terminates the application. If there is no AFTER APPLICATION section, the
application comes to a normal end.
Sample Statement
IF current_record_num$() = current_record_count$()
THEN
NEXT ACTION is CLEAR TO ADD
This statement is used in the fitems Language script to automatically perform a
CLEAR TO ADD if the user presses from the last field of the last item record for an
order.
REFRESH SCREEN
REFRESH SCREEN
265
The REFRESH SCREEN statement forces an immediate update of the information on
the screen.
ACCELL/IDS buffers output to the terminal, periodically updating the information on
the screen. Because of this use of buffered output, the displayed information may not
immediately reflect database changes. The REFRESH SCREEN statement forces
ACCELL/IDS to update the display to reflect any changes you may have just made.
REJECT OPERATION
REJECT OPERATION
The REJECT OPERATION statement keeps the user from performing a specific
operation. The Language section the statement appears in determines the operation
rejected. The table below shows the allowed Language sections and the
corresponding operation the statement prevents.
Language section
Rejected operation
Executed code section
BEFORE FIND
FIND
BEFORE FIND, AFTER FIND
BEFORE ADD
ADD
BEFORE ADD, AFTER ADD
BEFORE UPDATE
UPDATE
BEFORE UPDATE, AFTER UPDATE
BEFORE DELETE
DELETE
BEFORE DELETE, AFTER DELETE
ON NEXT FORM
NEXT FORM
N/A
ON PREVIOUS FORM
PREVIOUS FORM
N/A
ON NEXT RECORD
NEXT RECORD,
NEXT SET,
LAST RECORD
N/A
PREV RECORD,
PREV SET,
FIRST RECORD
N/A
ON CLEAR TO FIND
CLEAR TO FIND
N/A
ON EXIT
ABORT APPLICATION
N/A
ON PREVIOUS RECORD
N/A
N/A
REJECT OPERATION keeps executing the relevant code section (BEFORE ... and
AFTER ...) and then returns after completing the section.
If the code sections are to execute only if the operation is successful, the code must
be within an IF test having the same criteria used for acceptance.
266
The only “goto” language statement is NEXT ACTION.
Sample Statement
BEFORE ADD
IF user_name$() < > 'Alexander' THEN
REJECT OPERATION
This section prevents anyone with a user name other than Alexander from doing an
Add.
REJECT RECORD
REJECT RECORD
The REJECT RECORD statement discards a record found by a user FIND command.
REJECT RECORD may appear only in the ON FIND Language section. The rejected
record is not included in the selected set and cannot be viewed by the user.
REJECT RECORD provides another way to limit a user's search criteria–in addition to
the use of search ranges–to provide additional security for specified users or records.
Rejected records are excluded from the total of current_record_count$.
Sample Statement
ON FIND
IF emp_last_name = 'Smithers' THEN
REJECT RECORD
This REJECT RECORD statement keeps the record for Smithers from being selected,
viewed, or altered.
REPAINT SCREEN
REPAINT SCREEN
REPAINT SCREEN restores the entire screen display. The statement can be used to
restore the display after a call to an external procedure that produces screen output.
The effect is the same as the user giving the REPAINT command.
267
REPEAT
REPEAT statement_list UNTIL logical_expression;
logical_expression
Any ACCELL/IDS expression that evaluates to TRUE or FALSE. The
statement_list repeats until the expression becomes TRUE.
statement_list
One or more ACCELL/IDS statements. These statements form the
body of the REPEAT loop.
The REPEAT statement repeatedly executes a statement list as long as
logical_expression is FALSE. The major difference between the REPEAT and WHILE
statements is that ACCELL/IDS evaluates logical_expression after each execution of
the statement. This means that a REPEAT loop's statement list is executed at least
once; a WHILE loop's statement will not be executed at all if logical_expression is
initially FALSE.
The following flowchart illustrates the execution sequence of the REPEAT statement:
REPEAT
DO
STATEMENT
LIST
EVALUATE
EXPRESSION
AFTER
WORD UNTIL
IS LOGICAL
EXPRESSION
TRUE?
YES
NO
Figure 52. Execution sequence for REPEAT statement
Sample Statements
SET indx TO 100
REPEAT
DISPLAY indx
SET indx TO indx + 1
UNTIL indx > 50
268
This REPEAT statement displays the value 100 in the current screen field and then
leaves the loop.
RESTART ON FIELD
RESTART ON FIELD
The RESTART ON FIELD statement starts the ON FIELD section over again.
NOTE:
This statement can appear only in an ON FIELD Language section.
Sample Statements
FIELD answer
ON FIELD
INPUT
IF answer < > 'good' AND answer < > 'bad' THEN
BEGIN
DISPLAY
'Enter "good" or "bad". Press any key to continue.'
RESTART ON FIELD
END
The statements above receive input from the screen field answer. If the input is not
one of the two correct values, the DISPLAY statement prints a message in the FYI
MESSAGE area and the RESTART statement restarts the ON FIELD section.
The WAIT option must be used on the DISPLAY statement. Without the WAIT option,
ACCELL/IDS displays the message–but it is immediately overlaid with the field's FYI
message, preventing the user from reading the error message.
269
SET
SET (variable | attribute) TO expression
attribute
Any valid ACCELL/IDS attribute name. The attribute will be set to the value of the
expression. The expression and the attribute must be assignment compatible. See
section 6.3, ACCELL/IDS Attributes for a complete list of attributes.
variable
Any valid ACCELL/IDS variable. The variable is set to the value of the expression. The
expression and the variable must be assignment compatible. See Chapter 6.2,
Variables for more information about variables.
NOTE:
The parentheses in the syntax description are not part of the
statement.
The assignment statement, SET, changes the value of an ACCELL/IDS variable or
attribute and may, indirectly, change screen field and target record values.
If the variable is a screen or screen/target variable, the displayed value changes when
the variable's value changes. If the screen field linked to the variable is part of a
covered active form, the new field value appears only when the form reappears.
If the variable is linked to a field in the target table, changing its value changes the
field value only in the current record's buffer. The new value is not added to the
database until the current record is added or updated.
In the ACCELL/Language the SET statement is not actually a statement; it is an
expression. This means that the SET statement, unlike other statements, has a value.
Because SET has a value, you can put a SET statement inside another SET
statement to perform multiple assignments. You can use SET anywhere that an
expression may appear.
Sample Statements
SET var1 TO SET var2 TO SET var3 TO 0
DISPLAY SET var1 TO var1 + 1
SET screen_field:REVERSE TO TRUE
The first statement assigns the value 0 to the three variables, var1, var2, and var3.
270
The second statement increments the variable var1 and displays the value.
The final statement sets the REVERSE attribute of the screen variable screen_field to
TRUE. Setting the REVERSE attribute to TRUE displays the field in reverse video on
the screen.
SET/SELECT FIELD
SET variable_list TO SELECT
[AND (XLOCK | SLOCK)
db_field_name_list FROM table_name
[WHERE logical_expression]
[ORDER BY db_field_name_list]
[EXECUTING statement_block]
variable_list
A list of variables separated by commas. Values are to be assigned to these
variables.
db_field_name_list
A list of database field names separated by commas. In the first
db_field_name_list, these are database variables whose values are assigned to
the variables in variable_list. All database variable names must be preceded by
the table name and a period or the table name symbol #.
The db_field_name_list in the ORDER BY clause sorts the records in the
resulting selected set according to the list. Each item in the list is used as a sort
field and must be followed by ASCENDING or DESCENDING.
logical_expression
Any ACCELL/IDS expression that evaluates to either TRUE or FALSE. The
expression determines which records are chosen by the SELECT clause.
statement_block
A series of ACCELL/IDS statements starting with the keyword BEGIN and
ending with the keyword END. The statement_block in the EXECUTING clause
is done once for each record selected. UNLOCK statements cannot appear in
the block.
NOTE:
Even if the statement block contains only one statement, BEGIN and
END are required.
table_name
The name of a database table from which records will be selected.
The SET/SELECT statement retrieves some or all of a record's fields from the
database and assigns their values to the specified variables. There is no implicit
ordering to the assignments.
The SET/SELECT statement operates on one or more records depending on the
combination of the WHERE clause and the EXECUTING block. When the WHERE
271
clause appears by itself, ACCELL/IDS arbitrarily picks one of the records meeting the
WHERE criteria and makes the assignments to the variables in the variable_list.
For example, the following statement arbitrarily picks one record from the set of
employees in the sales department and assigns the last name to the variable
one_name.
SET one_name TO SELECT employee.emp_last_name
FROM employee
WHERE employee.emp_department = 'SALES'
The WHERE clause in combination with the EXECUTING block causes ACCELL/IDS
to cycle through all records that meet the WHERE criteria. For example, the following
statement cycles through all of the records for employees in the “Sales” department
and displays their last names in the current screen field. Notice the use of the symbol
# as a short notation for the table name.
SET one_name TO SELECT #emp_last_name
FROM employee
WHERE #emp_department = 'SALES'
EXECUTING
BEGIN
DISPLAY one_name
END
ACCELL/IDS automatically chooses (from several paths that may be available) the
optimum access path to the data specified by the WHERE clause. The ACCELL/
DBMS supports four access methods:
•
hashing – on a primary key
•
B-tree index – on any field or group of fields
•
explicit relationships – linked references between parent and child records
•
buffered sequential scan – all types of fields
For WHERE clause optimization to function correctly, you should fully expand all
expressions before using them in the WHERE clause. Expanding all expressions in
the WHERE clause can result in a ten-fold performance increase over any single
access method.
272
For example, the WHERE clause in the following statement contains expressions that
have not been fully expanded:
SET finventory:$nv_number TO
SELECT #nv_number FROM nvntry
WHERE #nv_description = half_name_1 + half_name_2
ACCELL/IDS cannot correctly determine the optimum access method for selecting
this data. To ensure WHERE clause optimization, the clause above should be
expanded as follows:
whole_name = half_name_1 + half_name_2
SET finventory:$nv_number TO
SELECT #nv_number FROM nvntry
WHERE #nv_description = whole_name
The ORDER BY clause causes records to be selected in the sort order determined by
the db_field_name_list in the clause. For example, the clause:
ORDER BY emp_last_name ASCENDING
could be used in the preceding example to display the employee names in
alphabetical order. Each item in db_field_name_list is used as a sort field and must be
followed by ASCENDING or DESCENDING.
If a locking option (XLOCK or SLOCK) appears in the statement, the selected record
or records change lock status according to the locking option.
The EXECUTING clause includes a block of statements that is done once for each
record that meets the SELECT criteria. In addition, STRING comparisons using the
operators <, >, <=, and >= must be specified in an IF statement within the
EXECUTING block. For example:
SET $empid, $lname TO
SELECT #empid, #lname
FROM emp‘
EXECUTING
BEGIN
IF ( $lname > 'S' ) THEN
END
273
SET/SELECT, like SET, is an expression. The value of SET/SELECT is the value of
the first variable in variable_list. This allows you to place a SET/SELECT to perform
multiple assignments or to use a SET/SELECT anywhere an expression may appear.
The system function status$ can be used to test the results of a SET/SELECT
statement.
Sample Statement
SET s_emp_first, s_emp_last, s_emp_ext TO
SELECT #emp_first_name, #emp_last_name, #emp_ext
FROM employee WHERE #emp_job_code = 'REP'
This statement selects all employees with a job code of “Rep”. However, only one of
those records' values will be assigned to the variable list after the keyword SET. The
selection of the record is arbitrary. Remember that the symbol # is a short notation for
the table name followed by a period. For example,
#emp_first_name
is the same as
employee.emp_first_name.
The following statement selects the same set of records as the previous statement.
However, the executing block executes once for each record selected. The effect is to
display the values of the three variables for every employee with a job code of “Rep”.
FROM employee
WHERE #emp_job_code = 'REP'
EXECUTING
BEGIN
DISPLAY s_emp_first + s_emp_last + s_emp_ext WAIT
END
The following statement selects and displays the same employees as the preceding
example except that the employees appear in alphabetical order:
274
FROM employee
ORDER BY #emp_last_name ASCENDING, #emp_first_name ASCENDING
EXECUTING
BEGIN
DISPLAY s_emp_first + s_emp_last + s_emp_ext WAIT
END
The following statement shows how an IF statement within the EXECUTING clause is
used instead of a WHERE clause for a string comparison operation.
SET $empid, $lname TO
SELECT #empid, #lname
FROM emp
EXECUTING
BEGIN
IF ( $lname > 'S' ) THEN
BEGIN
....
END
END
SLOCK
SLOCK table_name [WHERE logical_expression];
table_name
The name of the table to be SLOCKed or the table containing the records to be
SLOCKed.
logical_expression
Any ACCELL/IDS expression that evaluates to TRUE or FALSE. When the
WHERE clause appears, ACCELL/IDS evaluates this expression for every record
in the table. A record is SLOCKed only when logical_expression is TRUE.
An SLOCK statement protects selected records and tables. An SLOCK is a shared
lock. Any transaction may read an SLOCKed record or table, but no other transaction
may modify it.
The WHERE option, when used, identifies the set of records to lock; the set may be
empty. ACCELL/IDS evaluates the logical expression for each record in the table.
When the expression is TRUE, the record is SLOCKed. When there is no WHERE
clause, the statement requests a lock on the entire table.
275
Any time a lock is attempted on a set of records, the lock fails if a member of the set
cannot be locked.
ACCELL/IDS automatically unlocks all locked records at the end of the current
transaction.
Locking statements affect only other users of the database. An application can read
and modify any records it has locked. The ACCELL Lock Manager allows the
Environment to place “Shared” locks at the application level. Many developers can be
working on the same application at the same time, but are prevented from adding,
deleting, or updating on the same form or in the same Language script at the same
time.
Execution of an SLOCK statement does not guarantee that the record or table is
locked. The statement generates a request for a shared lock on the object. If the
request cannot be granted, ACCELL/IDS generates an error message. Such an error
usually indicates that another transaction (application) is holding a conflicting lock.
You can use the system function status$ to test the results of an SLOCK statement.
You can write your application so it attempts a lock several times if an SLOCK fails. If,
after repeated attempts, the lock still fails, it is best to start the transaction over and
release all locks. This prevents a deadlock with another application over the database.
Be sure your application provides appropriate messages to the user about the locking
problems.
Sample Statements
SLOCK employee
SLOCK employee
The first SLOCK statement requests a lock on the entire table employee. The second
statement requests a lock on the records in the employee table that meet the WHERE
criteria. If one of the records cannot be locked, the status$ function returns a value
greater than zero, indicating partial success.
NOTE:
276
Remember, the # symbol is short for the table name followed by a
period. #emp_job_code could also have been written
employee.emp_job_code. Either the # symbol or the table name must
be used because emp_job_code is a database name.
SWITCH
SWITCH expression BEGIN ((CASE constant: | DEFAULT:) +
statement_list) + END ;
constant
A valid ACCELL/IDS constant. The constant can be of any of the valid ACCELL/IDS
types: NUMERIC, FLOAT, AMOUNT, BOOL, STRING, DATE, or TIME.
statement_list
A series of ACCELL/IDS statements.
A SWITCH statement usually appears as follows:
SWITCH expression
BEGIN
CASE constant:
statement_list
CASE constant:
statement_list
.
.
.
DEFAULT:
statement_list
END
When ACCELL/IDS encounters a SWITCH statement, it evaluates the expression
following SWITCH and compares it to all of the constants following the CASE
keywords. When the value matches, the statement list corresponding to that case
executes. If there is no match, the statement_list following DEFAULT executes. Each
case must be unique.
When using SWITCH, do not make any assumptions about the order in which the
switch value and constants are compared: there is no fixed comparison order.
There can be only one DEFAULT in a SWITCH. The DEFAULT may appear anywhere
in the body of the SWITCH. When you want to use a single statement_list in more
than one case, you may use more than one CASE and constant combination in front
of the statement_list. This produces a SWITCH statement with the following form:
277
SWITCH expression
BEGIN
.
.
.
CASE constant:
CASE constant:
statement_list . .
END
The following flowchart illustrates the execution sequence of the SWITCH statement:
SWITCH
EXPRESSION
MATCHES
EVALUATE
EXPRESSION
AND FIND
MATCHING
CASE
EXPRESSION
MATCHES NO
EXPRESSION
MATCHES
DO THE
STATEMENTS
FOR
FIRST CASE
DO THE
STATEMENTS
FOR
SECOND CASE
DO THE
STATEMENTS
FOR
DEFAULT CASE
CONTINUE
TO NEXT
STATEMENT
Figure 53. SWITCH statement execution sequence
278
Sample Statement
SWITCH ship_code
BEGIN
CASE 'U':
SET exp_ship_code
CASE 'P':
SET exp_ship_code
CASE 'A':
SET exp_ship_code
DEFAULT:
SET exp_ship_code
END
TO 'UPS'
TO 'Parcel Post'
TO 'Air Express'
TO 'Unspecified'
The SWITCH statement above tests an abbreviated shipping code (ship_code) and
sets the variable exp_ship_code to an appropriate expanded shipping code.
UNLOCK
UNLOCK table_name [WHERE logical_expression];
logical_expression
Any ACCELL/IDS expression that evaluates to TRUE or FALSE. When the
WHERE clause appears, ACCELL/IDS evaluates this expression for every record
in the table. ACCELL/IDS unlocks a record only when logical_expression is TRUE.
table_name
The name of the table to be UNLOCKed or the table containing the records to be
UNLOCKed.
The UNLOCK statement unlocks selected records and tables locked by previous
statements in the current transaction. Only those tables or records that have not been
exclusive locked (XLOCKed) are unlocked. All other records or tables remain locked
until the current transaction ends.
The WHERE option, when used, identifies the set of records to unlock; the set may be
empty. ACCELL/IDS evaluates the logical expression for each record in the table.
When the expression is TRUE, the record is unlocked. When there is no WHERE
clause, the statement requests that the entire table be unlocked.
Unlocking records that are already unlocked is not an error. It is good programming
practice to unlock any records or tables no longer required. This frees database
resources for other applications.
279
You can use the system function status$ to test the results of an UNLOCK statement.
Sample Statements
UNLOCK employee
UNLOCK employee
The first UNLOCK statement unlocks the entire table employee. The second
statement unlocks the records in the employee table that have an employee job code
(emp_job_code) equal to “Rep”. The # symbol is short for the table name followed by
a period. Either the # symbol or the table name must be used because emp_job_code
is a database name. #emp_job_code could also have been written
employee.emp_job_code.
UPDATE CURRENT RECORD;
UPDATE table_name
SET db_field_name_list TO expression_list
WHERE logical_expression;
db_field_name_list
A list of database field names separated by commas. The target variable
names must be preceded by the table name and a period or the symbol #. The
target variables are assigned the values in expression_list. The first variable is
given the first value in the expression list, the second variable is given the
second value in the list, and so on.
expression_list
A list of ACCELL/IDS expressions. Each expression is evaluated and the
resulting value is assigned to the corresponding variable. The expressions
must be assignment-compatible with the variables.
table_name
The table containing the records to be updated.
UPDATE CURRENT RECORD writes the current record to the database using the
values of the current record's fields. UPDATE CURRENT RECORD should be used
carefully because it does not cause execution of any of the Update Language
sections.
280
The second form of the UPDATE statement updates the fields of the selected record.
When a WHERE clause is used, the statement goes through a series of steps:
•
A record, selected by the WHERE clause, is read.
•
The values in the expression list are assigned to the variables in the database
field name list (db_field_name_list). The first value in the expression list is
assigned to the first database field, the second value in the expression list is
assigned to the second database field, and so on until the ends of the lists are
reached.
•
The updated record is written to the database.
The sequence is performed for every record that meets the WHERE criteria. If the
WHERE clause identifies an empty set, no action is taken.
Expression list values and database fields must be assignment compatible.
To test the results of an UPDATE statement, use the status$ function.
Using the AFA unique option
When a field uses the AFA unique option, ACCELL/IDS generates a unique field
value after the Add is completed. Thus, immediately following a CLEAR TO ADD
command, the field using the AFA unique contains only the unique offset value. After
completing the Add with the ADD/UPDATE command or with the UPDATE CURRENT
RECORD statement, the field contains the generated unique value.
For example, suppose there is a numeric field called anum in the database table part.
The AFA description for anum is:
anum: (unique+100)
To add a new record to the part table, first press CLEAR TO ADD A unique offset
value of 100 appears in the anum field on the part form. Press ADD/UPDATE to save
this new record; the anum field is updated and the generated unique value is
displayed in the anum field. For instance, if there were currently three records in the
part table (anum values 100, 101, 102), the new anum value would now display as
103.
281
Unique values are not always assigned in sequential order; deleted numbers may be
reused.
Sample Statement
UPDATE employee
SET #emp_department TO 'SALES'
This UPDATE statement retrieves each record in the table employee that has a job
code equal to REP. As each record is read, the department code field
(emp_department) is set equal to SALES and the record is written back to the
database. The # symbol is a quick way of indicating the table name followed by a
period. #emp_job_code could also have been written employee.emp_job_code.
Either the # symbol or the table name must be used because emp_job_code is a
database field.
WHILE
WHILE logical_expression statement
logical_expression
Any ACCELL/IDS expression that evaluates to TRUE or FALSE. The
statement is performed as long as the expression is TRUE.
statement
Any ACCELL/IDS statement, including a statement block.
The WHILE statement repeatedly executes a statement. First, ACCELL/IDS evaluates
logical_expression. If TRUE, statement is executed and ACCELL/IDS
re-evaluates the logical_expression. This continues until
logical_expression becomes FALSE. The following flowchart illustrates
the execution sequence of the WHILE statement:
282
WHILE
IS
LOGICAL
EXPRESSION
TRUE?
NO
YES
DO THE
STATEMENT
OR BLOCK
AFTER THE
WORD THEN
Figure 54. Execution sequence of WHILE statement
Sample Statements
SET index TO 1
WHILE index < 100
BEGIN
DISPLAY index
REFRESH SCREEN
SET index TO index + 1
END
SET index TO 100
WHILE index < 100
BEGIN
DISPLAY index
REFRESH SCREEN
SET index TO index + 1
END
283
The first WHILE loop displays the numbers 1 to 99 in the current screen field. The
second WHILE loop would not be executed because the initial value of the index is not
less than 100.
WRITE PIPELINE
WRITE PIPELINE variable expression_list;
expression_list
One or more ACCELL/IDS expressions separated by commas.
variable
A standard ACCELL/IDS variable containing the identifier of an open pipeline.
Writes the elements of the expression list to the pipeline identified by the variable.
The information is written as a stream of ASCII characters separated by the standard
separator character. ACCELL/IDS automatically inserts separator characters between
the expressions, and appends a newline (/n). The separator character is usually a
vertical bar (|), although it can be changed by assigning a different value to the
environment variable SEPARATOR.
The application must be written in such a way as to write the information in the correct
format for the programs in the pipeline. WRITE PIPELINE does not perform any
implicit formatting.
Use the RPT data format whenever possible. This consists of a vertical bar (|) as a
field separator and a newline character () as a record terminator. See Chapter 9.5,
Pipelines, for more information about using pipelines.
To test the results of a WRITE PIPELINE statement, use the status$ function.
Sample Statement
WRITE PIPELINE $pipe_one
emp_first_name, emp_last_name,
emp_job_language
The statement above writes the employee's first name, last name, and job language
to the pipeline identified by $pipe_one. The information is written out in a standard
RPT format with fields separated by vertical bars (supplied by ACCELL/IDS) and a
newline marking the end of the record.
284
XLOCK
XLOCK table_name [WHERE logical_expression];
logical_expression
Any ACCELL/IDS expression that evaluates to TRUE or FALSE. A record is
XLOCKed only when logical_expression is TRUE. When the WHERE clause is
used, ACCELL/IDS evaluates this expression for every record in the table.
table_name
The name of the table to be XLOCKed or the table containing the records to be
XLOCKed.
The XLOCK statement protects selected records and tables. An XLOCK is an
exclusive lock: only the transaction that locked the table or record may use it. Other
transactions may neither read nor change the table or record.
WHERE identifies the set of records to lock; the set may be empty. When there is no
WHERE clause, the statement requests a lock on the entire table.
If one of the records in the set cannot be locked, the status$ function returns a value
greater than zero, indicating partial success. All locked records are automatically
unlocked at the end of the current transaction.
Locking statements affect only other users of the database. An application can read
and modify any records it has locked.
Execution of the XLOCK statement does not guarantee that the record or table is
locked. The statement generates a request for an exclusive lock on the object. If the
request cannot be granted, ACCELL/IDS generates an error message. Such an error
usually indicates that another transaction (application) is holding a conflicting lock.
You can use the system function status$ to test the results of an XLOCK statement.
You can write your application so it attempts a lock several times if an XLOCK fails. If,
after repeated attempts, the lock still fails, it is best to start the transaction over and
release all locks. This prevents a deadlock with another application over the database.
Be sure your application provides appropriate messages to the user about the locking
problems.
See Chapter 8.1, under Locking Specifications, for a description of ACCELL/DBMS–
ACCELL/Manager interaction.
285
286
Chapter 9: Advanced application
design
9.1 ACCELL/IDS files
Several advanced features for experienced developers are available in ACCELL/IDS:
command level operation, control of user access, in-line C functions, pipelines, and
transaction control and locking. This section explains these features and
demonstrates how to use them in applications.
Command level operation provides a way of running ACCELL/IDS directly from the
operating system prompt, rather than from the ACCELL/Environment menus.
If you are planning to use ACCELL/IDS solely from the Environment, you may want to
skip Chapter 9.1, ACCELL/IDS Files, and Chapter 9.3, ACCELL/IDS Command Level
Development, and look at the parts on environment variables, user functions,
pipelines, transaction control and locking, and application optimization.
To use ACCELL/IDS from the operating system prompt level, you should understand
the ACCELL/IDS file structure and how it works.
Types of ACCELL/IDS files
ACCELL/IDS creates several types of files. Each file type is used at a different stage
of application development or processing.
An ACCELL/IDS file name is followed by a dot and a two- or three-letter suffix
indicating its type. The file name is usually the same as the form or application the file
is part of. For example, fcompany.fq contains the screen file (.fq) for the company form
(company).
287
.fq and .aq files
These are the Standard form (.fq) and Master Application form (.aq) screen files
created by the ACCELL/Generator. They store a form's trim, screen field definitions,
and other characteristics specified in the ACCELL/Generator.
Each form has its own .fq or .aq file. The ACCELL/Environment automatically creates
the .aq file for the Master Application form and gives it the same name as the
application.
The ACCELL/IDS ASQ2Q utility also generates .fq files.
.fs and .as files
The .fs and .as files are form source Language files that contain Language scripts for
Standard and Master Application forms. The Environment automatically creates the
.as file for the Master Application form. You create .fs files for your application using
your system editor.
Regardless of what name you give to .fs files, the Environment automatically assigns
a file name to the file consisting of the form name and a .fs extension.
.sy, .cd, and .io files
The .sy, .cd, and .io files are optionally produced by the ACCELL/IDS Compiler
(ACPL), when you use the -s, -c, and -p options, respectively.
The .sy file contains the list of symbols used in the form. The .cd file shows the code
produced by the ACCELL/IDS Compiler. And the .io file contains the output of the C
preprocessor.
.fo and .ao files
The .fo and .ao files are form object files for Standard and Master Application forms.
They are compiled versions of .fs and .as files produced by the ACCELL/IDS Compiler
(ACPL).
288
.fa files
The .fa file is a form archive file. Form archives contain executable images–with the
compiled object code–of each form in an application, and are used by the manager at
runtime.
The Environment puts all forms for each application into a single archive, although
you can include more than one archive in an application when working at the
command level.
The ACCELL/IDS Combiner/Archiver (ACMB) produces form archive files. The
Combiner/Archiver takes each .fq file in the application, combines it with the
corresponding .fo file if one exists, and archives the results in a .fa file.
.al files
The .al file is the application load map file produced by linking the application. The
Manager uses this file to control execution of the application. The file contains
information that lets the Manager find the needed files. .al files are produced by the
Linker (ALNK).
.hlp files
The .hlp files are trim archive files that store Field Help forms. The ACCELL/
Generator (AGEN) creates and manages these files. The manager uses these files at
runtime.
The ACCELL/IDS ASQ2H utility also generates .hlp files.
ACCELL/IDS file processing
Once you design the forms and create the Language scripts, the ACCELL/IDS
Development Environment processes forms and scripts to create the files used during
application execution. The illustration that follows shows how this process works:
Advanced application design
289
.fs and .as files created
with system editor
ACCELL/IDS
SmartlinkTM
Compiler
(ACPL)
ACCELL/IDS
SmartlinkTM
Generator
(AGEN)
.fo and
.ao files
.fq and .aq files
created with
ACCELL/IDS Generator
.hlp files
ACCELL/IDS
Combiner
Archiver
(ACMB)
.fa
.fa
.fa
.fa
ACCELL/IDS
Linker
Loader
(ALNK)
Figure 55. File processing
290
The .fs and .as files are run through the ACCELL/IDS Smartlinkt Compiler to create
.fo and .ao files, respectively. .fq and .aq files are then combined with .fo and .ao files
by the ACCELL/IDS Combiner/Archiver to create .fa files. Finally, the ACCELL/IDS
Linker reads all the .fa files and creates one .al file.
A single option on the ACCELL/Environment Application/Form Operation menu,
Compile/Integrate Forms & Language, performs this entire operation. (See Chapter 3 for
more information on the Environment.) For this option to work, you must be sure to
follow the Environment conventions if you create files outside of the Environment:
Place all files in one directory–.fs and .fq pairs with the same name, .as and .aq pairs
with the same name, only one .fa file, and .hlp files.
How ACCELL/IDS uses files when running applications
When an application runs, the Manager uses the .fa and .hlp files and the single .al
file to run the application:
.fa
.fa
.fa
.fa
.fa
ACCELL/Manager (AMGR)
Figure 56. Use of ACCELL/IDS files at runtime
291
Recall that the .al file contains information on the location of each form's executable
image. When you run an application, ACCELL/IDS uses the .al, .fa, and .hlp files to
locate the forms and display them in the proper sequence.
Environment variables required by ACCELL/IDS
The list below shows the environment variables that must be set in order to run
ACCELL/IDS. A check (4) under "Developing" following the variable indicates a
variable needed for application development. A check under "Running"
indicates a variable that must be set in order to run an application. For exact
information on how to set these variables, see Chapter 9.2, Environment
Variables.
Required environment variables
Environment variable
292
Developing
Running
ACLENV
✔
ACLPATH
✔
DBPATH
✔
✔
PATH
✔
✔
TERM
✔
✔
TEMCAP
✔
✔
UNICAP
✔
✔
UNFIY
✔
✔
9.2 Environment variables
The standard operating system shell gives you a convenient way of setting up
parameters that can be accessed by shell scripts and programs. These parameters
are called environment variables.
Environment variables take the form:
name=value
where both name and value are arbitrary strings.
An example of an environment variable is PATH. PATH is used by the operating
system to determine which directories to search to locate programs. The default value
for PATH is :/bin:/usr/bin. Using the default value, the shell would search for programs
only in the current directory, /bin, and /usr/bin.
How to set environment variables
Suppose you put your ACCELL/IDS release into /usr/ACCELL/IDS. You would then
want to add /usr/ACCELL/bin to your PATH list.
Assuming you are using the Bourne shell, you would enter:
PATH=:/bin:/usr/bin:/usr/ACCELL/bin
or
PATH=$PATH:/usr/ACCELL/bin
where $PATH substitutes the current value of the variable PATH.
If you want this new PATH to take effect in subshells, you must export the variable.
This is done by entering:
export PATH
If you are using the C shell (csh) you can set environment variables and export them
using the following syntax:
293
setenv variable_name value
For example:
setenv PATH $PATH:/usr/accell/bin
Using environment variables
To enable ACCELL/IDS to process correctly using a default directory structure, you
only need to set the TERM environment variable.
If you set only the TERM variable, you must be in your database directory, where the
files file.db, unify.db, and *.idx are located, when you run ACCELL/IDS.
If you want to start up ACCELL/IDS from any directory, while still using the default
directory structure, you must also set DBPATH. DBPATH should be set to the
database directory containing the files file.db, unify.db, and *.idx.
The startup shell script, ACCELL/IDS, will automatically set the following environment
variables to their default setting:
Environment variable Startup default
BUDEV
the device specified by the installation procedures
DBPATH
the current directory
PATH
appends the location of the ACCELL/IDS system bin directory, as
specificied by the installation procedures, to $PATH
TERMCAP
the temcap file located in $UNIFY
UNIFY
the location of the ACCELL/IDS system lib directory as specified by the
installation procedures
To allow for a non-default directory structure, or a non-standard backup device,
system editor, or ACCELL/IDS system file location, you should set the appropriate
environment variables from the basic environment variables list. See the subsection,
Basic Environment Variables.
Environment variable setting commands can be added to your .profile or .login file to
have the variables set and exported automatically when you log in. Refer to profile
and login in your operating system documentation for further information.
294
As an application developer, be sure the end user has the appropriate variables set or
has an easy method of setting them; for example, a shell script. By setting all the
necessary environment variables correctly and using a standard directory structure,
users can run an ACCELL/IDS application without knowledge of how the operating
system works.
NOTE:
The manual sections in the following environment variable descriptions
refer to the ACCELL/IDS DBMS Developer's Reference Manual.
Basic environment variables
The following is the basic set of environment variables that should be defined to run
applications.
ACLEN V
Pathname to the root application development directory. This directory contains all
your individual application directories. ACLENV only needs to be set if you use a
directory structure other than the ACCELL/IDS default.
If DBPATH has been set, the default value for ACLENV is:
$DBPATH/../aclenv
otherwise, ACLENV is set to:
./../aclenv
DBPATH
The directory where your application database files are located. This includes the
files file.db, unify.db, and all .idx files. If you set DBPATH, you can access the
database from any directory.
When you set the DBPATH variable, all the above files must be located in the
indicated directory, or ACCELL/IDS will not find them. If DBPATH is not set, all the
above files are assumed to be in the current directory.
EDIT
The name of a text editor or word processor. The default setting is the UC Berkeley
vi editor. If you don't have the vi editor, or if you have something else you like better,
you can reset EDIT.
The EDIT variable is used by Create or Modify Help Documentation (section 12.4),
Edit SQL or RPT Command Scripts (section 12.5), Edit ACCELL/Language Scripts,
and SQL Extensions (Chapter 16.3) when editing queries. (Chapter numbers refer
to the DBMS Developer's Reference Manual.)
295
PATH
contain the directory where the ACCELL/IDS system programs are located. In
addition, it can contain the directory where your application programs are located, if
you want to execute them from somewhere other than the current directory. The
standard PATH is set to :/bin:/usr/bin.
For example, if you installed your ACCELL/IDS release system files in the directory:
/usr/ACCELL/bin
you would probably want to set PATH to:
$PATH:/usr/accell/bin
TERM
The type of your terminal, as defined in your termcap file. There is no default value,
so this variable must be set for your terminal to work properly.
TERMCAP
The pathname of the termcap file. This file tells ACCELL/IDS how your terminal
works. The termcap file supplied in the ACCELL/IDS Release has many additional
video attributes defined that are not included in the standard operating system
release. You should use the ACCELL/IDS Release termcap file when running
ACCELL/IDS.
The default setting for TERMCAP is /etc/termcap.
UNIFY
The location of the ACCELL/IDS system lib directory. If it is not set to the right
directory, or if it is set to null, ACCELL/IDS cannot locate the DBMS .q files,
ACCELL/IDS message and help archives, Development Environment forms and
help, or the ACCELL/IDS libraries.
For example, if ACCELL/IDS is installed in the /usr/ACCELL/IDS directory, UNIFY
should be set to:
/usr/accell/lib
296
Advanced environment variables
The following are additional environment variables that may be required for your
application to run properly.
ACLPATH
Pathname of the directory containing the .fa and .hlp forms archives. You only need to
set this variable if your application's .fa, .hlp, and .al files are located in a different
directory than the one you are running ACCELL/IDS from.
If the specified file name does not begin with ./ or /, ACLPATH is appended to the
beginning of the Help Form Name, Help Archive, and File Name file, as defined on the
Generator Form Definition and Advanced Field Definition forms.
The ACCELL/IDS Menu Handler sets ACLPATH for you using:
$ACLENV/application_name
if ACLENV is set, or:
$DBPATH/../aclenv/application_name
if DBPATH is set, or by default:
./../application_name
where application_name is the name of the application.
The ACLPATH variable is also used by the ACCELL/IDS linker, ALNK. If ALNK is run
from the operating system shell, ACLPATH will default to the current directory if not
set.
ACPLPP
The name of the preprocessor. The default is /lib/cpp, the UNIFY preprocessor. If
needed, you can specify the name of a custom preprocessor.
AGENINIT
A string used to set parameters for the ACCELL/Manager. Use the following syntax to
set the AGENINIT variable:
AGENINIT="param=val[param=val ...]"
where param refers to a parameter name, and val is a valid parameter value. Each
parameter=value setting is a single string with no embedded spaces. A single space
between each set of parameter settings separates them in the AGENINIT string, as
shown in the following example:
"error_file=AGEN.err num_windows=10"
Use AGENINIT to set the following parameters:
error_file
pathname of the error file used by the Generator.
heap_size
size of heap memory used by the Generator.
selected_set_dir
pathname of the directory where the temporary files for selected sets are kept.
num_windows
maximum number of windows that can be active at a time.
297
stack_block_size
size of the blocks used in the stack.
The following table summarizes the defaults for the AGENINIT parameters:
Parameter
Default
Maximum
Minimum
error_file
/dev/null
n/a
n/a
heap_size
8k
512k bytes
247 bytes
selected_set_dir
/usr/tmp
n/a
n/a
num_windows
128 windows
1024
2
stack_block_size
4k each
1MB
256 bytes
The default heap_size setting is sufficient for all but the largest applications. You need
not worry about this setting until you are notified of a heap memory problem by
ACCELL/IDS.
If ACCELL/IDS tells you a heap memory problem exists, increase the heap size in 2k
increments until the error no longer exists.
The num_windows parameter can be set to any integer between 1 and 1024.
The stack_block_size parameter has a valid range of 256 bytes to 1 Megabyte. This
parameter setting can be important because each code section for a form must fit in
one stack block. This value will need to be increased for very large and complex
forms.
AMGRINIT
A string used to set parameters for the ACCELL/Manager. Use the following syntax to
set the AMGRINIT variable:
AMGRINIT="param=val[param=val ...]"
where param refers to a parameter name, and val is a valid parameter value. Each
parameter=value setting is a single string with no embedded spaces. A single space
between each set of parameter settings separates them in the AMGRINIT string, as
shown in the following example:
"border_dsp=no fnkey_dsp=no"
Use AMGRINIT to set the following parameters:
error_file
pathname of the error file used by the Manager
explicit_mode
the mode used for string field searches
heap_size
size of heap memory
selected_set_dir
directory that all the selected record sets go to
num_windows
maximum number of windows that can be active at a time
298
stack_block_size
size of the blocks used in the stack
sort_mem_size
maximum amount of memory to use during sorting
init_mem_size
initial process size
list_scan
flag to report database access method used to select/find a record set
mode_dsp
the mode display, on or off
fnkey_dsp
function key display, on or off
fyi_dsp
FYI line display, on or off
border_dsp
the application area window border display, on or off
mode_row
placement of the mode display
fnkey_row
placement of the function key display
fyi_row
placement of the FYI line display
open_archives
maximum number of open form archive files
The following table summarizes the defaults for the AMGRINIT parameters:
Parameter
Default
Maximum
Minimum
error_file
/dev/null
n/a
n/a
explicit_mode
no
n/a
n/a
heap_size
8k
<192k bytes
247 bytes
selected_set_dir
/usr/tmp
n/a
n/a
num_windows
128 windows
1024
2
stack_block_size
4k each
1MB
256 bytes
sort_mem_size
24k less 1 byte
1024
4k
init_mem_size
65,535
none
0
list_scan
no
n/a
n/a
border_dsp
yes
n/a
n/a
fnkey_dsp
yes
n/a
n/a
fyi_dsp
yes
n/a
n/a
299
mode_dsp
yes
n/a
n/a
fnkey_row
max_row
max_row
min_row
fyi_row
max_row -1
max_row
min_row
mode_row
min_row
max_row
min_row
open_archives
5
1
The explict_mode parameter is used to toggle between default and explicit modes of
performing searches on string fields. See Chapter 4, Find Mode, for information on
explicit and default searches.
The default heap_size setting is sufficient for all but the largest applications. You need
not worry about this setting until you are notified of a heap memory problem by
ACCELL/IDS.
If ACCELL/IDS tells you a heap memory problem exists, increase the heap size in 2k
increments until the error no longer exists.
The num_windows parameter can be set to any integer between 1 and 1024.
The stack_block_size parameter has a valid range of 256 bytes to 1 Megabyte. This
parameter setting can be important because each code section for a form must fit in
one stack block. This value will need to be increased for very large and complex
forms.
If you increase the size of the sort memory, sort_mem_size, data sorts process in
memory instead of on disk. Data sorts are faster when processed in memory.
However, increasing sort_mem_size will also increase your process size.
The parameter, init_mem_size, is used to define the initial process size for the
application. By increasing the process memory size, you may be able to obtain better
performance and a faster startup.
If the list_scan parameter is set to YES, the ACCELL/Manager will write data access
information to the Manager error file (error_file). The Manager will report the access
method (random, hash, explicit relationship, B-tree, or buffered sequential access)
used each time a set of records is selected.
Information on the database scan type is added to the error_file when the database
statements select, insert, update, set, and delete process and when the Manager FIND
command processes. As an example, you might use the following setting:
AMGRINIT="list_scan=yes error_file=ACCELL/IDS.err"
To specify the mode, function key, FYI line displays, and window border displays, use
the syntax shown in the following table:
300
Option
Syntax
Turn border or line
display on or off
{ border_dsp | fnkey_dsp | fyi_dsp | mode_dsp }
= { yes | no }
Position line
display at top of
screen
{ fnkey_row | fyi_row | more_row } = min_row [+1 | +2]
{ fnkey_row | fyi_row | more_row } = max_row [-1 | -2]
Position line
display at bottom of
screen
In the preceding table, min_row refers to the top record–the default position for the
mode line display. max_row is the bottom record–the default position for the function
key line display.
When you change mode line, function key line, and FYI line display positions, the
application area shifts up or down to adjust for the changes.
NOTE:
If you change any one of the three locations, you must change all three
locations.
For example (on the Bourne shell), to place the FYI message line at the top, the status
(mode) on the line below, and turn the function key line and border displays off, set
AMGRINIT with the following command:
AMGRINIT="border_dsp=no fnkey_dsp=no
fyi_row=min_row mode_row=min_row+1
fnkey_row=max_row"
APPMAP
The name of the application map file. This file is used to access multiple databases in
ACCELL/IDS. Refer to Chapter 9.3 under Accessing Multiple databases for more
information on using multiple databases and the APPMAP variable.
BINEDIT
The name of a binary editor. This editor is used in ENTER for editing binary fields. To
edit a binary field in ENTER, press CTRL D when the cursor is on the position
reserved for a binary field.
BUBLK
The size in bytes of a block used by the backup device. If this variable is not set, the
block size defaults to 4096 bytes.
BUDEV
The complete path name of the system backup device. This is a diskette drive, a
cartridge tape drive, or a 9-track tape drive. There is no default value, so this must be
set for any program that uses the backup device. It is usually set up by the installation
procedure.
BUDRVR
The name of a custom program to be used as the backup device filter. The specified
program is a custom version of the BUDRVR program. BUDRVR reads from and
writes to BUDEV, a file. If the BUDRVR environment variable is not set, the default
backup device filter is BUDRVR.
301
BUTAPESZ
The number of blocks that fit on one tape or diskette on the backup device specified in
BUDEV. To ensure a successful backup, this variable must be set. If this variable is not
set or is set to zero (0), blocks are read or written until the read or write cannot be
completed.
The budb utility uses the BUTAPESZ environment variable to indicate the number of
blocks to be written to the media. If BUTAPESZ is not set, budb relies on the operating
system to correctly handle the end-of-media condition; however, the end-of-media
condition is often not handled correctly by the operating system. In these cases, you
must specify BUTAPESZ in the environment; otherwise, the backup may not be
recoverable.
Always set BUTAPESZ to a value smaller than the number of blocks that can fit on the
media. Allow approximately 100 extra 1k blocks of unused media or 25 extra 4k
blocks. To determine the approximate number of blocks that can fit on the backup
media and to verify correct handling of the end-of-media condition, take the following
steps:
1.
Back up the database without setting BUTAPESZ. BUDB will display the
number of blocks on the media while backing up the database. Make a
note of how many blocks were written on each tape.
2.
Set the BUTAPESZ environment variable to approximately 25 less than
the number of blocks written to the first tape.
For example, if budb indicates that 45654 blocks were written to the first
tape, you would set BUTAPESZ to 45629.
3.
Back up the database again using the smaller BUTAPESZ. This is a
safety copy of your database.
4.
Unset the BUTAPESZ environment variable; you can unset BUTAPESZ
by logging out.
5.
Because restoring the database is a risky operation on a production
system, you may wish to make additional backups prior to running redb
by using tar or cpio for regular files and dd for raw partition database
volumes.
6.
Using redb, try to restore the backup created in step 1.
If this fails, your operating system may not correctly handle end of tape.
You should then use the media created in step 3 to restore your
database, and always remember to set BUTAPESZ before starting your
backup.
An alternate technique is to calculate and set BUTAPESZ for all backups.
It can be calculated by taking the capacity of the tape in kilobytes and
dividing by 4; reduce this number by 5 to 10 percent to allow for
interrecord gaps. Then assign this number to BUTAPESZ.
CURR
302
Controls the display format for amounts on DBMS ENTER screens and in RPT. Up to
seven characters can be entered to define the currency amount format. The first three
characters are required and the last four characters are optional. Each character in
the CURR specification is described as follows:
The first character in the string is reserved for the thousands separator.
Enter a comma (,), a period (.), or a blank ( ). This character is required.
The second character is the decimal point. Enter a period (.) or a comma
(,). This character is required.
The third character indicates the truncation position, the number of
decimal digits that appear after the decimal point. Enter either a two (2) or
a zero (0). If you enter a zero, neither the decimal digits nor the decimal
point display. This character is required.
The fourth character indicates the position of the currency symbol in the
amount display. Use a greater than symbol (>) to display the currency
symbol on the right. Use a less than symbol (<) to display the currency
symbol on the left. This character is optional, and need only appear if a
currency symbol is specified.
The fifth, six, and seventh characters are reserved for the currency
symbol. The currency symbol can be any one, two, or three characters
except numeric characters. For example, the currency symbol can be $,
DM, or xxx. These characters are optional.
The default currency format is comma-separated thousands, with a decimal point and
two decimal digits, as follows:
CURR=",.2"
For example, if CURR is not set, 100 thousand dollars displays as follows:
100,000.00
And if CURR is set to:
" ,2>xxx"
then 100 thousand dollars displays as:
100000,00xxx
DATETP
The format in which to accept and display dates from January 1, 1900 to December
31, 2077. This environment variable can also be used to change all brackets that
display on menus and screen forms to parentheses.
The default date format, AM, is MM/DD/YY, where M stands for month, D stands for
day, and Y stands for year. The default format also displays brackets on menus and
screen forms. The valid values for DATETP are the following:
AM
American format, MM/DD/YY and brackets.
EU
European format, DD/MM/YY and parentheses.
IN
International format, YY/MM /DD and parentheses.
US
United States format, MM/DD/YY and parentheses.
303
If you need to format long dates (four-digit year) from October 1, 1752 through
December 31, 9999, use the LDATEFMT environment variable, also described in this
section.
DBNAME
The name of the ACCELL/IDS database file. This variable need not be set if the
default file name file.db is suitable for your system.
If you want to set the database file to something other than the default, you must use
an ordinary file name, not a pathname. Therefore, the value of DBNAME cannot
contain slashes (/).
The DBMS uses the following logic to determine the name of the database file:
If unify.db is given to opendb()
then unify.db is used,
else if DBNAME is set to a valid file name,
then the file named in DBNAME is used,
else file.db is used.
If the database filename is not unify.db, the name of the raw database file is always
obtained by adding an "r" to the end of the database file name.
DEFSIZE
IF the databse filename is ...
THEN the raw database
filename is ...
file.db
file.dbr
dbfile
dbfile
The default process size–used when NSEGS is 0– to calculate the shared memory
attach address. The default value for DEFSIZE is 1MB. You can set DEFSIZE to
another multiple of 1MB if you don't want the DBMS to use 1MB.
You must set DEFSIZE to a multiple of 1MB, as shown in the following example, which
sets DEFSIZE to 1MB:
DEFSIZE=1048576
NOTE:
If DEFSIZE is set too high, you may run into a range of addresses used
by the stack.
For more information on how NSEGS and DEFSIZE, see the description of NSEGS.
DELIMFLD
Whether or not the current field on a form is highlighted in reverse video. The possible
values are:
Y or y
N or n
The value of Y (yes) means that the current field on a form will be highlighted. If
DELIMFLD is set to N (no), the current field on a form will not be highlighted while
ACCELL/IDS waits for input. If DELIMFLD is not set, default value for this variable is Y.
This variable is useful when you want to reduce the amount of I/O performed by the
ACCELL/IDS application at runtime.
FLTFMT
304
Format for printing floating point numbers. The default for FLTFMT is %g. You can
specify any other valid conversion character for C float variables, for example: %17.9f,
%.2f, or %.0f.
For more information about formatting, see display in Chapter 8.
LDATEFMT
The format in which long dates are accepted and displayed. If LDATEFMT is not set,
the default format is MM/DD/YY. The valid settings for this variable are the following:
DD/MM/YY or DD-MM-YY or DD.MM.YY
DD/MM/YYYY
MM/DD/YY
MM/DD/YYYY
YY/MM/DD
YYYY/MM/DD
DD/AAA/YY
DD/AAA/YYYY
where D (day), M (month), Y (year), and A (alphabetic month) can be entered in
upper or lower case.
The separator can be a slash (/), dash (-), or period (.).
To specify that days or months less than 10 display as 1 - 9 rather than 01 - 09, you
can enter D and M. For example, if LDATEFMT is set as follows:
LDATEFMT=M/D/YYYY
the first day of June displays as
6/1/1999
rather than 06/01/1999.
To specify a three-letter month, as in "MAY" or "DEC", use the DD/AAA/YY or DD/AAA/
YYYY form.
LMPROMO
The maximum number of locks allowed on a database object before it is promoted to
a like lock of the next higher object, for example, from a record to a table. The Lock
Manager uses LMPROMO to conserve memory.
If conflicting locks exist, lock promotion may be postponed until a subsequent lock
call.
The default maximum number of locks is 50. You can set LMPROMO to a number
from 1 up to the maximum integer value allowed by your computer system. A larger
setting increases multi-user access ability, but uses more memory. A smaller setting
decreases multi-user access ability, but uses memory better.
The Lock Manager promotes the locks if there are no conflicting locks. A premature
promotion causes other transactions to be locked out.
NOTE:
LOCKDIR
LMPROMO is only used when a Lock Manager shared memory partition
is created. If LMPROMO is changed, you must remove the shared
memory partition and restart the application.
The named pipes directory. The nonshared version of the ACCELL/IDS Lock Manager
creates special files called named pipes (or sockets) for inter-process communication.
Named pipes have .p suffixes.
305
If LOCKDIR is set, the named pipes are stored in the specified directory. Otherwise,
the named pipes are stored in the default directory, /usr/tmp. If /usr/tmp does not exist,
the named pipes are stored in the directory specified in DBPATH.
NOTE:
MAXOPNBTS
LOCKDIR is only used if there is no shared memory.
The maximum number of B-tree files that may be open at one time. If MAXOPNBTS is
not set, the default maximum number of open B-trees is 5.
When MAXOPNBTS is set, the size of MAXOPNBTS affects B-tree performance in
the following ways:
NOUMSGS
l
If MAXOPNBTS is set to a number greater than 5, B-tree index searches
may be faster than at the default. However, less file descriptors are
available for user programs.
l
If MAXOPNBTS is set to a number less than 5, B-tree searches are
slower because ACCELL/IDS must repeatedly open B-trees. However,
more file descriptors are available for user programs.
Controls the display of progress messages while data dictionary report programs run.
The progress messages include: Selecting, Sorting, and Formatting.
If the variable NOUMSGS is set to T (True), the progress messages do not display.
The default value for NOUMSGS is F (False).
The following programs display progress messages when NOUMSGS is set to F:
NSEGS
System name
Menu description
lemp
Print individual privileges
lexec
Print list of programs
lgrp
Print group privileges
lmenu
Print menus
schlist
Print database design
sfrep
Print screens
Indicates whether ACCELL/IDS can use a system default attach address for shared
memory.
The default, if NSEGS is not set, is zero (0).
When NSEGS is set to one (1), the DBMS uses the default system attach address.
You should set NSEGS to one if the system provides the same default address for all
processes attaching to a segment.
When NSEGS is set to zero (0), the DBMS calculates an attach address based on the
DEFSIZE environment variable value, as outlined below:
306
l
The DBMS calculates an attach address that is comfortably outside the
process data space. In this case, shared memory segments are attached
relative to the process size.
l
If the DBMS cannot attach at the calculated attach address, it steps down
through memory, in even steps, until it can attach.
NOTE:
Because it steps down in even decrements, the DBMS attaches at the
original default, if it can find no other attach address.
l
The DBMS looks in the DEFSIZE environment variable for a default
process size to use in calculating the attach address.
The default value for DEFSIZE is 1MB. You can set DEFSIZE to another
multiple of 1MB if you don't want the DBMS to use 1MB. For more
information on DEFSIZE, see the DEFSIZE description.
PAGELN
The page length for LST and RPT reports. The default value is 66. This value is also
used for the following data dictionary and database reports:
Print Database Design
Print Menus
Print Group Privileges
Print Individual Privileges
Print List of Programs
Print, Display database Statistics
Print, Display B-Tree Statistics
SEPARATOR
The field separator for RPT, SQL, DBLOAD, and BMTOFF. The default separator is
the pipe symbol (|). (BMTOFF is the program that interfaces ENTER to RPT.)
SHMID
The ID number to be used for the shared memory segment dedicated to the ACCELL/
IDS Lock Manager. The default setting for SHMID is 4903.
Set SHMID if you want to run an application that uses another database that has a
different memory segment.
NOTE:
All applications that use the same database must use the same ID
number.
SHMMAX
The maximum size allowed for the shared memory segment. Set this variable to a size
appropriate for your operating system. At the first call to the Lock Manager, the Lock
Manager tries to create a shared memory segment of the requested size. If the
requested size is larger than the size allowed by the operating system, the Lock
Manager cycles down in 2 K-byte jumps until it successfully creates a shared memory
segment. The default setting for SHMMAX is 32767.
SHMMIN
The minimum shared memory segment size. The Lock Manager uses SHMMIN with
SHMMAX. The Lock Manager must be able to find a shared memory segment greater
than or equal to the setting of SHMMIN for ACCELL/IDS to run. The default setting for
SHMMIN is 4096 bytes.
307
SPOOLER
The name of your system's line printer spooler. You should set this to the standard
operating system spooler, usually lpr.
If you want, you can also specify options for the spooler. For example, if you want to
get a mail message after the file is printed, you can set SPOOLER as follows:
SPOOLER="lpr -m"
The SPOOLER environment variable must be set so that output can be piped or
redirected to $SPOOLER using one of the following syntax forms:
cat filename | $SPOOLER
$SPOOLER < filename
$SPOOLER filename1 filename2
SQLPMEM
The amount of memory used during an SQL sort to hold projected fields (the fields in
the select clause that are not part of the order by clause). If this variable is set too low
and the sort needs more memory for projected fields, the overflow is stored in a disk
file. This slows down sort performance. For more information about setting internal
SQL table sizes, see SQL Extensions, Chapter 16.3 of the DBMS Developer's
Reference Manual.
SQLSMEM
The amount of memory used during an SQL sort to hold the sort keys. If this variable
is set too low and the sort needs more room for the sort keys, the overflow is stored in
a disk file. This slows down sort performance. For more information about setting
internal SQL table sizes, see SQL Extensions, Chapter 16.3 of the DBMS Developer's
Reference Manual.
TIMEM
The maximum amount of memory used by SQL as a buffer for a temporary index. If
this variable is set too low and the temporary index requires more memory, the
overflow is stored in up to two disk files. If the temporary index uses less memory than
specified in TIMEM, only the smaller amount is used.
For more information about setting TIMEM and other internal SQL table sizes, see
Chapter 16.3 of the DBMS Developer's Reference Manual.
UCFLAGS
Specifies the C compiler options to be used by ucc to generate an object file during
program loading. If UCFLAGS is not set, the default is -c. For more information about
ucc, see Chapter 1.5 of the Direct HLI Programmer's Manual.
UCNAME
Specifies the name of the C language compiler to be used during program loading
and by ucc. If UCNAME is not set, the default C compiler is cc. For more information
about ucc, see Chapter 1.5 of the Direct HLI Programmer's Manual.
UNICAP
The complete pathname of the ACCELL/IDS unicap file; for example, /usr/lib/
myunicap. If UNICAP is not set, the default location of this file is in $UNIFY/unicap.
This file is used by Paint Screen Forms (Chapter 13.2 of the DBMS Developer's
Reference Manual) and the Menu Handler, Generator, and Manager to determine how
the keyboard works. The unicap file is described in Chapter 6.2 of the ACCELL/IDS
DBMS Developer's Reference Manual and in Appendix B of the ACCELL/IDS
Developer's Reference Manual.
308
UNIFYTMP
The pathname of the temporary directory used by the DBMS.
The default value for UNIFYTMP is the directory /tmp. You can reset the temporary
directory to any existing directory on your system, provided the following:
l
The directory pathname begins with root (/)
l
The directory path name does not exceed 17 characters
l
The temporary directory must also have read, write, and execute
permission for all users
The following is an example of a UNIFYTMP setting:
UNIFYTMP=/usr/mytmp
UUACL
The current user's access level for the current program. The access level value is a
string of length 2, "00" to "15" that indicates the user's access level for the current
program. This value is defined in Add or Modify Individual Privileges. .
UUID
The ID of the current user as defined in Add or Modify Individual Privileges. This
variable is set by the Menu Handler so user programs can reference it.
VOLPATH
The complete pathname for your database volumes. When VOLPATH is not set, all
your databasevb volumes are assumed to be in the current directory or in $DBPATH, if
DBPATH is set.
NOTE:
Do not set the VOLPATH environment variable unless the database
volumes directory is different than the application database directory.
309
9.3 ACCELL/IDS command level development
A series of special commands lets you develop and run applications directly from the
operating system prompt. This way of working with ACCELL/IDS provides an
alternative to selecting options from ACCELL/Environment menus. Command level
operation requires a greater understanding of the operating system and is not
recommended for inexperienced developers.
To work effectively at the system level, you should be in the same directory as the
application. Generally, an application's forms, Language scripts, and other files reside
in a single directory. This directory has the same name as the application; it is an
immediate subdirectory of the directory named in the ACLENV environment variable.
The following illustration shows this relationship:
ACLPATH
Application_name
Form 1
Application_name
Form 2
Application_name
Form 3
Form n
Figure 57. Application directory structure
In working at the operating system level, you only need to use the form name after
commands–each command automatically appends the appropriate file suffix to the
310
form name. You can override the automatic suffixes by using the -i option with the
command. The -i option forces the command to take the file name exactly as you type
it in.
The sections that follow describe the ACCELL/IDS operating system commands and
tell you how to use the commands to create and run an application.
In the syntax for operating system commands, the following conventions are used:
bold words
Command key words. Enter them exactly as they are printed.
italicized words
Words that you provide; for example, variable names, table names, or
constants.
[]
Square brackets that enclose optional elements. The square brackets
are not part of the command.
Entering the ACCELL/Generator from the operating system
To enter the ACCELL/Generator from the operating system, type the AGEN
command, followed by the name of the form you want to create or edit. For example,
the following command lets you create or edit the form sample:
AGEN sample
The general form of the AGEN command is:
AGEN [–a] [–i] filename
If you are going to edit or create a Master Application form, you must use the -a flag to
indicate a Master Application form. When the -a and -i flags are both used, they must
be combined in the single sequence -ai.
One of the advantages of using the Generator at the operating system level is being
able to specify a list of forms to edit. For example, if you type the following command,
the Generator will edit, in turn, tutorial.aq, fcompany.fq, forders.fq, and fleads.fq:
AGEN -a tutorial fcompany forders fleads
311
If you use a list of forms that includes a Master Application form, the Master
Application file must appear first.
When you have finished editing each form, press ADD/UPDATE to save it; then press
PREV FORM to edit the next form.
Compiling language scripts from the operating system
The ACCELL/Environment automatically takes care of compiling Language scripts
when it processes an application. If you want to compile a script from the operating
system, use the ACPL command.
ACPL uses the operating system preprocessor cpp. Through the use of cpp, ACPL
allows you to use macros to define whole sections of code, or leave debug statements
in your code without having to comment them out.
The command has the following format:
ACPL [–a] [–i] [–p] [–s] [–c] [–Idir] filename
You must use the –a option to compile a Master Application form Language script (an
.as file).
You may also specify a list of files to compile. Like the Generator, if you use the –a
option, the first file in the list must be the Master Application script. When both the –a
and –i flags are used, they must be combined in the single sequence –ai.
Use the –p option to view the preprocessed file. When using –p, the line numbers
contained in the compiler error messages can be misleading. Whenever a compilation
error occurs, the intermediate file is left in the directory, form_name.io.
The –s option produces symbol table output in a .sy file. The –c option produces an
ACCELL/IDS machine assembly code file.
The –Idir option searches for #include files in dir, where dir is the name a directory.
For example:
ACPL -I$UNIFY/../include empform
312
compiles the Language script empform.fs. Note that there is no space before the
directory name.
The preprocessor could be used as follows:
#include "example.h"
form example
before form
#ifdef DEBUG
display 'debug mode' for fyi_message wait
#endif
if not(open_message_file$(MESFILE))
then
display OPENERR for fyi_message wait
where example.h contains:
#define DEBUG
#define MESFILE '/usr/application/messages'
#define OPENER 'There was an error opening the error file'
NOTE:
If you have an ANSII–standard C preprocessor, any line that begins
with a pound sign (#) is interpreted as a compiler control statement.
Therefore, be careful not to place ACCELL/IDS statements beginning
with # at the beginning of a line.
In the following example the highlighted line will cause a compilation
error:
form saleschart
target_table company
field co_sales.rep
when field changes
set $rcp_name to select
#rep_name from employee
where #rep_key = $co_sales_rep
To correct this problem, you can reformat the statement or insert a blank comment at
the beginning of the line, for example:
/* */
#rep_name from employee
313
Combining forms and language scripts from the operating system
Forms and Language scripts can be combined using the Combiner/Integrator
command, ACMB. The ACMB command takes two arguments: the archive name
(usually the same as the application), and the form name. The general form of the
command is
ACMB [–i] archive_name [–a] form_name
When both the –a and –i flags are used, they must be combined in the single
sequence –ai.
Linking files from the operating system
When you process files in the Environment, linking is done automatically. To link a file
from the operating system, use the ALNK command. The command word ALNK is
followed by the archive name and the application name. Generally, the archive name
and the application name are the same. In this case, you can type:
ALNK application_name
If the archive and the application have different names, you type:
ALNK archive_name application_name
The ALNK command has the following format:
ALNK [–i] archive_name application_name [–i] [.al_filename]
Building ACCELL/IDS executables with make
When you compile Language scripts from the operating system, you need to keep
track of which steps to run whenever you change a given script.
For example, if you change a Standard form script, the .fs script must be recompiled
(with ACPL). The new script and its .fq form file must be recombined (with ACMB) into
an archive, and the new archive must be relinked into the application (with ALNK).
314
If you modify a Standard form, the .fq form file and its .fs script must be recombined
(with ACMB), and the new archive must be relinked into the application (with ALNK).
If you modify the Master Application script, the .as script must be recompiled (with the
–a option of ACPL). The new script and its .aq form file must be recombined (with the
–a option of ACMB), and the application must be relinked.
You can have ACCELL/IDS automatically figure out which files to compile, combine,
and link by using the operating system make utility. The make utility reads the file
makefile to see which files need to be reprocessed (compiled, combined, and linked)
when a given file changes. The makefile contains the list of commands needed to
reprocess the modified files.
The syntax of the makefile is complex. So to save you from having to create your own
makefile, ACCELL/IDS provides the makeamake command. The makeamake
command makes a makefile which contains commands to compile (ACPL) and
archive (ACMB) each of the form and script files, and link the application (ALNK).
NOTE:
You should run makeamake after creating all forms and scripts for an
application. Rerun makeamake when you add or delete forms and
scripts. Running makeamake ensures that the makefile is up to date.
The makefile is then used to relink an application after changes have been made to
form and language files outside of the ACCELL/IDS Development Environment.
These changes normally occur when form files–.fq and .aq files–are modified using
the ACCELL/IDS AGEN program, and when Language files–.fs and .as files–are
modified using a system editor. For a description of the AGEN command, see
Entering the ACCELL/ Generator From the Operating System.
To generate a makefile, take the following steps:
1. Change to the application directory where you want to generate a makefile.
If you have the ACLENV environment variable set, enter:
cd $ACLENV/application_dir
If you do not have the ACLENV environment variable set but are using the
default ACCELL/IDS directory structure, you can enter:
cd ../aclenv/application_dir
315
where application_dir is the application directory containing your form and
Language files.
2. Remove any existing makefile.
rm makefile
3. Generate a new makefile for your application:
makeamake
To use a makefile to relink your application, run the operating system utility,
make:
make
The make program runs using the makefile. This utility compares the dates of
all files listed in the makefile to see if any files have been modified since the
previous relink. Depending on the actual files you have modified, make
automatically runs the appropriate processing steps.
Moving an application
Generally, an ACCELL/IDS application's files reside in a single directory. This
directory is usually a subdirectory of the directory pointed to by the environment
variable ACLENV.
Moving an application to another directory involves copying the application's files
(forms and Language scripts) to the other directory.
When an application is moved, remember that successfully running the application
requires two environment variables to be set in the user's login directory: DBPATH
must be set to the pathname for the database, and ACLPATH must be set to the
pathname to the directory containing the copied ACCELL/IDS application files.
If the application is moved to another computer, make sure that any scripts or forms
referenced by the application but residing in other directories are also transferred.
You can make a copy of an application that can be executed but cannot be modified:
copy all of the .hlp, .fa, and .al files. The application will run without the .fq and .fs files,
but it cannot be modified without these source files.
316
Renaming an application
It is possible to rename your application after it has been added to the ACCELL/
Environment. To rename your application, take the following steps:
1. Move to your application root directory. The application root directory is the
directory containing your individual application directories. The ACCELL/IDS
environment variable ACLENV should point to the root directory.
If you have the ACLENV environment variable set, enter:
cd $ACLENV
If you do not have the ACLENV environment variable set but are using the
default ACCELL/IDS directory structure, you can enter:
cd .../aclenv
where .../ is the default ACCELL/IDS directory.
2. Move the old application directory to a new name.
mv old_appl_name new_appl_name
where old_appl_name is the name of the application you want to rename, and
new_appl_name is the new name you want to assign to the application.
3. Change directory to the new application directory.
cd new_appl_name
4. Move the old application's .as, .al, and .aq files to similar files using the new
application name.
mv old_appl_name.as new_appl_name.as
mv old_appl_name.al new_appl_name.al
mv old_appl_name.aq new_appl_name.aq
5. Edit the .as file and change all occurrences of the old application name to the
new application name. This includes all form and file names.
6. Start ACCELL/IDS.
accell
7. Enter the ACCELL/Environment (option 1 of the ACCELL/IDS Main Menu).
8. Display the Application List form by pressing ZOOM at the Current Application
form.
317
9. Delete the old application entry by moving the cursor to entry on the
Application List and pressing DELETE RECORD. Answer YES to the Delete
confirmation prompt
10. Add the new application to the Application List by pressing CLEAR TO ADD to
move to a blank line on the form, entering the new application name and
description, and pressing ADD/UPDATE to save the entry.
11. Change the application name in the Master Application Form by selecting the
Edit ACCELL/Generator Form option from the Application/Form Operation
menu for the new_application_name form. Change the Form Name on the
Form Definition form to the new_application_name.
12. Compile and integrate the new application by pressing selecting the Compile,
Integrate option from the Application/Form Operation menu.
13. .Move to the directory the old application's .ao and .fa files located in and
remove the files to save space.
rm old_application_name.ao
rm old_application_name.fa
Registering ACCELL/IDS applications
You can register an ACCELL/IDS application with the ACCELL/IDS Menu Handler
using the AREG program from a command line. Normally, application registration and
deregistration is done for you automatically by the ACCELL/Environment. When you
add a new application to the Application List, the Environment runs the AREG
program.
You can also run AREG manually. The syntax for AREG is:
AREG [–a | –d] application_name
where the –a option is used when you want to add (register) an application, and the –
d option is used when you want to delete (deregister) an application. You must choose
only one of these two options.
For example, if you want to delete an application called accounts without starting up
the ACCELL/Environment, you can use the AREG command from the operating
system shell:
318
AREG –d accounts
Accessing multiple databases
It is possible to access several ACCELL/IDS applications, each with its own database,
from the ACCELL/IDS Menu Handler. The ACCELL/IDS Menu Handler is the software
system that controls the display and selection of menu items. When you start up
ACCELL/IDS, it is the Menu Handler that displays the ACCELL/IDS Main Menu and
waits for you to select a menu item. From within the Menu Handler, you can select
your own applications and the ACCELL/IDS Manager can determine which database
to use for the application.
NOTE:
In order to access multiple databases, you must select your
applications from within the ACCELL/IDS Menu Handler. The multiple
databases feature will not work when you start up the application
directly by running the ACCELL/IDS Manager from the operating
system shell.
The multiple database feature assumes that all the runtime applications are
registered with the ACCELL/IDS Menu Handler in the master application. The master
application is not usually a complete ACCELL/IDS application. It may contain forms
but has no actual application data (no file.db file). The master application serves as
the runtime environment for the runtime applications.
Suppose you have four applications: appA, appB, appC, and appD and that these
applications have already been developed from within the ACCELL/IDS Development
Environment. Figure 58 shows the directory structure of the development
319
environment.
u sr
d ev ela pp s
a pp A
ac len v
db
a pp licatio n
files
d atab ase
file s
a pp D
ap pB
ap pC
aclen v
a cle nv
a cle nv
db
a pp licatio n
file s
a pplica tion
file s
da ta ba se
files
ap plication
files
ap psd b
d atab ase
files
Figure 58.. Development directory structure
Each of the four applications appA, appB, appC, and appD, is in a subdirectory of the
/usr/develapps directory. The application files are in the application's aclenv directory
and the database files are in its db directory. Application appA has its application files
(.fs , .fq , .aq , .as , .hlp , .al , and .fa files) in the /usr/develapps/appA/aclenv directory
and its database files (.db and .idx files) in the /usr/develapps/appA/db directory.
Application appD has its application files in the /usr/develapps/appD/aclenv directory
and its database files in the /usr/develapps/appD/db directory. Applications appB and
appC have their application files in the directories /usr/develapps/appB/aclenv and /
usr/develapps/appC/aclenv respectively. These two applications, however, share a
common database. Their database files are stored in the directory /usr/develapps/
appsdb.
Figure 59 shows a runtime directory structure for the development structure in Figure
58 runtime directory structure contains the master application and the runtime files for
each application. In Figure 59 directory /usr/runtimeapps contains the master
application. The /usr/develapps directory has the same structure as shown in
Figure 58.
320
us r
ru ntim e ap ps
aclen v
ap pA
ap pB
dev ela pp s
db
ap pC
a ppA ap pB ap pC ap pD a pps db
ap pD
a ppA .a l app B .al a pp C .a l app D .a l
a ppA .fa app B .fa a pp C .fa app D .fa
Figure 59. Example runtime directory structure
To create the runtime directory structure, you need to create a master application
directory. The master application is the application where each of the runtime
applications is registered. In order for the Menu Handler and the Manager to be able
to access the applications, the runtime files for all these applications must be stored
under the master application directory.
Each application is stored in a subdirectory of the master application's aclenv
directory. These subdirectories contain the runtime files for each of the applications.
The ACCELL/IDS application runtime files are the application load map (the .al file)
and the application archive file (the .fa file). All other ACCELL/IDS application files
(.fq , .fs, .aq, .as, and .hlp files ) remain in the application's development directory.
Only the .fa and .al files are actually needed at application runtime.
In Figure 59, the directory /usr/runtimeapps contains the master application. The
master application directory stores the four applications: appA, appB, appC, and
appD. The master application database is in /usr/runtimeapps/db. The /usr/
runtimeapps/aclenv directory contains the runtime application subdirectories. Each of
the subdirectories: appA, appB, appC, and appD contains the runtime files for a single
application. databases for the runtime applications remain in the development
directory structure.
To set up a master application, follow the steps below:
321
1. .Create a subdirectory for the master application.
cd appsroot
mkdir runtime
where appsroot is the absolute pathname of where you want to store your
master application and runtime is the name of the master application directory.
For the example in Figure 59 would be the /usr directory and runtime would be
the runtimeapps directory.
2.
Create the db subdirectory for the master application's database.
mkdir db
where db is the name of the master application's database directory.
For the example in Figure 59, db would be the db directory.
3.
Create a aclenv subdirectory to store the runtime applications.
cd runtime
mkdir aclenv
where runtime is the name of the master application directory.
4. Create an application subdirectory in the aclenv directory of the master
application. This subdirectory should have the same name as the runtime
application.
cd aclenv
mkdir appname
where appname is the name of the runtime application.
5. Into this new runtime subdirectory, copy only the .al and .fa files for the runtime
application from the development structure.
cp old/appname/aclenv/appname.al appname
cp old/appname/aclenv/appname.fa appname
where old is the absolute pathname of the application's development files and
appname is the name of the runtime application.
For the example in Figure 59 old would be the pathname /usr/develapps and
appname would be either appA, appB, appC or appD. The cp commands for
copying the runtime files for appA would be:
322
cp /usr/develapps/appA/aclenv/appA.al appA
cp /usr/develapps/appA/aclenv/appA.fa appA
6. Set the DBPATH environment variable to point to the master application
database.
For the example in Figure 59, DBPATH would be set to:
/usr/runtimeapps/db
7.
Register the runtime application with the master application. To register an
application, use the ACCELL/IDS utility AREG. For more information on using
AREG, refer to Chapter 9.3 under Registering ACCELL/IDS Applications.
AREG –a appname
where appname is the name of the runtime application.
NOTE:
If your application has not been registered with the
ACCELL/IDS Menu Handler, you will not be able to
select it from within the ACCELL/IDS Menu Handler.
8. You can also create menu items for your applications on the ACCELL/IDS
Menu Handler menus. These menu items will enable you to select your
applications by typing the menu item number at a menu's SELECTION:
prompt.
You create menu items with the ACCELL/DBMS program, Add, Modify or
Delete Menus (menumnt). You can enter the menumnt program directly from
the ACCELL/IDS Menu Handler by typing "menumnt" at the SELECTION:
prompt. To add the menu item entries, refer to Chapter 12.2, Add, Modify or
Delete Menus of the ACCELL/DBMS Reference Manual for information on
using the menumnt program.
9. Repeat Steps 4 through 8 for each of the runtime applications.
For the example in Figure 59 you would perform these steps four times: once
for each of the runtime applications, appA, appB, appC, and appD.
In addition to the application's .al and .fa files, the Manager also needs to know where
to find the data for each runtime application. The location of an application's database
is given by the ACCELL/IDS environment variable DBPATH. If all runtime applications
used a single database, then the DBPATH variable could be set to this pathname and
the Manager could always find the application data. However, when the runtime
323
applications access different databases, the Manager must have some way of setting
DBPATH to point to the correct database for each application.
For the Manager to know which database to access for each application, you create a
file called an application map. This file associates an application with its
corresponding database. The application map file contains two fields of information.
The first field is the absolute pathname of the application's load map: its .al file. The
second field is the absolute pathname of the directory containing the application's
database. The two fields must be separated by a single space (1 blank character).
10. Create the application map file.
For the example in Figure 59, suppose the application map for the directory
structure above was stored in the file /usr/runtimeapps/aclenv/appsmap. The
appsmap file would contain the following application information:
/usr/runtimeapps/aclenv/appA/appA.al
/usr/runtimeapps/aclenv/appB/appB.al
/usr/runtimeapps/aclenv/appC/appC.al
/usr/runtimeapps/aclenv/appD/appD.al
/usr/develapps/appA/db
/usr/develapps/appsdb
/usr/develapps/appsdb
/usr/develapps/appD/db
Once you have created the application map, you must set the ACCELL/IDS
environment variable APPMAP. The variable should be set to the absolute pathname
of your application map file. When you select an application from within the ACCELL/
IDS Menu Handler, the Menu Handler checks the ACCELL/IDS master application
database for the application name. If the Menu Handler finds that the selected item is
an existing ACCELL/IDS application, it sends the name of the application's load map
file (its .al file) to the ACCELL/IDS Manager.
11. Set the ACCELL/IDS environment variable APPMAP to the absolute
pathname of the application map file.
For the example in Figure 59, APPMAP would be set to:
/usr/runtimeapps/aclenv/appsmap
When it receives the name of the load map, the Manager first checks for the APPMAP
environment variable. If APPMAP is set, the Manager opens the indicated application
map file. If, for any reason, the Manager is unable to open this file, the Manager exits
and execution is returned to the Menu Handler. You will only receive an error message
indicating that this open has failed if you have initialized the ACCELL/IDS Manager
with the name of an error file. Refer to the description of the environment variable
324
AMGRINIT in Chapter 9.2 under Advanced Environment Variables for information on
initializing the Manager and naming an error file.
If the Manager successfully opens the application map, it searches the first field of the
file for the load map name that matches the name sent by the Menu Handler. If it finds
this name, the Manager then gets the pathname from the entry's second field. This
pathname is the location of the application's database directory. The Manager sets
the DBPATH environment variable to this database path. The Manager will only reset
the DBPATH variable if:
•
the APPMAP variable is set to a valid application map file.
•
the name of the application's load map is found in the application map file.
If either of these conditions is not met, the DBPATH variable remains set to its initial
value.
Once you have registered the runtime applications, created the application map, and
set the APPMAP variable, you can access any of the runtime applications from within
the Menu Handler without having to manually reset DBPATH. To run a runtime
application from the master application, follow the steps below.
12. Return to the master application directory. Make sure that the required
ACCELL/IDS environment variables are set to the master application.
cd runtime
where runtime is the name of the master application directory.
For the example in Figure 59, runtime would be /usr/runtimeapps:
13. Start up the ACCELL/IDS Menu Handler on the master application.
ACCELL
14. Select your application from within the ACCELL/IDS Menu Handler. The Menu
Handler will send your application name to the ACCELL/IDS Manager and the
Manager will set DBPATH and begin execution of your application.
Suppose you started up ACCELL/IDS and selected application appB from the Main
Menu. The Menu Handler sends the name application's load map file, appB.al, down
to the ACCELL/IDS Manager. The Manager checks the status of the APPMAP
variable. Since APPMAP is set, the Manager opens the indicated application map, /
usr/runtimeapps/aclenv/appsmap, and searches for the application load map file that
325
matches the name sent from the Menu Handler. There is an entry for appB on line 2
of the application map file so the Manager would reset the DBPATH environment
variable to the pathname contained in the second field of this matching entry. DBPATH
would be set to /usr/develapps/appsdb and the application appB would access data
from the /usr/develapps/appsdb database. As the final step, the Manager would start
up the execution of appB.
Setting up end user access to an application
An ACCELL/IDS application can be started either from a command line or from a
DBMS menu. The Environment automatically includes applications in the DBMS
menus when they are added.
The command line has the following form:
AMGR path_to_application access_code
where path_to_application is a standard operating system pathname to the .al file of
the application.
The access_code is a number from 0 to 15 that determines which of the four
operations, Find, Add, Update, and Delete, are allowed. The default is 15.
The following table shows the relationship between the number and the allowed
operations. A check (4) indicates the operation is allowed; a minus (–) indicates a
disallowed operation.
Access code Find
326
Add
Update
Delete
1
–
–
–
–
2
–
–
–
✔
3
–
–
✔
–
5
–
✔
–
–
5
–
✔
–
✔
6
–
✔
✔
–
7
–
✔
✔
✔
8
✔
–
–
–
Access code Find
Add
Update
Delete
9
✔
–
–
✔
10
✔
–
✔
–
11
✔
–
✔
✔
12
✔
✔
–
–
13
✔
✔
–
✔
14
✔
✔
✔
–
15
✔
✔
✔
✔
The following is a command line for the tutorial application allowing all operations
except delete:
AMGR /usr/bin/tutorial/tutorial.al 11
Listing form defaults and help text
ACCELL/IDS includes five utility programs to list the form and field attributes of your
Master Application, Standard, and Help forms:
FRMDOC
Q2ASC
H2ASC
ASC2Q
ASC2H
FRMDOC
The FRMDOC program takes a Standard or Master Application form and produces a
listing of the form's characteristics on your terminal. The program is useful when
generating documentation for the application forms.
FRMDOC produces a multiple-page report about the specified screen form. The
report contains the following information:
•
the form's relation to the database
•
whether the form is single-occurrence or multi-occurrence
327
•
the associated help forms
•
the form's screen coordinates and size
•
the form image (as it appears in the ACCELL/Generator)
•
the field coordinates and video attributes
•
the trim coordinates and video attributes
•
the field definitions
•
any advanced field definitions
•
FYI messages
The syntax for FRMDOC is as follows:
FRMDOC [–a] [–i] form_name [> ascii_file]
where form_name is the name of the form you want information for. This form_name
does not need to include the .fq or .aq form file suffix. The –a option is needed to see
the form documentation for the Master Application form. The –i option overrides the
default file extensions and uses the file name exactly as entered.
When both options are used, they must be combined in a single sequence: –ai. notice
that the output for this program is sent to standard output. Output can be redirected to
a file.
Q2ASC
The program Q2ASC takes a Standard or Master Application form and produces an
ASCII file. The file includes a listing of all form and field characteristics and their
settings as well as a reproduction of the form. The syntax for Q2ASC is as follows:
Q2ASC [–a] [–i] form_file [> ascii_file]
If you are going to convert a Master Application screen file, you must use the –a flag.
Q2ASC will add either a .fq or .aq to the form file as appropriate. The –i option
overrides the default file extensions and uses the file name exactly as it is typed.
When the –a and –i flags are both used, they must be combined in the single
sequence –ai. Notice that the output is written to the standard output and can be
redirected to a file or printed on your terminal.
328
H2ASC
The program H2ASC takes a Help form archive and produces an ASCII file. The
syntax for H2ASC is as follows:
H2ASC [–a] [–i] help_archive [> ascii_file]
The –a and –i options work the same as they do for Q2ASC. Like Q2ASC, output from
H2ASC is written to the standard output and can be redirected to a file or listed on
your terminal.
ASC2Q AND ASC2H
ACCELL/IDS also includes two programs, ASC2Q and ASC2H to convert ASCII form
and help files back to form screen files and help archives. The syntax for the ASC2Q
and ASC2H programs is as follows:
ASC2Q [–a] [–i] form_file < ascii_file
ASC2H [–a] [–i] form_file < ascii_file
The –a and –i options have the same meaning as they have for Q2ASC and H2ASC.
The options apply to the resulting form file. Notice that input is taken from the
standard input and may be redirected.
Sometimes a corrupted form screen file can be restored by converting it to an ASCII
file and then converting it back.
329
9.4 User functions
ACCELL/IDS's user function facility allows you to add functions, written in C, to the
ACCELL/Language.
To add a user function, you perform three steps:
1. Write the function in C
2. Modify ACCELL/IDS's user function table and relink the ACCELL/Manager
3. Use the function in the Language script
The sections that follow describe how to write a sample function and provide detailed
information on writing user functions of all types. The first section demonstrates how a
function would be used in an application. The second and third sections discuss
writing the function in C and describe how to link a user function with the Manager.
User functions and applications
Suppose you wanted to write a boolean function namechk to verify the format of a
name typed in a field. The function returns TRUE if the name consists only of letters,
apostrophes, blanks, and hyphens. It returns FALSE if there are any other characters
in the name.
To use the function, you would first declare it at the beginning of a Language script as
follows:
EXTERN C BOOL FUNCTION namechk(sparm)
where sparm is a string parameter containing the name to check. This tells the
ACCELL/IDS compiler that the form uses the external C function namechk. The
function returns a boolean (BOOL) value, and has a single argument. The rest of the
Language script would appear after the function declaration.
Later in the script, you could use the declared function in the ON FIELD section to test
a name entered by the user. The section might appear as follows, assuming the input
is placed in the screen variable $sc_name_field:
330
FIELD sc_name_field
ON FIELD
INPUT;
IF (NOT namechk($sc_name_field)) THEN
BEGIN
DISPLAY
'Letters, blanks, apostrophes, hyphens only'
FOR FYI_MESSAGE WAIT;
RESTART ON FIELD;
END;
This section gets the name from the user, calls the boolean C function namechk to
test it, and, if the name is invalid (namechk returns FALSE), restarts the input.
A sample user function
The code for the user function namechk appears on the following page. The details of
passing arguments from ACCELL/IDS to a user C function appear in User Function
Conventions.
Notice that the sample function namechk has a single argument, $sc_name_field,
when used in the application. User functions may have up to 31 arguments.
Regardless of the number in the application, ACCELL/IDS passes only two
arguments to the C function itself: the number of arguments in the function invocation,
and an array of structures (AVAL structures described in chookincl.h) that contain
information about the arguments. In the sample function, these two arguments are
numargs and acclarg.
Also, notice that the function namechk includes a local declaration of an AVAL
structure, retval, to use for returning the function value. User functions may pass
values back to an application in two ways.
•
First, to return a value for the function, the user function declares a local AVAL
structure (retval) and calls the function chookrt to transmit the value. Using the
C return statement will not return the value in a way the application can
recognize.
•
The second way of passing values back to an application is through the
argument list. This method is described in EXTERN Statement Syntax and
Multiple Return Values.
331
namechk begins by defining some of the elements of the return value. Next, the
function checks to make sure the correct number and type of arguments were passed
to it. If there are problems with the arguments, the return value is set to FALSE (NO),
and the function halts and returns to the application.
If the arguments are correct, the function gets the string containing the name, checks
its format, and returns an appropriate value.
#include <include/chookincl.h>
/* Include the ACCELL/IDS user
function definitions */
#define YES 1
#define NO 0
namechk(numargs,acclarg)
int numargs;
/* Number of arguments from ACCELL/IDS */
AVAL acclarg[];
/* Array of AVAL structs containing
information about the arguments */
{
AVAL retval; /*Define an AVAL struct for the
returned value */
char *p;
int c;
retval.aknd = A_BOOL;
/* Set the return value
type to boolean */
retval.dfflg = YES;
/* Yes, the value is defined */
/* Make sure there is exactly one argument,
that it is defined, and that it is
a string argument. */
if(numargs <= 0 || numargs > 1 ||
acclarg[0].dfflg != YES
|| acclarg[0].aknd != A_STR) {
retval.aval.boval = NO; /* Set the return
value to FALSE*/
chookrt(&retval);
/* Pass the return value
to ACCELL/IDS */
return;
/* Leave the function */
}
else {
p = acclarg[0].aval.stval; /* Set local pointer
to string */
retval.aval.boval = YES; /* Set return value
to TRUE */
332
/* Loop until the end of the string is reached
or until an invalid character is found */
while(c = *p + + ) {
if(!isalpha(c) && c != ' ' && c != ''
&& c != '–') {
retval.aval.boval = NO; /* Invalid
character */
break;
}
}
chookrt(&retval); /* Return the value,
whatever it is */
return;
/* Return to the application */
}
}
Combining the application and the user function
There are two final steps that link the user function and ACCELL/IDS: making an entry
in the external function table file, and relinking the Manager. These steps are
described in the next two sections.
Modifying the user function table
ACCELL/IDS contains a file in the include directory called chooktb.c. This file contains
a table listing all of the external user functions. A listing of the file follows:
#include <include/chookincl.h>
/** REPLACE with your function declarations **/
extern int chook1();
/*** c-hook table global definition - MODIFY ***/
CHOOK chooktb[] =
{ /**** REPLACE with your functions here: ****/
/**** one-line for each function
****/
{ "chook1",chook1 },
333
};
/*** number of elements in chook table ***/
/*** DO NOT MODIFY ***/
int nhooks = (sizeof(chooktb)/sizeof(*chooktb));
To include a new function, make a copy of chooktb.c in your current directory. Then
use the system editor to add an extern statement for the function and to make an
entry in the array chooktb. For the function namechk, this would involve adding the
following line after the entry extern int chook1():
extern int namechk();
You would also add the following line after the line
{ "chook1",chook1 }:
{ "namechk", namechk }
Once the entries are made in the file, the last major step is to relink the manager. The
relinking process is described in the next section.
Relinking the manager
To make namechk available to an application, the function and the modified table
chooktb.c must be compiled. Then, the compiled function and table must be linked to
ACCELL/IDS to create a new ACCELL/IDS that includes the function.
The system C compiler is used to compile the function and the table. To compile
namechk.c and chooktb.c, use these two commands:
cc -c -I include_path pathname/namechk.c
cc -c pathname/chooktb.c
where pathname is the pathname of the directory where the function and its include
files are located. If the include files are located elsewhere, you must use the –I option
and specify the include directory pathname. For other usages of cc, see your
operating system manual.
334
The two object files in your directory, namechk.o and chooktb.o, need to be linked with
the Manager to form a new, custom Manager. Linking is done with amgr.ld. The
general form of the command to relink the Manager is:
amgr.ld custom_accell_name
function_object_files chooktb.o
For example, the object files namechk.o and chooktb.o can be linked with the
Manager to form a new Manager, amgr0986, with the following command:
amgr.ld amgr0986 namechk.o chooktb.o
The new Manager, amgr0986, could be executed by the following command:
amgr0986 application_name 15
See the ACCELL/IDS Command Level Development section for more information.
User function conventions
This section describes in detail how ACCELL/IDS and user functions pass information
back and forth. The chookincl.h Header File describes the file chookincl.h which
defines the structures and symbolic constants used in calling a user function. The
next subsection, The AVAL Structure, describes the AVAL structure, used to pass
values in and out of user functions. The subsection, EXTERN Statement Syntax and
Multiple Return Values describes the full EXTERN statement syntax along with a
method for passing multiple values back to an application.
The chookincl.h header file
The file chookincl.h must appear in a #include in your user function definition. This file
defines all of the elements involved in passing values to and from a user function. It
also defines a set of symbolic constants used to simplify writing functions. Specifically,
the file contains definitions of the following:
•
AVAL–the structure containing information about the type and value of an
argument
•
A union (aval) inside the AVAL structure used to hold the argument value
335
•
The symbolic constants A_INT, A_FLT, A_BOOL, A_STR, A_DATE, A_TIME,
and A_AMNT used to indicate the type of the variable in an AVAL structure
A description of each element follows.
The AVAL Structure
The AVAL structure is used both in passing arguments to a user function and in
passing values back to the application. If you look back at the sample function,
namechk, you will see that AVAL structures appear in two places.
First, the arguments passed to the function are contained in an array of AVAL
structures.
Second, because namechk passed a value back to the application, the returned value
was contained in an AVAL structure. The AVAL structure is defined in the file
chookincl.h as part of a typedef. This means that whenever you need an AVAL
structure, you can write something like the following:
AVAL retval;
The AVAL structure is defined as follows:
struct AVAL {
char aknd; /* ACCELL/IDS data type */
char dfflg; /* define flag: 1 if defined,
otherwise 0 */
union {
double amval; /* ACCELL/IDS AMOUNT value */
int
boval; /* ACCELL/IDS BOOLEAN value */
long
daval; /* ACCELL/IDS DATE value */
double flval; /* ACCELL/IDS FLOAT value */
long
inval; /* ACCELL/IDS INTEGER value */
char *stval; /* ACCELL/IDS STRING value */
long
tival; /* ACCELL/IDS TIME value */
struct align *alignval; /* Force alignment */
} aval;
}
NOTE:
336
The AVAL structure may change from one release to another. Make
sure you use the correct chookincl.h file.
Although at first glance the aval union looks like it contains eight different items, it will
in fact contain only a single value. A union, as you may recall, is a method C uses for
handling a value that may be of several different types. This means that the AVAL
structure contains only three things:
1. a variable aknd used to indicate the data type
2. a variable dfflg, set to 1 if the variable is defined and set to 0 if undefined
3. the actual value
The AVAL structure accounts for the way the values were returned in the name
checking function. Remember that when you want to gain access to an element of a
structure in C, you write the structure identifier followed by a period and the element
name. Thus, to tell the application that the returned value was a boolean value, the
symbolic constant A_BOOL was assigned to the aknd element of the return value:
retval.aknd = A_BOOL;
Placing the actual value inside the AVAL structure is slightly more complicated. To
assign the value, you use the structure name, a period, the name of the structure
element–this time the union aval–followed by a period, and then the identifier of the
variable in the union. In the name checking function, the following statement was used
to return a boolean value FALSE:
retval.aval.boval = NO;
If an integer value had been returned, the assignment statement would have been
almost the same, differing only in the element of the union used, as follows:
retval.aval.inval = int_result;
Returning Function Values
In order to use a value returned from a function, ACCELL/IDS has to process the
AVAL structure containing the value. Because of the need for processing, the
standard C return statement will not work. Instead, you use a special function,
chookrt.
Calling chookrt causes the structure passed to it to become the function return value.
In the name checking function, the call looked like this:
337
chookrt(&retval);
NOTE:
The function argument is the address of the structure (a pointer), not
the structure itself.
Symbolic Constants for Data Types
The file chookincl.h includes definitions of symbolic constants for the data types.
These constants should be used in testing and in making assignments to the data
type element, aknd, in the AVAL structure.
The constants and their meanings appear in the following table:
Constant
Meaning
A_INT
NUMERIC data
A_FLT
FLOAT data
A_BOOL
BOOL data
A_STR
STRING data
A_DATE
DATE data
A_TIME
TIME data
A_AMNT
AMOUNT data
EXTERN statement syntax and multiple return values
The EXTERN statement is used in the Language script to declare user functions the
script uses. The EXTERN statement's syntax is as follows:
EXTERN C (type_specifier | VOID) FUNCTION
function_name ([formal_parameter_list]);
The valid function type specifiers are NUMERIC, FLOAT, AMOUNT, BOOL, STRING,
DATE, and TIME. The function type specifies the type of value returned by the
function. If VOID is used instead of a type specifier, the function does not return a
value to the application.
The parameter list is optional and can be used to pass arguments to the function and
to set return values in the application. In order to set a value in the application through
338
the parameter list, the parameter to contain the value must be preceded by the
keyword RESULT.
Assignments made in a function to a RESULT parameter's AVAL structure change the
corresponding application variable's value when the function returns. Note that the
value of a variable passed as a RESULT parameter only changes after the function
returns. For example, if we had a function func1 that took one value and set two
values, we could declare it with the EXTERN statement below:
EXTERN C VOID FUNCTION
func1 ($x1, RESULT $x2, RESULT $x3);
The arguments would be passed as an array of three AVAL structures. The function
func1 would make assignments to the second and third elements of the array before
returning to the application. Because there is no function value returned, func1 would
not call the function chookrt.
Notes on writing user functions
ACCELL/IDS does not perform checks on the number or the type of function
arguments. Each function you write must check the number and the type of
arguments.
When returning a string through a RESULT parameter, you must avoid overwriting
memory beyond the end of the string. Always use the C function strlen to determine a
string's length before making an assignment to it.
Also, if a RESULT parameter is an undefined string, the user function must obtain
permanent storage for the string. This can be done by using a global or static variable,
or by calling the memory allocation function malloc.
Suppose you are returning a string in the second element of the argument list,
acclarg. The string has been built up in a temporary string, p. To return the string,
obtain the necessary storage from the operating system, copy the string into the
allocated area, and make the necessary assignment to the AVAL structure:
q = malloc(strlen(p)+1); /* allow one space
for the null */
strcpy(q,p);
acclarg[1].aval.stval = q;
339
Note that you would still need to set the other elements of the AVAL structure
acclarg[1] before returning from the function.
If you obtain storage through a call to malloc, you must be able to free the storage
when you are finished with it. Be sure to note and save the address.
340
9.5 Pipelines
The ACCELL/IDS pipeline feature lets you pass data from your application to an
external data file or to another program. Thus, you can use your ACCELL/IDS
applications with your current report generation programs without rewriting them.
To use a pipeline in a 4GL script, you follow these three steps:
•
Establish the pipeline with the CREATE PIPELINE statement.
•
Write the information to the pipeline using the WRITE PIPELINE statement.
•
Clear and close the pipeline with the CLOSE PIPELINE statement.
The following sections describe the syntax of pipeline statements and how output
data format is controlled.
Pipeline statement syntax
This section describes the syntax and the operation of each pipeline statement.
Statement descriptions are in the order that they would be used in an application. For
a description of each element of the pipeline statements, see Chapter 8.2, ACCELL/
IDS Statement Descriptions.
Square brackets ([ ]) indicate optional parts of the statements. They are not parts of
the statements.
Create pipeline
CREATE PIPELINE variable program_name_list
[OUTPUT [IS] string_expression];
This statement creates a pipeline to send information out of the application to a
program, a series of programs, or a file. When ACCELL/IDS executes the statement, it
creates a pipeline, stores an identifier in a variable, and transmits any data from a
corresponding WRITE PIPELINE statement to the programs in the list
(program_name_list). Optionally, ACCELL/IDS sends the information to a data file
identified by the string expression in the OUTPUT IS clause.
341
The variable containing the pipeline identifier must remain unchanged until the
pipeline is closed.
The programs in program_name_list are taken to represent a standard operating
system pipeline. That is, the output of the pipeline goes to the first program. The
output of the first program becomes the input to the second program, and so on. If
literal program names are used, they must be enclosed in single quotation marks (')
and separated by commas. For example, the statement that follows creates a pipeline
to send the data to RPT, the DBMS Report Generator, which would then send its
output to the line printer spooler (lpr):
CREATE PIPELINE $pipe_one 'RPT script -', 'lpr';
The characters script – following RPT are command line arguments for RPT. They tell
RPT that report formatting information appears in the file script and that all report data
comes from the standard input.
Alternatively, the program names may be stored in string variables. These variables
would simply be listed, separated by commas.
When the OUTPUT IS option is used, the string expression specifies a file to receive
the output from the final program in the pipeline. If the final program writes its output
to a file instead of to stdout, the file specified by OUTPUT IS will be empty.
Write pipeline
This statement writes the elements of expression_list to the pipeline identified by
variable. Each field is separated by the standard separator character, usually |. A
newline character () is appended to the expression_list.
For example, the statement below writes a numeric constant, a string constant, and a
form variable to the pipeline identified by $pipe_one:
WRITE PIPELINE $pipe_one 50,
'Standard Terms',form:variable;
342
If variable contained the string "Region 4", then the output to the pipeline would be as
follows:
50|Standard Terms|Region 4
The default separator character (|) may be changed by setting the environment
variable SEPARATOR. See the DBMS Developer's Reference Manual for more
information.
Close pipeline
CLOSE PIPELINE variable;
This statement closes the pipeline identified by the variable. Be sure to close all
pipelines before the application ends in order to avoid loss of data.
Controlling pipeline output format
The output from WRITE PIPELINE is a continuous ASCII stream. Output is only
broken up into lines when a newline character appears in the expression list or at the
end of a statement. Newline characters () must appear when using a pipeline to send
information to RPT.
RPT expects input in the form of records terminated by a newline with fields separated
by the standard separator character. Writing data in the correct format for pipeline
programs often involves using multiple WRITE statements and various flow of control
statements.
The table that follows lists the available escape sequences for writing non-printing
characters with WRITE PIPELINE statements. Other non-printing characters may be
written using the system function char_code_to_str$ in the WRITE PIPELINE
statement.
Escape Sequence
Result
\b
Backspace
\n
Newline
\r
Return (ASCII 13)
\t
Tab
343
9.6 Transaction control and locking
ACCELL/IDS applications may run on multi-user systems where more than one
person is using the same database. Because a database is shared among users,
some mechanism is necessary to prevent one user's operations from interfering with
another user's operations.
ACCELL/IDS prevents such interference by:
•
organizing database operations into transactions
•
providing locking mechanisms to transactions
In the ACCELL/Language, you can explicitly control certain aspects of the transaction:
•
initialize a form's transaction information
•
request transaction locks for database operations
•
handle transaction work (committing the transaction)
Each of these topics is described in this chapter.
ACCELL/IDS transaction management
ACCELL/IDS controls access to the database by organizing database operations into
transactions. A transaction is a set of database operations that must proceed
uninterrupted by others who want to access the database. Therefore, a transaction is
an atomic unit of work that operates on the database.
ACCELL/IDS transaction control allows you to define when a transaction starts. When
a new transaction starts, the current transaction ends and a new transaction begins.
By defining when a transaction begins and ends, you control which database
operations must always be performed as a unit.
In ACCELL/IDS, you control transactions on a form-by-form basis. The ACCELL/
Manager determines how to handle the current transaction when the Manager
receives the command to move to the application's Next form. The Manager receives
the "Next form" command in one of the following ways:
344
•
the application end user issues the NEXT FORM command
•
the NEXT ACTION IS NEXT FORM Language statement executes
NOTE:
In this chapter, the phrase "Next form" refers both to Next forms (from
Standard forms) and First forms (from a Master Application form)
unless explicitly indicated otherwise.
When the Manager receives the "Next form" command, it needs to know:
•
the name of the Next form to move to
•
the transaction level for this Next form
This information is contained in the form's Next form definitions.
Next Form definitions
If the form has only one Next form defined, the Manager obtains the name of the Next
form from this Next form definition. If the current form has several Next forms defined,
the Manager displays the Next Form menu and waits for the application end user to
select the desired Next form. If no Next forms are defined, the Manager displays an
error message and ignores the "Next form" command.
ACCELL/IDS Transaction levels
Once the Manager has the name of the Next form, it checks the Next form's
transaction level to determine how to control the current transaction. The Next form's
transaction level tells the Manager how to handle the current transaction when the
Next form begins execution.
When execution of the Next form begins, the transaction level can tell the Manager to:
•
start a new transaction (Start Tx)
•
continue the current transaction (Continue Tx)
•
restart a transaction (Restart Tx)
Each of these transaction levels affects when the current transaction ends.
Starting a transaction
345
The Start Transaction (Start Tx) transaction level tells the ACCELL/Manager to start a
new transaction when the associated Next form begins execution. All database
operations performed on the Next form are not part of the current transaction; they are
in a new transaction.
To begin a Next form at the Start Tx transaction level, the Manager:
•
commits the current transaction
•
releases all existing locks (SLOCKs and XLOCKs) held by the current
transaction
•
deactivates all active forms back to the Master Application form
•
activates the specified Next form
•
starts a new transaction with the specified Next form
•
begins execution of the specified Next form
All locks held by the previous transaction are released when Start Tx begins a new
transaction.
This transaction level clears all active forms back to the Master Application form. For
this reason, the Next form that has a transaction level of Start Tx is actually a First
form: it follows the Master Application form.
The Manager performs a Start Tx when it encounters:
•
a CHOOSE NEXT FORM statement with the transaction clause of:
or
STARTTXSET_CONSISTENCY
•
a CHOOSE NEXT FORM entry for the Next form with a transaction level
number of 3 (Start Tx at Record Consistency) or 4 (Start Tx at Set
Consistency)
If the Manager finds a CHOOSE NEXT FORM statement for the Next form, it uses the
transaction level in the CHOOSE NEXT FORM statement. Otherwise, the Manager
uses the CHOOSE NEXT FORM entry.
346
Continuing a transaction
The Continue Transaction (Continue Tx) transaction level tells the ACCELL/Manager
to continue the current transaction when the associated Next form begins execution.
All database operations performed on the Next form are part of the current
transaction.
To begin a Next form at the Continue Tx transaction level, the Manager:
•
activates the specified Next form
•
This transaction level maintains the active forms and the acquired locks.
The Manager performs a Continue Tx when it encounters:
•
a CHOOSE NEXT FORM statement with the transaction clause of:
CONTINUE TX RECORD_CONSISTENCY
or
CONTINUETXSET_CONSISTENCY
•
a CHOOSE NEXT FORM entry for the Next form with a transaction level
number of 1 (Continue Tx at Record Consistency) or 2 (Continue Tx at Set
Consistency)
Restarting a transaction
The Restart Transaction (Restart Tx) transaction level tells the ACCELL/Manager to
start a new transaction with a Next form that is already active. A transaction "restarts"
by returning execution to the specified Next form.
If the specified Next form is not currently active, a runtime error occurs.
347
All locks held from the previous invocation of the Next form still exist. However, these
locks have all been downgraded to SLOCKs. The Next form still has the same current
record and the same selected set.
To begin a Next form at the Restart Tx transaction level, the Manager:
•
commits the current transaction, downgrading all existing XLOCKs to LOCKs
•
deactivates all forms back to the specified Next form
•
starts a new transaction with the specified Next form
•
Notice the following differences between the Start Tx and the Restart Tx transaction
levels:
•
Restart Tx does not perform the Start Tx operation to start a new transaction:
it does not release all locks, it only downgrades them to SLOCKs.
•
Restart Tx does not activate the specified Next form because it can only start
a transaction with a Next form that is already active.
•
Restart Tx deactivates all active forms back to the specified Next form while
Start Tx deactivates all active forms back to the Master Application form.
•
Restart Tx maintains the selected set of records on the next form and all its
previous forms.
All database operations performed on the Next form are not part of the current
transaction; they are in a new transaction.
The Manager performs a Restart Tx when it encounters:
•
a CHOOSE NEXT FORM statement with the transaction clause of RESTART
TX
•
a Choose Next Form entry for the Next form with a transaction level number of
5 (Restart Tx)
348
NOTE:
You cannot redefine the Next form's consistency level with the Restart
Tx transaction level. The Manager restarts the transaction at the
consistency level currently defined for the Next form.
The "Restart Transaction" is useful for entering significant amounts of information
across several forms while maintaining control over the selected set.
Lock requests
When a database operation accesses the database, it must be able to complete its
database access without interruption. An interruption could cause the data being
selected, added, updated, or deleted to become inconsistent. To guarantee that the
database operation is uninterrupted, the transaction uses locking.
ACCELL/IDS lock management allows transactions to limit access by other
transactions to a locked database object. When the transaction acquires a lock on a
database object, this lock limits how other transactions can access the locked object.
By locking an object, the transaction ensures that no other transaction can access the
object in such a way that the data could be corrupted.
Only a transaction may hold locks on database objects. For a transaction to acquire a
lock:
•
the transaction issues a lock request on a database object.
•
ACCELL/IDS grants the lock request if no conflicting locks exist on the desired
database object.
Once the transaction acquires a lock on the database object, it can access the object
until the lock is released.
Issuing lock requests
A transaction issues a lock request to ACCELL/IDS indicating that the transaction
needs to control access to a database object.
The lock request specifies:
•
the database object to be locked
•
the type of ACCELL/IDS lock requested
349
A database object is an entity in the database that can be locked. The lock restricts
how other transactions can access the object.
ACCELL/IDS has two levels of database objects:
•
a database table
•
a single record in the table
These database objects are arranged in levels. If a lock is held at one level of
database object, all lower level objects are also locked. For example, because tables
are composed of records, if a table is locked, all its records are locked.
NOTE:
ACCELL/IDS cannot request a lock at the database schema level.
Only table and record lock requests are valid.
Once a transaction has started, the transaction may issue lock requests on database
objects. If a lock request is granted, then the transaction can access the object. Read
access allows the transaction to read the database object. Read/Write access allows
the transaction to modify the object; modification includes an Add, an Update or a
Delete operation.
The type of access permitted (Read or Read/Write access) is determined by the type
of lock the transaction acquires.
The transaction should acquire the appropriate lock type to perform the desired
database operation. For example, the Select operation only requires Read access
while all other database operations (Add, Update, and Delete) require Read/Write
access.
ACCELL/IDS supports two types of locks on database objects. These locks are:
•
SLOCKs (shared locks) – for Read access
•
XLOCKs (exclusive locks) – for Read/Write access
A transaction can have Read access to an object without requesting a lock. However,
if it does not request a lock, the transaction has no way of knowing how other
transactions are accessing the object.
350
For example, if Transaction A wants Read access on a particular database table, it
can still access the table without requesting a lock on the table. However, if
Transaction B already has Read/Write access on the same table, it is probably
modifying the table data. Without requesting a lock, Transaction A has no guarantee
that the data it is accessing is not in the process of being modified.
If Transaction A requested a Read access lock (an SLOCK), this request would be
denied when Transaction B already had Read/Write access (an XLOCK). Transaction
A's lock request would fail and the Transaction would not access inconsistent data.
To modify an object, a transaction must have Read/Write access granted. This access
can only be granted by the requesting of an XLOCK on the database object to be
modified.
The SLOCK
An SLOCK is a shared lock. It allows transactions to share a database object. When a
transaction acquires an SLOCK on a database object, this transaction is granted
Read access on the object. Other transactions can also be granted SLOCKs, allowing
them Read access as well.
NOTE:
A transaction holding an SLOCK on a database object can read the
object but cannot modify it.
Requesting an SLOCK ensures data consistency because no other transaction can
be granted Read/Write access to an object when this object SLOCKed. Because no
other transaction can be granted Read/Write access, no other transaction can modify
the object as long as the object is SLOCKed.
A transaction should request an SLOCK when it performs a database Find operation
because the transaction only needs Read access to an object to search it.
To acquire an SLOCK
•
During an interactive Find operation, ACCELL/IDS automatically issues
SLOCK requests on target table records associated with the selected set .
•
You can explicitly request SLOCKs for selected records during a noninteractive Find operation.
351
•
You can explicitly request SLOCKs on a table or on specific records within a
table.
You determine how the selected set is SLOCKed by specifying a consistency level in
the form's target table.
You explicitly issue SLOCK requests during a non-interactive Find by adding the
SLOCK locking clause to the SET/SELECT statement. You can also request SLOCKs
on a table or records with the Language SLOCK statement.
A transaction acquiring an SLOCK holds the lock until the SLOCK is released. To
release an SLOCK:
•
ACCELL/IDS automatically releases all locks (SLOCKs and XLOCKs) for the
current transaction when it performs a Start Tx.
•
At record consistency, ACCELL/IDS automatically releases the SLOCK for the
current record when the current record changes.
•
You can explicitly request a lock release for an SLOCKed object.
When the Manager moves to a specified Next form at the Start Tx transaction level, it
releases all locks (SLOCKs and XLOCKs) held by the current transaction before
terminating the transaction.
When a form is running at record consistency, ACCELL/IDS automatically SLOCKs
the current record. When another record in the selected set becomes current,
ACCELL/IDS releases the SLOCK on the previous current record and issues an
SLOCK request on the new current record.
You can use the UNLOCK statement to explicitly release an SLOCK on a database
object.
The XLOCK
An XLOCK is an exclusive lock. It allows a transaction exclusive access to a database
object. When a transaction acquires an XLOCK on a database object, this transaction
is granted Read/Write access on the object. Other transactions can be granted
neither Read nor Read/Write access on an XLOCKed object.
352
NOTE:
A transaction holding an XLOCK on a database object can read and
modify the object. Modifying the object can be an Add, Update, or
Delete operation.
Requesting an XLOCK ensures data integrity because other transactions cannot be
granted Read or Read/Write access to a database object when this object is
XLOCKed. Because no other transaction can be granted access, no other transaction
can read the data being modified nor can it modify the data as long as the object is
SLOCKed.
A transaction must request an XLOCK when it performs a database Add, Update, or
Delete operation. The transaction must have Read/Write permission on an object to
perform one of these operations.
To acquire an XLOCK
•
During an interactive Add, Update, or Delete operation, ACCELL/IDS
automatically issues XLOCK requests on target table records associated with
the selected set.
•
During a non-interactive Insert, Update, or Delete operation, the DML
statements (INSERT, UPDATE, and DELETE) automatically request XLOCKs
on specified database records.
•
You can explicitly request XLOCKs for selected records during a noninteractive Find operation.
•
You can explicitly request XLOCKs on a table or on specific records within a
table.
You can request XLOCKs on a table or records with the Language XLOCK statement.
You explicitly issue XLOCK requests during a non-interactive Find by adding the
XLOCK locking clause to the SET/SELECT statement.
A transaction acquiring an XLOCK holds the lock until:
•
ACCELL/IDS automatically releases all locks (SLOCKs and XLOCKs) for the
current transaction when it performs a Start Tx.
•
When a transaction is committed, ACCELL/IDS automatically downgrades all
XLOCKs to SLOCKs.
353
•
You can request a lock release for an XLOCKed object by first downgrading
the XLOCK to an SLOCK and then releasing the SLOCK.
When the Manager moves to a specified Next form at the Start Tx transaction level, it
releases all locks (SLOCKs and XLOCKs) held by the current transaction before
terminating the transaction.
When the transaction is committed, all XLOCKs are downgraded to SLOCKs. You use
the COMMIT TX statement to commit a transaction. When the Manager moves to a
specified Next form at the Restart Tx transaction level, it automatically commits the
current transaction so all XLOCKs are downgraded to SLOCKs as well.
You cannot use the UNLOCK statement to explicitly release an XLOCK. However, you
can use COMMIT TX to downgrade the XLOCKs and then use UNLOCK to release
the SLOCKs.
Granting lock requests
If the transaction's lock request is granted, then the transaction can access the
requested database object. The type of lock request determines the type of access
(Read or Read/Write) permitted.
Whether the lock request is granted to the transaction depends upon:
•
the locks held by other transactions
•
the locks already held by the current transaction
The following table summarizes the lock request rules. In this table, "Maybe" means
that the lock request is granted only if no other transaction holds a conflicting lock.
Lock requested
by A
Lock held by transaction A
Row SLOCK
Row XLOCK
Table SLOCK Table XLOCK
Row SLCOK
Granted
Granted
Granted
Granted
Row XLOCK
Maybe
Granted
Maybe
Granted
Table SLOCK
Maybe
Maybe
Granted
Granted
Table XLOCK
Maybe
Maybe
Maybe
Granted
Locks held by other transactions
354
The locks held by other transactions can affect a transaction's lock request when:
•
the transaction issues an SLOCK request – if no other transaction holds an
XLOCK on the object
•
the transaction issues an XLOCK request – if no other transaction holds any
lock on the object
Two or more transactions may hold shared locks (SLOCKs) on an object, while only
one transaction may hold an exclusive lock (XLOCK) on an object.
The following table summarizes how a lock request issued by one transaction
interacts with locks held by another transaction.
Lock held by transaction B
Lock requested by B
SLOCK
XLOCK
SLOCK
Granted
Denied
XLOCK
Denied
Denied
Figure 60. Locking Interaction between Transactions
A transaction can have Read access to an object without requesting a lock. However,
if it does not request a lock, the transaction has no way of knowing how other
transactions are accessing the object.
For example, if Transaction B wants Read access on a particular database table, it
can still access the table without requesting a lock on the table. However, if
Transaction A already has an XLOCK (Read/Write access) on the same table, it is
probably modifying the table data. Without requesting a lock, Transaction B has no
guarantee that the data it is accessing is not in the process of being modified.
If Transaction B requested an SLOCK (Read access), this request would be denied
when Transaction A already had an XLOCK (Read/Write access). Transaction B's
SLOCK request would probably fail and the transaction would not access inconsistent
data.
Locks held by the current transaction
The locks held by the current transaction can also affect a transaction's lock request if:
•
the transaction already holds the same lock on the object
355
•
the transaction already holds a higher level lock on the object
•
the transaction already holds a lock of the same level on a higher level object
It is not an error for a transaction to request the same lock more than once. However,
the number of successful lock requests is not recorded, so only one unlock request is
necessary to release the lock.
Lock promotion
A transaction has a limit on the number of locks it can hold at one time. To stay under
this limit, the ACCELL/DBMS may automatically perform lock promotion when large
numbers of records or tables are locked.
Lock promotion is a way of reducing the number of locks held by a transaction. If a
transaction already holds a large number of lock requests on records in a single table
and the transaction requests an additional record from the same table, the ACCELL//
DBMS "promotes" the lock request from a record lock request to a table lock request.
If the number of locks held by a transaction exceeds the lock limit, ACCELL/IDS may
request the same type of lock on the next higher-level database object. Additional
requests for the same type of lock on the lower-level object will not actually create the
requested lock.
When a table lock is granted, all record locks for that table held by the transaction are
released. Record locks are also released if you explicitly request a table lock after
acquiring several record locks.
To specify the number of locks that a single transaction can hold, you can set the
LMPROMO configuration parameter. If you do not want the database to promote
locks, set LMPROMO to zero (0). By default, a transaction is allowed to acquire 50
locks before the lock is promoted to a higher level.
Specifying a form's transaction information
When a Next form begins execution, the ACCELL/Manager needs to know how the
form affects the current transaction. To provide this information, each Next form has
transaction information defined:
•
356
a transaction level
•
a consistency level
A transaction level tells the Manager how to control the current transaction. All Next
forms have transaction levels. The consistency level tells the Manager how to issue
lock requests for the form's selected set. Only Next forms with target tables need to
have consistency levels.
Initializing the transaction information
You initialize a Next form's transaction information by creating a Next form definition
on the ACCELL/Generator's Choose Next Form form. The CHOOSE NEXT FORM
allows you to enter:
•
the name of the Next form
•
the Next form's transaction level number
A transaction level number specifies both the transaction level and the consistency
level to use for the Next form.
The following table summarizes the values for the Next form transaction level number.
Transaction level
number is ...
Transaction level is ...
Consistency level is ...
1
Continue Tx
Record consistency
2
Continue Tx
Set consistency
3
Start Tx
Record consistency
4
Start Tx
Set consistency
5
Restart Tx
Current consistency level
The transaction level number that appears by default depends upon whether the
working form in the Generator is the Master Application form or a Standard form.
If the Generator working form is the Master Application form, the Choose Next Form
form lists the names of possible First forms. The First form follows the Master
Application form in the application. By default, the transaction level number for a First
form is 3: Start Tx with Record Consistency. You can specify a Start Tx transaction
level only for a Master Application form (transaction level numbers 3 and 4).
357
If the Generator working form is a Standard form, the Choose Next Form form lists the
names of possible Next forms. A Next form follows a Standard form in the application.
By default, the transaction level number for a Next form is 1: Continue Tx with Record
Consistency.
Which transaction level to use depends on how what database operations are
performed on the form and how the form is activated. A transaction level of Start Tx
causes the Manager to deactivate all active forms back to the Master Application form
before activating the Next form. A Restart Tx transaction level deactivates all active
forms back to the specified Next form. A Continue Tx transaction level just causes the
Manager to activate the Next form.
Which consistency level to use depends on whether the form is a single-occurrence or
a multi-occurrence form, and how much concurrency you want to allow. In general,
single-occurrence forms should have a transaction level of record consistency; multioccurrence forms should have a transaction level of set consistency.
Changing the transaction information
To change the default transaction level number, you can either:
•
enter the new transaction level number in the Transaction Level field
•
use a Language statement to assign a new transaction level or consistency
level
Entering a new transaction level number on Choose Next Form changes the
transaction information for every activation of the associated Next form.
Using a Language statement can change the transaction level or the consistency level
for a particular activation of the associated Next form. The next time the Next form is
activated, the Manager returns to the transaction information defined in the
Generator.
With a Language statement, you can change the:
•
transaction level
•
consistency level
Changing the transaction level
358
The transaction level for a Next form is initialized by the transaction level number
associated with the Next form definition on the Choose Next Form form.
You can change the transaction level for a Next form at runtime with a CHOOSE
NEXT FORM statement. A CHOOSE NEXT FORM statement is either:
•
CHOOSE NEXT FORM – for a Next form (a form following a Standard form
•
CHOOSE FIRST FORM – for a First form (a form following the Master
Application form)
At runtime, the ACCELL/Manager uses this statement to select the valid Next forms.
The CHOOSE NEXT FORM statement specifies the name, transaction level, and
consistency level for the Next form.
The transaction clause allows you to specify the transaction level:
•
Start Tx – start a new transaction
•
Continue Tx – continue the current transaction
•
Restart Tx – restart a transaction
The following table shows CHOOSE NEXT FORM transaction clause values.
If the transaction level
clause is ...
Transaction level is ...
Consistency level is ...
CONTINUE TX
RECORD_CONSISTENCY
Continue Tx
Record consistency
CONTINUE TX
SET_CONSISTENCY
Continue Tx
Set consistency
START TX
RECORD_CONSISTENCY
Start Tx
Record consistency
START TX
SET_CONSISTENCY
Start Tx
Set consistency
RESTART TX
Restart Tx
Current consistency level
If a form's Language script contains a CHOOSE NEXT FORM statement, the Next
forms defined in this statement override the Next Forms defined in the ACCELL/
Generator.
Changing the consistency level
359
When you define an ACCELL/IDS form with a target table, the ACCELL/Manager
automatically performs the locking for the form's selected set. The type of locks the
Manager requests for the selected set is determined by the form's consistencylevel.
You initialize a Next form's consistency level by entering the transaction level number
on the ACCELL/Generator's Choose Next Form form.
You can initialize the consistency level to:
•
Record Consistency – request an SLOCK for the target table record
associated with the form's current record
•
Set Consistency – request an SLOCK for all target table record associated
with the form's selected set
On the Choose Next Form form, the default consistency level for both First forms and
Next forms is Record Consistency. You can change this initial consistency level by
modifying the transaction level number in the Transaction Level field.
You can change the consistency level for a Next form at runtime for:
•
a Next form – with a CHOOSE NEXT FORM statement
•
a Zoom form – with the ENABLE ZOOM statement
For a Next form
To change the consistency level for a Next Form, use one of the CHOOSE NEXT
FORM statements:
•
CHOOSE NEXT FORM – for a Next form (a form following a Standard form)
•
CHOOSE FIRST FORM – for a First form (a form following the Master
Application form)
At runtime, the ACCELL/Manager uses the CHOOSE NEXT FORM statement to
select the valid Next forms. The CHOOSE NEXT FORM statement specifies the
name, transaction level, and consistency level for the Next form.
The transaction clause allows you to specify the Next form's consistency level.
360
If a form's Language script contains a CHOOSE NEXT FORM statement, the Next
forms defined in this statement override the Next Forms defined in the ACCELL/
Generator.
For a Zoom form
To change the consistency level for a Zoom form, use the ENABLE ZOOM statement.
This statement has a consistency level clause that allows you to specify either
RECORD_CONSISTENCY or SET_CONSISTENCY as the Zoom form's consistency
level.
If a form's Language script contains an ENABLE ZOOM statement with a consistency
level clause, this consistency level overrides the Next Form consistency level defined
in the ACCELL/Generator.
Without the consistency level clause, the Zoom form executes at the consistency level
of the calling form.
NOTE:
You cannot change the transaction level for a Zoom form. The
transaction level for a Zoom form is always Continue Tx.
Using interactive operations in a transaction
An interactive operation is a database operation that accesses the form's target table
without explicitly stating the table name. The form's target table is defined within the
ACCELL/Generator. An interactive operation can be:
•
an interactive Find (generated by FIND, NEXT ACTION IS FIND, or
AUTO_FIND = TRUE) that creates a selected set
•
an interactive Add (generated by ADD/UPDATE or UPDATE CURRENT
RECORD) that adds a new record to the selected set and a new record to the
target table
•
an interactive Update (generated by ADD/UPDATE or UPDATE CURRENT
RECORD) that updates a record in the selected set and a record in the target
table
•
an interactive Delete (generated by DELETE RECORD or DELETE
CURRENT RECORD) that deletes a record in the selected set and a record in
the target table
361
Lock requests are automatically issued on the target table during an interactive
operation.
The interactive find
In an interactive Find, the ACCELL/Manager automatically initiates a search on the
form's target table. If the Manager finds target table records that match the search
criteria, it creates a selected set. In the selected set, there is an ACCELL/IDS record
for each selected target table record.
When a form has a target table, the ACCELL/Manager performs lock management on
the selected set automatically. The Manager issues lock requests on the target table
when it:
•
creates the selected set
•
moves through the selected set
•
clears the selected set
Creating the selected set
During an interactive Find, the ACCELL/Manager creates a selected set of records
when it finds matching target table records. The type of locks placed on target table
records is determined by the form's consistency level.
The ACCELL/IDS consistency levels are:
•
record consistency
•
set consistency
The following table summarizes the lock requests made for each consistency level.
Conssistency
level is ...
Record locking is ...
Record
Consistency
All records satisfying the search criteria are placed in the selected set
regardless of their lock status.
Only trhe record associated with the current record is SLOCKed;
reocrds associated with all other records are unocked.
362
Conssistency
level is ...
Record locking is ...
If the application shows
“dirty” data:
The selected set record for an XLOCKed record has the values of the
datbase record when the selected set was created. The actual
database record may be in the process of being modified or deleted by
another transaction.
If the application does not
show “dirty” data:
The selected set record for an XLOCKed record has field values of
UNDEFINED
Set consistency
Lock status of records satsifying the search criteria is checked before
the records are placed in the selected set.
All records associated wtih selected set records are SLOCKed.
XLOCKed records are not placed in the selected set.
At record consistency
The record consistency consistency level guarantees that the form's current record in
the selected set cannot be modified by another transaction. To ensure this
consistency, the ACCELL/Manager requests a shared lock (SLOCK) on the current
record. Record consistency is appropriate for single-occurrence forms where records
are displayed one at a time.
The advantage of using record consistency is that it provides greater concurrency:
other transactions have access to more records in the target table. The disadvantages
of running at record consistency is that a record in the selected set may be updated or
deleted by another transaction.
At record consistency, all records satisfying the search criteria are placed in the
selected set. The Manager requests an SLOCK only for the target table record
associated with the current record. Records associated with all other records in the
selected set have no lock requested. Therefore, the Manager can create selected set
records for all matching target table records, regardless of their lock status.
Because the Manager does not issue lock requests for selected records not
associated with the current record, other transactions can obtain Read and Read/
Write access on these selected records. Only the record associated with the current
record is protected from modification by other transactions.
At record consistency, there is a chance for "dirty" data to be selected. The Manager
creates selected set records for all target table records satisfying the search criteria. It
363
does not check the lock status of the selected records during the creation of the
selected set. Therefore, XLOCKed records may be placed in the selected set.
You can reject the XLOCKed record with the REJECT RECORD statement.
At set consistency
The set consistency consistency level guarantees that all records in the form's
selected set cannot be modified by another transaction. To ensure this consistency,
the ACCELL/Manager requests a shared lock (SLOCK) for the selected database
records. Set consistency is appropriate for multi-occurrence forms where several
records are displayed at one time.
The advantages of using set consistency is that no other transactions can modify the
target table records associated with the selected set until the locks are released. The
disadvantages of running at set consistency is fewer target table records are available
to other transactions.
At set consistency, a record that satisfies the search criteria is placed in the selected
set only if the current transaction can acquire SLOCKs on it. If a target table record is
currently SLOCKed by another transaction, the SLOCK request can be granted.
Therefore, the Manager can create an associated selected set record. However, if a
target table record is currently XLOCKed by another transaction, the SLOCK request
is not granted and the Manager cannot create an associated selected set record.
Because the Manager has acquired an SLOCK for all records associated with the
selected set, other transactions can read but cannot modify the selected records.
At set consistency, it is not possible for "dirty" data to occur in the selected set
because the Manager checks the lock status of selected records before it creates the
associated selected set records. If the Manager encounters a target table record that
is already XLOCKed, it does not create a selected set record for this XLOCKed
record. No XLOCKed records are placed in the selected set and therefore no "dirty"
data is selected.
When the form is at set consistency, you can use the status$() function to check for
XLOCKed records by including it in the AFTER FIND section.
364
NOTE:
At set consistency, the status$() system function does not return the
status code in the ON FIND section.
Making a record current
Once the ACCELL/Manager creates a selected set, it must establish which record is
the current record. At both transaction types (record consistency and set
consistency), the Manager must be able to acquire an SLOCK on the target table
record associated with the current record. If this record is not SLOCKed, other
transactions can update or delete it.
At record consistency, the Manager must acquire an SLOCK on a target table record
to make a record current. The Manager requests an SLOCK on the first record
selected. If this SLOCK is granted, then the associated selected set record becomes
the current record. If this SLOCK is not granted, then the Manager requests an
SLOCK on the next record selected.
If the Manager cannot acquire an SLOCK on any of the selected target table records,
a runtime error occurs. The Manager:
•
displays an error message
•
performs a CLEAR TO FIND
•
places the form back in Find mode
At the set consistency level, acquiring an SLOCK specifically on the current record's
target table record is not necessary because, at set consistency, the Manager has
already requested an SLOCK on every target table record associated with the
selected set. Only those target table records that could be SLOCKed have records in
the selected set.
Moving through the selected set
Whenever the Manager receives a command to move to another record, the current
record changes. The Manager moves to another selected set record when:
•
the end user issues one of the following commands.
NEXT RECORDPREV RECORD
FIRST RECORDLAST RECORD
NEXT SETPREV SET
365
•
one of the following NEXT ACTION statements executes:
NEXT ACTION IS NEXT RECORD
NEXT ACTION IS PREVIOUS RECORD
NEXT ACTION IS FIRST RECORD
NEXT ACTION IS LAST RECORD
NEXT ACTION IS NEXT SET
NEXT ACTION IS PREVIOUS SET
When the Manager moves through the selected set, it must determine which selected
set record to make current. At record consistency, the Manager must issue an SLOCK
request to make another record current.
NOTE:
At set consistency, the Manager does not need to issue the SLOCK
request because all records associated with the selected set already
have an SLOCK.
At record consistency, to make another selected set record current, the Manager:
•
requests an SLOCK on the target table record associated with the record
being moved to
•
requests a lock release on the target table record associated with the old
current record
If the Manager is not granted the SLOCK request, it tries to "skip over" the requested
record. It searches for the next record in the selected set whose target table record
can be SLOCKed.
NOTE:
If the Manager cannot acquire an SLOCK on any record, a runtime
error occurs. The old current record remains current.
Once the new current record has an SLOCK on its target table record, the Manager
requests a lock release on the old current record's associated target table record. If
this old current record was updated or added, unlocking the current record will not be
successful because this current record's associated target table record has been
XLOCKed. In this case, the XLOCKed record remains locked until the transaction is
committed or restarted.
Clearing the selected set
366
The ACCELL/Manager clears the selected set when:
•
it performs a CLEAR TO FIND operation
•
it moves to a previous form with either PREV FORM or CANCEL ZOOM
For the CLEAR TO FIND operation, the Manager places the form in Find mode. For
PREV FORM or CANCEL ZOOM operation, the Manager clears the selected set.
NOTE:
When it clears the selected set, the Manager does not perform any
transaction operations: the current transaction is neither committed nor
restarted.
The actions taken by the Manager depend on whether the form is running at record
consistency or set consistency.
At record consistency, the Manager clears the selected set by:
•
issuing a lock release request to unlock all SLOCKed target table records
associated with the selected set records
•
discarding the selected set records
At set consistency, the Manager just discards the selected set records: all SLOCKs on
the target table records associated with the selected set records are retained until the
current transaction is committed.
If any selected set records were modified or added, their associated target table
records have an XLOCK. Regardless of the form's consistency level, the Manager
does not release these XLOCKs when it clears the selected set. The XLOCKs remain
locked until the current transaction is either committed or restarted.
Adding records to the selected set
The Manager adds a new record to the selected set if the current record was created
with the CLEAR TO ADD command. If the current record was part of a selected set
created by FIND (an interactive Find), the Manager updates the current record. The
events that initiate an add or update of the current record are:
•
the end user issues the ADD/UPDATE command
•
the UPDATE CURRENT RECORD statement executes
367
When it adds a new record, the Manager can also add a new record to the target table
(if the form has a target table defined). When the record is added to the database, the
Manager requests an XLOCK on the record. This XLOCK remains until the current
transaction is committed.
By default, the Manager does not perform any transaction operations when it adds a
new record. The current transaction is not committed nor is it restarted. However, if
the AUTO_COMMIT form attribute is set to TRUE, the Manager does perform a
"Commit Transaction" after the interactive Add successfully completes.
NOTE:
If the AUTO_COMMIT form attribute is set to TRUE, the Manager
performs a "Commit Transaction" after every successful interactive
operation.
The Commit operation downgrades all XLOCKs to SLOCKs. This lock operation
allows other transactions to read the target table record just added.
The interactive Add operation can fail because of XLOCKed records if the target table
is a child table in a link relation. You cannot add a target table record when the parent
table is XLOCKed.
You can use the status$() system function to check whether the interactive Add failed
because the parent table was XLOCKed.
For an interactive Add initiated by ADD/UPDATE, check for the Add failure in the
AFTER UPDATE Language section. For an interactive Add initiated by UPDATE
CURRENT RECORD, check for the Add failure after the UPDATE CURRENT
RECORD Language statement.
NOTE:
The UPDATE CURRENT RECORD statement does not cause the Add
Language sections to execute. You must check the lock status of
UPDATE CURRENT RECORD in the same section that contains the
UPDATE CURRENT RECORD statement.
Updating records in the selected set
The Manager updates the current record if the current record was part of a selected
set created by FIND (an interactive Find). If the current record was created with the
368
CLEAR TO ADD command, the Manager adds a new record to the selected set. The
events that initiate an add or update of the current record are:
•
the end user issues the ADD/UPDATE command
•
the UPDATE CURRENT RECORD statement executes
When it updates a record, the Manager can also update a record in the target table (if
the form has a target table defined). The Manager acquires an XLOCK on the target
table record before updating the record. This XLOCK remains until the current
If ACCELL/IDS cannot obtain the XLOCK, it displays a message and the Update fails.
You can use the status$() system function to check whether the Update initiated by
ADD/UPDATE encountered a locking conflict.
For an interactive Update initiated by ADD/UPDATE, check for XLOCKed records in
the AFTER UPDATE Language section. For an interactive Update initiated by
UPDATE CURRENT RECORD, check for XLOCKed records after the UPDATE
CURRENT RECORD Language statement.
NOTE:
The UPDATE CURRENT RECORD statement does not cause the
Update Language sections to execute. You must check the lock status
of UPDATE CURRENT RECORD in the same section that contains the
UPDATE CURRENT RECORD statement.
By default, the Manager does not commit the current transaction. However, if the
AUTO_COMMIT form attribute is set to TRUE, the Manager does perform a "Commit
Transaction" after the interactive Update successfully completes. The Commit
operation downgrades all XLOCKs to SLOCKs. This lock operation allows other
transactions to read the target table record just modified.
NOTE:
operation.
Deleting records from the selected set
The ACCELL/Manager deletes a record from the selected set when:
•
the end user issues the DELETE RECORD command
369
•
the DELETE CURRENT RECORD statement executes
When it deletes a record, the Manager can also delete a record in the target table (if
the form has a target table defined). The Manager acquires an XLOCK on the target
table record before deleting any record. This XLOCK remains until the current
If ACCELL/IDS cannot obtain the XLOCK, it displays a message and the Delete fails.
You can use the status$() system function to check whether the Delete operation
failed because of a locking conflict.
If a buffered sequential scan is used with the DELETE RECORD command, an
SLOCK is acquired on the table. The SLOCK is not released until the table is
unlocked.
For an interactive Delete initiated by DELETE RECORD, check for XLOCKed records
in the AFTER DELETE Language section. For an interactive Delete initiated by
DELETE CURRENT RECORD, check for XLOCKed records after the DELETE
CURRENT RECORD Language statement.
NOTE:
The DELETE CURRENT RECORD statement does not cause the
Delete Language sections to execute. You must check the lock status
of DELETE CURRENT RECORD in the same section that contains the
DELETE CURRENT RECORD statement.
By default, the Manager does not perform any transaction operations when it deletes
a record. The current transaction is not committed nor is it restarted. However, if the
AUTO_COMMIT form attribute is set to TRUE, the Manager does perform a "Commit
Transaction" after the interactive Delete successfully completes.
NOTE:
operation.
If a buffered sequential scan is used with the DELETE CURRENT RECORD
command, an SLOCK is acquired on the table. The SLOCK is not released until the
table is unlocked.
370
Using non-interactive operations in a transaction
A non-interactive operation is a database operation that accesses a specified
database table. A non-interactive operation can be:
•
a non-interactive lock request (generated by one of the SLOCK, XLOCK, or
UNLOCK statements) that locks or unlocks either specified records in a
database table or a table itself
•
a non-interactive Find (generated by the SET/SELECT statement) that
searches for records in a specified database table
•
a non-interactive Insert (generated by the INSERT statement) that inserts
records into a specified database table
•
a non-interactive Update (generated by the UPDATE statement) that updates
specified records in a database table
•
a non-interactive Delete (generated by the DELETE statement) that deletes
specified records from a database table
The non-interactive Insert, Update, and Delete operations are also referred to as DML
operations.
Locking database records
A lock affects whether other transactions can access a database object. A transaction
has Read access to any object it has SLOCKed and Read/Write access to any object
it has XLOCKed.
The ACCELL/Manager performs some lock management automatically:
•
when a record is inserted – the Manager XLOCKs the new record
•
when a record is updated or deleted – the Manager XLOCKs the record before
the Update or Delete
•
when a transaction is committed – the Manager downgrades all XLOCKs to
SLOCKs
•
when a form begins at the Start Tx transaction level – the Manager unlocks all
locked records
371
During an ACCELL/IDS transaction, you can create your own lock requests with the
locking statements. Use the ACCELL/IDS locking statements in a multi-user
application to protect records and tables from modification.
The ACCELL/Language locking statements are:
•
SLOCK – places a shared lock (SLOCK) on a specified record or table
•
XLOCK – places an exclusive lock (XLOCK) on a specified record or table
•
UNLOCK – releases a shared lock (SLOCK) on a specified record or table
After issuing a lock request, it is good practice to check the status$() return code to
ensure that the requested lock was acquired. Performing any operations based on the
assumption that the lock has been granted is dangerous because the object may be in
the midst of an update and may contain inconsistent data.
NOTE:
Usually, you will use these locking statements on non-target tables.
ACCELL/IDS automatically performs target table locking in an
interactive transaction.
Each of these locking statements is described in the following sections.
The SLOCK statement
An SLOCK statement attempts to place an SLOCK on a database object. This object
can be either a table or a set of database records. An SLOCK is a shared lock. When
a table or record has a shared lock, any transaction may read the SLOCKed object,
but no other transaction may modify it.
The requested SLOCK is kept until either:
•
a form begins execution at the Start Tx transaction level
•
the SLOCK is explicitly released by an UNLOCK
The WHERE clause identifies the set of database records in the database table to
SLOCK. For each record that meets the WHERE criteria, ACCELL/IDS requests an
SLOCK.
If an SLOCK statement does not have a WHERE clause, ACCELL/IDS requests an
SLOCK on the database table. If this lock request is successful, all records in the
372
table acquire an SLOCK. The statement fails if the table cannot be SLOCKed (either
the table itself is already XLOCKed or any of the table's records are XLOCKed).
Execution of an SLOCK statement does not guarantee that the record or table is
SLOCKed. The statement generates a request for a shared lock on the object. If the
request cannot be granted, another transaction is probably holding a conflicting lock.
You can use the status$() system function to test the success of an SLOCK
statement.
When the SLOCK statement contains a WHERE clause, SLOCK issues SLOCK
requests a on all records meeting the WHERE clause criteria. In this case, SLOCK:
•
selects a matching record
•
requests an SLOCK on this record
It continues this process until one of the following conditions is met:
•
no more matching records exist
•
the SLOCK request fails
•
some other error occurs
You can write your application so it attempts a lock several times if an SLOCK fails. If,
after repeated attempts, the lock still fails, it may be best to start the transaction over
and release all locks. This prevents a deadlock with another application over the
database. Be sure your application provides appropriate messages to the user about
the locking problems.
The XLOCK Statement
An XLOCK statement attempts to place an XLOCK on a database table or on
database records. An XLOCK is an exclusive lock. When a table or record has an
exclusive lock, only the transaction that XLOCKed the object may use it. Most other
transactions may neither read nor change the table or record.
The WHERE clause identifies the set of database records in the table table_name to
XLOCK. For each record that meets the WHERE criteria, ACCELL/IDS requests an
XLOCK.
373
The requested XLOCKs are kept until:
•
the transaction is committed
•
the transaction is restarted (a form begins execution at the Restart Tx
transaction level)
•
a new transaction is started (a form begins execution at the Start Tx
transaction level)
When either of these events occurs, all XLOCKs are downgraded to SLOCKs.
NOTE:
You cannot use the UNLOCK statement to release an XLOCK. An
XLOCK must be downgraded to an SLOCK before it can be released.
Once the XLOCK is downgraded to an SLOCK, you can release the
SLOCK with the UNLOCK statement or by starting a new transaction.
If an XLOCK statement does not have a WHERE clause, ACCELL/IDS requests an
XLOCK on the database table. If this lock request is successful, all records in the
table acquire an XLOCK. The statement fails if the table cannot be XLOCKed (either
the table itself is already XLOCKed or any of the table's records are XLOCKed).
Execution of an XLOCK statement does not guarantee that the record or table is
XLOCKed. The statement generates a request for a shared lock on the object. If the
request cannot be granted, another transaction is probably holding a conflicting lock.
You can use the status$() system function to test the success of an XLOCK
statement.
When the XLOCK statement contains a WHERE clause, XLOCK issues XLOCK
requests on all records meeting the WHERE clause criteria. In this case, XLOCK:
•
selects a matching record
•
requests an SLOCK on this record
It continues this process until one of the following conditions is met:
374
•
•
the XLOCK request fails
•
some other error occurs
You can write your application so it attempts a lock several times if an XLOCK fails. If,
after repeated attempts, the lock still fails, it may be best to start the transaction over
and release all locks. This prevents a deadlock with another application over the
database. Be sure your application provides appropriate messages to the user about
the locking problems.
The UNLOCK Statement
An UNLOCK statement attempts to release a lock on a database table or on database
records. All lock release requests are treated as suggestions. If an object is currently
XLOCKed, the ACCELL/Manager just ignores the UNLOCK suggestion.
This statement can release shared locks (SLOCKs) only. To release an XLOCK, you
must first downgrade the XLOCK to an SLOCK. The COMMIT TX statement and the
RESTART TX clause of the CHOOSE NEXT FORM statements (CHOOSE NEXT
FORM and CHOOSE FIRST FORM) automatically downgrade XLOCKs to SLOCKs.
Once the XLOCK is downgraded to an SLOCK, you can release the SLOCK with the
UNLOCK statement.
NOTE:
The only way an XLOCK can be released directly (without first being
downgraded to an SLOCK) is by the ACCELL/Manager when it begins
form execution at the Start Tx transaction level. Within the ACCELL/
Language, you must always downgrade an XLOCK before you can
release it.
ACCELL/IDS ignores requests to unlock an object when the transaction holds a lock
on a higher level object. Thus, if a table is locked, a request to unlock a record in this
table is ignored.
The following table summarizes the unlock request rules
UNLOCK
request by A
Locks held by transaction A
Row SLOCKed
Row XLOCKed
Table SLOCKed Table XLOCKed
UNLOCK record
Granted
Denied
Denied
Denied
UNLOCK table
Granted
Denied
Granted
Denied
The WHERE clause identifies the set of database records in the table table_name to
unlock. For each record that meets the WHERE criteria, ACCELL/IDS requests a lock
375
release for an SLOCK. If an UNLOCK statement does not have a WHERE clause,
ACCELL/IDS requests a lock release for an SLOCK on the database table.
The status$() system function always reports success even if the objects cannot be
unlocked because they have been XLOCKed.
Unlocking a table unlocks all the individually locked records. However, unlocking all
the records in the table does not unlock the table. To unlock a table, you must use the
UNLOCK statement to explicitly unlock it.
Unlocking records that are already unlocked is not an error. It is good programming
practice to unlock any records or tables that are no longer required. Once the object is
unlocked, other transactions can access it.
Using the locking statements
To use the locking statements (SLOCK, XLOCK, and UNLOCK), you:
•
list the database table containing the records you want to lock or unlock
•
specify which records within the table are to be selected for the locking
request (optional)
Listing the table name
To lock or unlock a database object, you must list the name of a database table. You
list the table name just after the locking statement keyword (SLOCK, XLOCK, or
UNLOCK). This table name specification has the syntax:
UNLOCK table
Specifying the records to lock
The WHERE clause identifies a set of database records in the table to be locked. To
issue a lock request, ACCELL/IDS scans the appropriate table, selecting records
based on the search criteria in the WHERE clause. Lock requests and lock release
requests both fail for a selected record if the record is currently XLOCKed by another
transaction.
The locking statement selects all records that satisfy the logical expression following
the keyword WHERE. This logical expression describes the search criteria to use
376
when selecting the records to delete. This expression usually includes a test on at
least one field name from the database table.
Lock promotion can occur if the statement has a WHERE clause and a large number
of records meet the selection criteria. In this case, you may get better performance by
explicitly locking the entire table.
If the WHERE clause is omitted, all records in the table are selected from the
database and a lock request is issued for the entire table. The table lock request is
successful only if it is not currently XLOCKed by another transaction.
When you specify a WHERE clause, the Manager determines the optimal database
access method to use. For WHERE clause optimization to function correctly, make
sure that the logical expression in the WHERE clause is reduced to its simplest form.
Reducing all expressions in the WHERE clause to their simplest form greatly
enhances access performance.
Selecting database records
The SET/SELECT statement initiates a non-interactive Find. With the SET/SELECT
statement, you control the lock status of the selected record by including the locking
clause.
This locking clause can contain either of the keywords SLOCK or XLOCK to specify
the type of locks you want placed on the selected record.
If the SET/SELECT statement includes an EXECUTING clause and a locking clause,
the Language statements in the EXECUTING block execute for each selected record
and locks are requested for all selected records. However, if no EXECUTING clause
exists, SET/SELECT selects only the first record that matches the search criteria and
only this single record is locked.
NOTE:
If the record is XLOCKed, all field values in this record are
UNDEFINED.
If you omit the locking clause, no locks are placed on the selected records.
If you do not include a locking clause on the SET/SELECT statement, ACCELL/IDS
does not issue lock requests for the selected records and therefore no locking
377
conflicts can occur. All records satisfying the search criteria are selected regardless of
their current lock status.
Inserting database records
The INSERT statement inserts the record or records into a database table. After a
successful insert, the records remain XLOCKed until the transaction is committed.
You can use the status$() system function after the INSERT statement to check
whether the non-interactive Insert failed because the parent table was XLOCKed.
Updating and deleting database recordS
For the non-interactive statements UPDATE and DELETE, ACCELL/IDS scans the
appropriate table to select the records to update or delete. Either statement selects
the first record matching the criteria in the WHERE clause.
Before it actually updates (or deletes) this selected record, the UPDATE (or DELETE)
statement always requests an XLOCK on this record. If the XLOCK is granted, the
statement updates or deletes the record. This XLOCK is retained until the transaction
is committed.
Once the record is updated (or deleted), the statement selects the next matching
record. This process of:
•
requesting an XLOCK on the record
•
updating (or deleting) the record if the XLOCK request is successful
•
selecting the next matching record
continues until one of the following conditions is met:
•
•
an XLOCK request fails
•
it encounters another error
Lock promotion can occur if the statement has a WHERE clause and a large number
of records meet the selection criteria. In this case, you may get better performance by
378
explicitly locking the entire table with the XLOCK statement before executing the
statement.
If an UPDATE or DELETE statement does not have a WHERE clause, ACCELL/IDS
requests an XLOCK on the entire table. It then performs a sequential search on the
table, operating on each record. The statement fails if the table cannot be XLOCKed.
You can use the status$() system function after the UPDATE or DELETE statement to
check whether the UPDATE (or DELETE) failed because of an XLOCKed record.
If a buffered sequential scan is used with the DELETE command, an SLOCK is
acquired on the table. The SLOCK is not released until the table is unlocked.
Committing a transaction
While a transaction is active, it requests locks for database operations. If the form
performs a Find operation, the transaction should first hold an SLOCK (Read access)
on a database object. If the form performs an Add (Insert), Update, or Delete
operation, the transaction should first hold an XLOCK on a database object.
When a transaction is committed, locks on all changed or added records are
downgraded from XLOCKs to SLOCKs. When these records are SLOCKed, other
transactions can read but not modify the records.
Using the COMMIT TX statement
The COMMIT TX statement performs a Transaction Commit to end the current
transaction. After COMMIT TX executes, a new transaction is ready to start. All locks
are retained, but all exclusive locks (XLOCKs) held by the transaction have been
downgraded to shared locks (SLOCKs).
COMMIT TX affects the lock status of every XLOCKed record regardless of whether
this record has been locked through an interactive operation (ADD/UPDATE, DELETE
RECORD, UPDATE CURRENT RECORD, DELETE CURRENT RECORD) or a noninteractive operation (SET/SELECT, UPDATE, DELETE, INSERT).
NOTE:
Once you have committed a transaction with COMMIT TX, the
transaction cannot be aborted.
379
The COMMIT TX statement can alternatively be written as COMMIT TX to be
compatible with previous releases of the ACCELL/Language.
Setting the AUTO_COMMIT attribute
The AUTO_COMMIT form attribute is a BOOLEAN flag that controls whether the
ACCELL/Manager performs an implicit Transaction Commit after every successful
interactive database operation.
The Manager checks AUTO_COMMIT form attribute when it successfully completes
an interactive Add, Update or Delete operation. If AUTO_COMMIT is TRUE, the
Manager performs a Transaction Commit after the operation, downgrading any
XLOCKs to SLOCKs, ending the current transaction, and beginning a new
transaction.
When AUTO_COMMIT downgrades the XLOCKs, it affects the lock status of every
XLOCKed record regardless of whether this record has been locked through an
interactive operation (ADD/UPDATE, DELETE RECORD, UPDATE CURRENT
RECORD, DELETE CURRENT RECORD) or a non-interactive operation (SET/
SELECT, UPDATE, DELETE, INSERT).
If the AUTO_COMMIT form attribute is set to FALSE, interactive database operations
are not committed automatically. You must commit them with the COMMIT TX
statement, by beginning a Next form at the Start Tx transaction level, or by beginning
a Next form at the Restart Tx transaction level.
You can set the AUTO_COMMIT form attribute only from within the ACCELL/
Language. There is no way to initialize AUTO_COMMIT from within the ACCELL/
Generator. This form attribute is useful only on a form that has a target table defined.
380
9.7 Application optimization
This section describes how to optimize your application's performance. You should
read this guide before you start developing your application. However, if your
application is complete, this section can help you analyze the application's
performance.
Application performance can be affected in many ways. Applications can have
performance problems related to memory use or execution speed. Execution speed
problems can be global or relate to specific bottlenecks during the application
execution.
In this section, "performance" refers to execution speed, and "memory" refers to
performance problems related to memory use. If you are having a performance or
memory problem, the information in this section should help you determine the nature
of problem. The section also gives suggestions for solving some of the more common
problems.
This section contains three subsections:
•
Performance Optimization
•
Memory Optimization
•
Diagnostic Guide
Performance optimization
This subsection describes tools that help you identify possible performance problems
and several solutions for common problems.
Environment variable settings
The init_mem_size and sort_mem_size parameters for the AMGRINIT environment
variable were designed to increase performance for large applications or databases.
ACCELL/IDS allocates and deallocates memory frequently while an application is
running. If there is not a large enough contiguous segment of memory, a call to sbrk
381
will result. Often this results in your process being swapped to acquire more memory.
Slow processing after the NEXT FORM command is a symptom of this problem.
The init_mem_size parameter of the AMGRINIT environment variable controls the
initial size of the data segment of your process. The default size is 65,535 bytes. If
init_mem_size is set to the maximum data segment size required by your application,
calls to sbrk–and swapping to acquire more memory–can be eliminated.
ACCELL/IDS incorporates its own sorting package to help optimize performance. You
can set the sort_mem_size parameter of the AMGRINIT environment variable to
control when sorts occur in memory versus disk. Setting sort_mem_size can
dramatically effect sort performance. Note, however, that it also increases the total
process size, so be careful setting this parameter.
Screen design
When you design your forms, be sure to size them efficiently. The form should not
include lots of white space because the window manager must keep track of white
space and what it covers. This causes unnecessary processing and memory use. Try
to design your forms with just the information needed, leaving a small amount of
space between the trim/fields and the window border.
USING list_scan
With the list_scan feature of ACCELL/IDS, you can determine which Pathfindert
access method is being used to retrieve data from the DBMS. The list_scan feature
reports scan information for both interactive Finds and DML statements contained in
ACCELL/IDS language scripts.
To turn on the list_scan feature, add the string list_scan=yes to the options in the
AMGRINIT environment variable. You must also define the error_file option when
using list_scan, or output is directed to /dev/null. To best use list_scan, try using two
terminals, one running your application, and the other running tail –f on the error_file.
Whenever a Find or DML statement processes you see the type of scan and other
information.
The list_scan feature is important because usually you want to avoid sequential scans
in favor of hash keys, links, or B-Trees. If you require items to be sorted according to a
combination of fields that you use often as search criteria, you may want to add a
382
combination B-Tree with the same components and ordering. A combination B-Tree
would speed up the search, avoiding the sort. When a large sequential scan is
unavoidable, you can try browse mode if the semantics of your application permit.
The list_scan Report
The following four figures show examples of list_scan reports.
=============== ubstcn() info ===============
scan kind =
4
scan mode =
1
best index =
0
sort ord?
0
empty scn?
0
range scn?
0
no. records =
10
=============== Access info ===============
Sequencial Scan
Figure 61. Example of Sequential Scan
=============== ubstcn() info ===============
scan kind =
2
scan mode =
1
best index =
0
sort ord?
0
empty scn?
0
range scn?
0
no. records =
1
=============== Access info ===============
Hash-key Scan
no. components in key =
1
Figure 62. Example of Hash-Key Scan
383
=============== ubstcn() info ===============
scan kind =
scan mode =
best index =
0
sort ord?
empty scn?
range scn?
no. records =
1
=============== Access info ===============
Linked Scan
no. components in key =
1
related field number =
55
parent relation id. =
1
parent field no. =
1
Figure 63. Example of Linked Scan
384
=============== ubstcn() info ===============
scan kind =
3
scan mode =
1
best index =
0
sort ord?
0
empty scn?
0
range scn?
0
no. records =
1
=============== Access info ===============
B-Tree Scan
duplicate entry flag =
1
duplicate entry flag =
1
no. of b-tree components =
1
no. of components used for b-tree =1
-------------b-tree entries--------------entry 0
0
Figure 64. Example of B-Tree Scan
list_scan report elements
The following table describes the elements displayed in a list_scan report.
Under the heading ubstcn()
Element
Value
Meaning
scan kind
0
Unknown scan kind
1
Link scan
2
Hash key scan
3
B-Tree scan
4
Sequential scan
1
direct mode (no sort)
2
Build a tag file (sort)
scan mode
385
Under the heading ubstcn()
Element
Value
best index
Disregard
sort ord?
0
If no sort is specified, or if records are not sorted as a by-product of
using the access method (B-tree)
1
If records are returned in sorted order (skip the sort)
0
This is not an empty scan
1
Something about the search criteria identified as being guaranteed
to produce no records (num < 10 && num >11)
0
This is not a range scan
1
This is a range scan
n
The esitmated number of records this scan will produce. This is
used internally for access method selection and may or may not
match the final result.
empty scn
range scn
no. records
Meaning
Depending on scan type, some additional information may be included:
Under the heading access info
Element
Meaning
no. component in key
The number of components in the key for this database
related field number
parent relation id
parent field no.
duplicate entry flag
no. of b-tree components
no. of components used for b-tree
Using lmpeek to investigate locking
With lmpeek, you can monitor the number and type of locks at a specific time. You can
determine if table locks are being obtained or if large numbers of locks are not being
released.
To use lmpeek, enter the following command at the shell prompt:
lmpeek
386
The following figure shows an example of lmpeek's output.
unify% lmpeek
------------------------------trx# 8053.2 (1), dbid: 13027.2077 rid: 1 tid: 0
[SLK]
--------------------------------Total 22408 Busy 3156 Free: 19252
Figure 65. Example of lmpeek Output
The information displayed by lmpeek can be interpreted as follows:
trx#
dbid:
rid: and tid:
[SLK] or [XLK]
Transaction information consisting of three parts:
l
The process ID number
l
The number of times this process has started a new transaction
l
The number of locks held by the process now
Database information, consisting of two parts:
l
The inode number of file.db
l
The device number that file.db resides on. The device number is
calculated by multiplying the major device number by 256 and adding the
result to the minor device number.
Normally rid and tid refer to the relation (table) number and tuple (record) number
that is locked. If either number is 0, it has meaning as shown in the following table:
State
Meaning
both rid = 0; tid = 0
The database is locked
only rid = 0
There is a resource lock, and tid is the ASCII value for the
type of lock (see lock_r in the DBMS Direct HLI
Programmer’s Manual).
only tid = 0
There is a table lock and the rid number is the number of
the locked table (see Data Dictionary Report: Table List).
The type lock held on this object. SLK represents shared locks and XLK
represents exclusive locks.
387
Using hash table statistics
If performance is slow during some hash key scans or inserts, it may be caused by an
improperly tuned hash table. The ACCELL/DBMS supports a utility that prints
statistics about the hash table.
The hash table should usually have 50% of the slots full and an average chain length
of less than 6. The longest chain length should not be greater than 100.
To generate the hash table statistics report, select Display Hash Table Statistics (hts)
from the database Maintenance Menu. The following figure shows an example of the
Display Hash Table Statistics report:
HASH TABLE STATISTICS
Total Entries
198
Per Cent Filled
2.00
Average Chain length ‘1.07
Longest Chain length
2
Starting Address
10520
Number of Chains of Length ...
2
3 4 5 6 7 8 9 10 >10
13
0 0 0 0 0 0 0 0 0
Figure 66. Example Hash Table Statistics Report
For larger tables, if the hash table fills up, or chains are longer than 100, increase the
number of expected records. Reconfigure the database and run Display Hash Table
Statistics again.
In rare cases a table or combination of tables can cause a full hash table or long
chains. In this case, try to use a unique B-Tree instead of a hash key. This is always
an option, because the DBMS supports multiple access methods (Pathfindert).
For more information on Hashing and Reconfiguration, refer to Chapter 2 of the
DBMS Direct HLI Programmer's Manual and Chapters 8 and 9 of the DBMS
Developer's Reference Manual.
388
Using code sections
Take care when inserting code in an ACCELL/IDS application. For example, if the ON
FIND code section contains a time-consuming block of code, finds may take longer to
process. This is because a great deal of work is required each time a record is added
to your new set. If you were to insert a block of code that averaged 0.05 seconds to
process in the ON FIND code section, and your find resulted in 5000 records,
ACCELL/IDS would spend over four minutes processing the code.
You should ask whether you really need to include such code in the ON FIND section.
Perhaps the WHEN FIELD CHANGES code section would be more appropriate. The
WHEN FIELD CHANGES will only process for records displayed on the screen.
Also take care with the ON NEXT RECORD and ON PREVIOUS RECORD code
sections, because they can slow the NEXT RECORD and PREVIOUS RECORD
operations.
Writing C functions
After your application is complete using the ACCELL/IDS Language, you should
examine the code. Look for sections that might be optimized by writing a C function.
A candidate for optimization would be a complicated pricing function that involves
many lookups and computations and which occurs frequently during a transaction.
However, there is no absolute rule which defines when you should write C functions.
Try using DISPLAY statements in your code to help determine where time is being
spent. If you use ifdef's, you can leave the statements in the code for future use. The
following example code shows how you can use ifdef:
389
#define DEBUG
...
AFTER FIELD
#ifdef DEBUG
display ‘before pricing-> ‘ + val_to_str$(current_time$())
for fyi_message wait;
#endif
(pricing function code)
#ifdef DEBUG
display ‘aftrer pricing -.’ + val_to_str$(current_time$())
for fyi_message wait;
#endif
Figure 12. Example Code Using ifdef
Other conditional statements can be used, such as #if, #ifndef, #else. The pound sign
(#) must always appear in field 1.
Checking the termcap entry
If forms seem to paint very slowly, or cursor movements seem very slow, check the
termcap entry for your terminal. It may have unnecessary or excessive pad characters
for various string capabilities. If you think this is the problem, reduce the number of
pad characters until none remain or other problems are introduced.
Checking the ndelaypad setting in unicap
If the application has a performance problem associated with input speed, you should
check the ndelaypad in the unicap file. The ndelaypad helps the ACCELL/IDS input
handler in executables distinguish between a group of characters sent by a function
key and a manual sequence typed in by a user. On heavily loaded systems or on
network systems, the size of ndelaypad can be increased. This ensures that a
function key command can always be recognized. If ndelaypad is set too high, input
appears slow. Usually, ndelaypad should have a value of 30 to 60.
390
Using browse feature
If the time between pressing FIND and getting a current set seems too slow, you can
try the Browse feature. Browse lets you specify by form the number of records added
to the selected set, before control is passed back to the user. If the user scrolls
through the set to the boundary, another batch equal to the first is added to the set.
This continues until no more records satisfy the search criteria.
This concept is similar to declaring a cursor and doing fetches in the Unify Embedded
SQL/A product, except that ACCELL/IDS can move back to previous records in the
set. This feature is ideal for inventory lookup forms in which, once the user finds the
appropriate part, the set is usually discarded. Forms that require a complete set for a
total or some other reason would not be appropriate for this feature. The following
example illustrates:
FORM INVENTORY
BEFORE FORM
SET INVENTORY:FIND_COUNT TO 25;
Using B-Tree indexes to avoid sorting
You can use B-Tree indexes to minimize sorting during the processing of an
application. For example, on the items form of an order items application, the user
does a global find of every item for the current order on the order form. These items
are usually sorted by item number. To avoid the sort, set up a B-tree with two
components, order and item number, in ascending order.
The optimizer then selects the B-Tree as the access method and since the items are
already in the correct order, no sort is performed. Take care to include both
components in the correct order in the B-Tree. Use list_scan to verify your results.
Memory optimization
This subsection describes tools that help you measure your application's memory use
and several ways to reduce memory requirements.
391
Environment variable settings
If your system does not support the number of users expected, or heavy swapping or
paging occurs, check your environment variable settings. Some commonly misused
environment variable parameters are described here.
heap_size
The heap_size parameter for the AMGRINIT environment variable
controls the size of the heap during processing of either the Generator
or the Manager. The heap is used to store strings.
The external size of the heap does not grow or shrink during
application processing. Internally, heap space is allocated, freed, and
compacted as needed. When applications become more complex or
have many string variables, the heap space may need to be
increased. The default size of the heap is 8k.
Even though the maximum size of the heap is 512k, only increase
heap_size incrementally until the problem goes away. If, for example,
heap_size is set to 100k and only requires 12k, then 88k of user data
space is wasted.
If your application runs for several iterations, then generates out of
heap space errors, you may have logic errors in your code.
stack_block_size
The stack_block_size parameter for the AMGRINIT environment
variable controls the size of stack blocks that are pushed and popped
from the ACCELL/IDS machine stack. The stack is where ACCELL/
IDS forms are located during execution of ACCELL/IDS applications.
The code for a single form must fit completely in one stack block. This
can be either the remaining space in a previously-allocated stack
block or in a new one. As more fields or more code accumulate, the
size of the form may exceed the default stack block size of 4k. If this
happens, increase stack_block_size incrementally until the form
processes.
If stack_block_size is the problem, the form cannot process. You could
set stack_block_size to a very large value, but that would be wasteful.
For example, if you set the size to 64k, and the total of all the forms in
your application require 65k, then two stack blocks would be
allocated, wasting 63k.
Transaction design
As ACCELL/IDS applications process, forms are pushed and popped from the
ACCELL/IDS machine stack. As transactions continue, the stack gets larger. When
new transactions begin, all forms from the previous transaction are popped. If your
application runs slower over time or increasingly uses more memory, perhaps the
transaction logic is incorrect. To illustrate, consider the following transaction diagram
392
based on the ACCELL/IDS tutorial:
Items Form
Cont Tx
Order Form
Cont Tx
Cont Tx
Company
Form
Tutorial
Form
Start Tx
Given the previous diagram, as this application processed, the form stack would
continue to grow with more copies of the company, order, and items forms. Each new
order would start with an empty set on the company form. The application also would
acquire more locks as orders were added. If the user decided after 5 orders to back
out of the application, using the command, there would be 15 forms to go through. A
better transaction diagram would be as follows:
Items Form
Cont Tx
Order Form
Restart Tx
Cont Tx
Company
Form
Tutorial
Form
Start Tx
This application would pop the order and items forms after each order, start a new
transaction, release the locks on the order and items forms and place the user back
on the company form with the same set as before.
393
Externalizing messages
As with any application, ACCELL/IDS applications must provide help, give error
messages, and communicate in other ways with the user. Including these messages
in the program text can use large amounts of memory space. If you want to provide
messages in several languages, the problem multiplies.
Often error messages never display during application processing, thereby wasting
the memory required to store them. for example, in a five-form application with twenty
80-character messages on each form, the application overhead for messages would
be 8k.
To alleviate this problem, create an external message file and use the message
ACCELL/IDS system functions. This way you can easily display messages in multiple
languages, or edit messages without recompiling. In addition, application memory
requirements can be reduced. You may decide to open the message file only when
required to avoid wasting a file descriptor, as shown in the following example:
open_message$("/usr/ACCELL/messages");
display get_message$(100) for fyi_message wait;
close_messages$();
UNIX-tunable parameters
If your system does not seem to support as many users as you might expect, check
the UNIX-tunable parameters to see if they are set properly for your system. UNIX lets
you specify the number of buffers (NBUF) for the buffer cache. This can reduce
access time considerably in many cases because the system finds what it needs in
memory instead of by accessing the disk.
In some cases, the buffer parameter is set too high, causing the system to swap.
Swapping is extremely expensive, negating any benefit received from finding data in
the buffer cache. You can use the sar command to determine the buffer cache hit ratio
and discover whether swapping is occurring.
Using UNIX tools to determine process size
You can use the UNIX utilities crash and ps to help determine your process size.
394
The ps command prints the size of the process in the SZ field of its output, as shown
in the following example:
FLAGS S UID PID PPID C PRI NI ADDR SZ WCHAN
TTY TIME COMD
108001 S dawn 1728 1723 0 26 20 1170 141 ffd35768 i25 0:08 AMGR
The value reported for SZ is the size in data blocks of the core image of the process. It
does not include the text portion of the process. The value reflects the process's static
and dynamic data memory use. In the above example, the data space used is
approximately 288,768 bytes. (141 * 2 * 1024–Assuming 2048 byte pages)
Some systems support the /etc/crash command, which can be used to obtain the text,
data, and bss memory use for a process. Consult your system guide for information
on how to use crash.
Diagnostic guide
This subsection contains a table of common performance or memory problem
symptoms and directions on where to look for more information.
If the symptom is ...
Then try using ...
Long delays moving from form to form
(init_mem_size parameter).
Screen design. Reduced code in ON NEXT
FORM
Finds taking too long
(sort_mem_size parameter)
Browse feature. list_scan. B-trees to avoid
sorting. Reduced code in BEFORE FIND.
Reduced code in ON FIND.
Reduced code in AFTER FIND.
Some Adds/Inserts take a very long time
Hash table statistics. Reduced code in AFTER
ADD. Reduced code in BEFORE ADD.
Long delays moving record to record
Reduced code in ON NEXT RECORD.
Process size too large, swapping occurring, or
system not supporting enough users
Memory optimization
Application runs progressively slower
Transaction design.
Locking.
Slow input or slow screen painting
termcap, unicap, or the input driver
395
9.8 Writing batch applications
Batch applications written with ACCELL/IDS are powerful and easy to write. All that is
required is that you create a blank master application form, create a language file with
the code in the ON NEXT FORM code section, and execute the application in the
background.
For example:
AMGR batchapp.al > /dev/null &
A sample application is presented at the end of this subsection for your reference.
Included is the code and a representation of the Master Application form and a shell
script that drives the application. The application is based on the ACCELL/IDS tutorial
application. It prints out all the current orders in the database.
Considerations
The following are considerations and performance suggestions when creating batch
applications with ACCELL/IDS:
1. The blank master application form should be made as small as possible to
optimize performance and minimize memory requirements.
2. The function key, status, and FYI lines should not be displayed since they will
not be used.
3. If there are no fields and borders displayed, it is not necessary to redirect
output to /dev/null. This will help the application do the minimum processing.
4. Since batch operations are run without operator intervention (for example,
night runs) you should pipe runtime status information and error messages to
a batch status file. The batch status file will help greatly when trying to
reconstruct the events of a failed run.
Batch status files are also useful in identifying where batch programs are
spending their time.
An example of a batch status file is presented below:
396
Batch Status Pipe Created|06/13/87|21:48
Data Pipe Created|06/13/87|21:48
Processing Order Number |10001|06/13/87|21:48
NORMAL TERMINATION|06/13/87|21:49
5. Batch programs should attempt to acquire all the resources they will need
before beginning to modify information. Batch programs, unlike interactive
programs, can not always try again or make another decision.
If your application will require certain files to be opened or certain tables read,
be sure to open or lock the files first and return a fatal error, if this fails, before
operating against data.
6. Checking status$() returns in batch programs is even more important than in
interactive programs. Use CASE statements if you wish to take specific actions
for specific status returns.
7. As with all applications, use external message files. External files will make
your code easier to maintain and reduce the amount of memory required to
execute your application.
Sample Application
The following is the the message file used with the sample batch application:
1|ABNORMAL TERMINATION
2|NORMAL TERMINATION
100|Error Pipe Created
200|Data Pipe Created
300|ERROR IN ORDER SELECTION, STATUS =
400|Processing Order Number
500|ERROR IN COMPANY SELECTION, STATUS =
600|ERROR IN ALTERNATE ADDRESS SELECTION, STATUS =
700|ERROR IN ITEM SELECTION, STATUS =
800|ERROR IN INVENTORY SELECTION, STATUS =
397
Excerpts from FRMDOC ouptut (after running it on the Master Application form) are
shown below. For purposes of the example, one field is present on the Master
Application form.
FORM batchapp
---------------|SSSSSSSSSSSSSS|
---------------FIELD
ACCELL/IDS DB
INP
WN
SFI
TAB REQ CASE
NAME
TYPE
FLD
LEN
WID
________________________________________________________________
indicator
STRING
N
14
14
F
F
F
N
# Batch Script to turn off unneeded interfaces and execute
# Batch Report.
#
AMGRINIT="fnkey_dsp=no mode_dsp=no border_dsp=no fyi_dsp=no"
export AMGRINIT
AMGR batchapp.al >/dev/null &
The Master Application form Language Script is shown below:
/***************************************************************
*
*
batchapp.as
*
*
FORM:
batchapp
*
DESCRIPTION:
*
*
AUTHOR:
dw
*
DATE:
June 12, 1987
*
REVIEWER:
*
*
MODIFICATION HISTORY:
*
Date
Author
Description
*
*
***************************************************************/
APPLICATION batchapp
FIELD indicator
BEFORE FIELD
NEXT ACTION IS NEXT FORM
398
ON NEXT FORM
/* Place the batch code in the on next form code
section of the master application form. Normally,
the master application form does an auto next form
when there are no fields on it so code can be made to
execute with no user input.In this case I have placed
a field on the form so that the application can be
run interactively and give the operator some
feedback. Therefore the field code sections and next
action statement became necessary.
Optionally, developers may wish to require a
keystroke to start the batch process.In this way the
application can be more easily controlled when
running interactively. To do this merely create a
keystroke file with the appropriate keystrokes in it
and when running batch redirect input into it.
*/
/* Open the message file. Fatal Error if unsuccessful.
*/
IF ((open_message_file$('batch_messages')) <> 0)
THEN
BEGIN
SET batchapp:$indicator to ' ABORTING';
REFRESH SCREEN; /* Needed so message is flushed */
sleep$(1);
NEXT ACTION IS EXIT
END
SET batchapp:$indicator to ' PRINTING';
/* Open a pipe to an error/message file so messages
about execution can be saved. Fatal Error.
*/ CREATE PIPELINE batchapp:errpipe 'cat' OUTPUT IS
'batch.out';
IF status$() <> 0
THEN
BEGIN
sleep$(1);
NEXT ACTION IS EXIT;
END
/* If you cannot open pipes there is not much
of a reason to continue
*/
/* Now write a message to the error file
399
*/
WRITE PIPELINE batchapp:errpipe
get_message$(100),
current_date$(),
current_time$();
/* Now open the data pipeline for the report
*/
CREATE PIPELINE
batchapp:datapipe 'RPT sorder.rpt -', 'lpr'
IF status$() <> 0
THEN
BEGIN
get_message$(100);
WRITE PIPELINE batchapp:$errpipe
get_message$(1)
close_message_file$();
CLOSE PIPELINE batchapp:errpipe
NEXT ACTION IS EXIT
END
/* If you cannot open pipes there is not much
of a reason to continue, but in this case
clean up first.
*/
get_message$(200),
current_date$(),
current_time$();
/* Select all orders */
SET batchapp:$ord_number,
batchapp:$ord_company,
batchapp:$ord_terms,
batchapp:$ord_fill_code,
batchapp:$ord_date,
batchapp:$ord_ship_via,
batchapp:$ord_sales_rep,
batchapp:$ord_alt_shipto,
batchapp:$ord_nxt_item
TO SELECT
orders.ord_number,
orders.ord_company,
orders.ord_terms,
orders.ord_fill_code,
orders.ord_date,
orders.ord_ship_via,
orders.ord_sales_rep,
400
orders.ord_alt_shipto,
orders.ord_nxt_item
FROM orders
EXECUTING
BEGIN
/* Check Status of order set select statement
*/
IF status$() <> 0 THEN
BEGIN
get_message$(300),
status$(),
current_date$(),
current_time$();
END
ELSE
BEGIN
get_message$(400),
batchapp:$ord_number,
current_date$(),
current_time$();
END
SET batchapp:$co_key,
batchapp:$co_name,
batchapp:$co_address_1,
batchapp:$co_city,
batchapp:$co_state,
batchapp:$co_zip_code,
batchapp:$co_phone,
batchapp:$co_sales_rep
TO SELECT
company.co_key,
company.co_name,
company.co_address_1,
company.co_address_2,
company.co_city,
company.co_state,
company.co_zip_code,
company.co_phone,
company.co_sales_rep
401
FROM company
WHERE company.co_key = batchapp:$ord_company
IF status$() <> 0
/* A fatal error */
THEN
BEGIN
get_message$(500),
status$(),
current_date$(),
current_time$();
get_message$(1);
CLOSE PIPELINE batchapp:datapipe
NEXT ACTION IS EXIT
END
IF batchapp:ord_alt_shipto = UNDEFINED
OR batchapp:ord_alt_shipto = 0
THEN BEGIN
/* Set the ship to address to the company address */
SET batchapp:alt_name TO batchapp:co_name
SET batchapp:alt_address_1 TO
batchapp:co_address_1
SET batchapp:alt_city_st_zip
TO batchapp:co_city + ', ' +
batchapp:co_state + ' ' +
batchapp:co_zip_code
END;
ELSE BEGIN
/* else select the alternate address from the
database */
SET batchapp:alt_name,
batchapp:alt_address_1,
batchapp:alt_city,
batchapp:alt_state,
batchapp:alt_zip_code
TO SELECT
altaddr.alt_name,
altaddr.alt_address_1,
altaddr.alt_city,
altaddr.alt_state,
altaddr.alt_zip_code
FROM altaddr
WHERE altaddr.alt_key = batchapp:ord_alt_shipto
IF status$() <> 0
/* Error */
402
THEN
BEGIN
SET batchapp:alt_name TO batchapp:co_name
SET batchapp:alt_address_1 TO
batchapp:co_address_1
SET batchapp:alt_city_st_zip
TO batchapp:co_city + ', ' +
batchapp:co_zip_code
/* Let System Administrator know */
get_message$(600),
status$(),
current_date$(),
current_time$();
END
ELSE /* Select worked so combine alternates */
SET batchapp:alt_city_st_zip TO batchapp:alt_city
+ ', ' + batchapp:alt_state
+ ' ' + batchapp:alt_zip_code
END;
SET ln_num,
batchapp:nv_num,
batchapp:quantity,
batchapp:price_qtd,
batchapp:qty_ship,
batchapp:status
TO SELECT
items.itm_line_number,
items.itm_stock_number,
items.itm_quantity,
items.itm_price_qtd,
items.itm_qty_shipped,
items.itm_status_code
FROM items
WHERE items.itm_order_number = batchapp:ord_number
ORDER BY items.itm_order_number ASCENDING,
items.itm_line_number ASCENDING
EXECUTING
BEGIN
IF status$() <> 0
/* A fatal error */
THEN
BEGIN
get_message$(700),
403
status$(),
current_date$(),
current_time$();
get_message$(1)
get_message$(1)
NEXT ACTION IS EXIT
END
SET batchapp:nv_description TO
SELECT nvntry.nv_description
FROM nvntry
WHERE nvntry.nv_num = batchapp:nv_num;
IF status$() <> 0
/* Error */
THEN
BEGIN
/* Revert to Default */
SET batchapp:nv_description TO
'General Inventory';
/* Let System Administrator know */
get_message$(800),
status$(),
current_date$(),
current_time$();
END
WRITE PIPELINE batchapp:datapipe
batchapp:$co_key,
batchapp:$co_name,
batchapp:$co_city + ', ' +
batchapp:$co_zip_code,
batchapp:$co_phone,
batchapp:$alt_name,
batchapp:$alt_address_1,
batchapp:$alt_city_st_zip,
batchapp:$ord_number,
batchapp:$ln_num,
batchapp:$nv_num,
batchapp:$nv_description,
batchapp:$quantity,
404
batchapp:$price_qtd,
batchapp:$qty_ship,
batchapp:$status,
batchapp:$ord_terms,
batchapp:$ord_ship_via,
batchapp:$ord_date
END; /* End Select Items */
END; /* End Select Orders */
get_message$(2),
current_date$(),
current_time$();
SET batchapp:$indicator to ' COMPLETE';
NEXT ACTION IS EXIT;
405
9.9 Customizing ACCELL/IDS error forms using PAINTHLP
After your application is complete, you may want to customize the error forms that can
appear when the application processes. For example, you may not want error
messages to refer to the ACCELL/IDS Language or to mention the heap. You can
tailor these error forms using the PAINTHLP command.
ACCELL/IDS error forms are stored in the SERRORS archive in the UNIFY lib
directory. Before you modify any error forms, make a backup of the SERRORS
archive.
ACCELL/IDS identifies error forms by the error number that appears in the upper right
corner of the error form. Do not remove this number. The error number will help you
communicate with Unify technical support should the need arise.
To modify ACCELL/IDS error forms, enter the following command:
PAINTHLP SERRORS
PAINTHLP asks if you want to add, modify, or delete ACCELL/IDS error forms.
Usually, you want to modify an existing error form. To modify an error form, enter "m".
PAINTHLP then asks you to enter a form name to modify. PAINTHLP also displays a
list of error form names with a summary of their contents. Enter the name of the form
name you wish to add, modify, or delete in the format:
SERR
2427
where 2427 is the error message number. Then press RETURN.
PAINTHLP displays the selected error form. You can edit the trim or resize the form
exactly as you did in the Generator. When you finish editing the form, use the ADD/
UPDATE command to save your changes. You can then enter the next form name to
edit.
406
PAINTHLP ERRORS
The following list shows the possible PAINTHLP errors with their error identification
numbers:
Error #
Error message
SERR2400
There are no errors to report.
SERR2401
There is not enough memory to activate the form.
SERR2402
The file is not in the proper format.
SERR2403
There has been an internal system error.
SERR2404
There is not enough memory to continue processing.
SERR2405
User has improper permission to access the file.
SERR2406
There has been an I/O error detected by the system.
SERR2407
There is no more memory available to create a new form.
SERR2408
The form cannot be displayed at the specified location.
SERR2409
The specified form cannot be found in the form archive.
SERR2410
An arithmetic overflow has occurred in a code section of the form.
SERR2411
An arithmetic underflow has occurred in a code section of the form.
SERR2412
The specified value is not in a correct DATE format.
SERR2413
The current operation requires more heap memory than available.
SERR2414
The specified file cannot be found.
SERR2415
The data types for this operation do not match.
SERR2416
The value's data type is incorrect for this operation.
SERR2417
A division by zero is not allowed.
SERR2418
The help form archive file cannot be found.
SERR2419
The help form cannot be found in the help archive file.
SERR2420
*** UNUSED ***
SERR2421
*** UNUSED ***
SERR2422
*** UNUSED ***
SERR2423
*** UNUSED ***
SERR2424
*** UNUSED ***
SERR2425
*** UNUSED ***
SERR2426
The form referenced in the code section is not active.
SERR2427
A reference has been made to a non-existent external symbol.
SERR2428
The referenced ACCELL/IDS help file cannot be found or is not readable.
407
408
Error #
Error message
SERR2429
The ACCELL/IDS help sub-system file cannot be found or is not readable.
SERR2430
The referenced help form has too many 'next forms' associated with it.
SERR2431
The referenced help form cannot be found in the description file.
SERR2432
The menu description is too long.
SERR2433
Too many menu descriptions.
SERR2434
No selected set.
SERR2435
This is the last record.
SERR2436
This is the first record.
SERR2437
This is the last set.
SERR2438
This is the first set.
SERR2439
The range specifier is invalid .
SERR2440
The justification specifier is invalid.
SERR2441
The current record is no longer in the database.
SERR2442
Cannot open the application '.al' file.
SERR2443
Cannot read the application '.al' file.
SERR2445
There is no 'next form' for this form.
SERR2446
There is no 'previous form'. Use EXIT to leave the application.
SERR2447
The referenced c-hook cannot be found in code.
SERR2448
Bad heap size parameter.
SERR2449
Bad number of forms parameter.
SERR2450
Bad stack block size parameter.
SERR2451
Unknown parameter.
SERR2452
Bad error file parameter.
SERR2453
A reference has been made to an invalid screen field name.
SERR2454
The referenced form is unknown to the Manager.
SERR2455
There was an error while comparing checksums for the referenced form.
SERR2456
The checksum could not be calculated.
SERR2457
Select one record error.
SERR2458
Main_help is missing.
SERR2459
The current record could not be locked. Try again later.
SERR2460
No screen attributes.
SERR2461
No target attributes.
SERR2462
A subtraction operation was attempted on strings from within code.
Error #
Error message
SERR2463
A string specified in code is too long.
SERR2464
ONE and EXECUTING.
SERR2465
Window does not exist.
SERR2466
Trim does not exist.
SERR2467
Bad case conversion.
SERR2468
The find operation is not allowed using this form.
SERR2469
The add operation is not allowed using this form.
SERR2470
The update operation is not allowed using this form.
SERR2471
The delete operation is not allowed using this form.
SERR2472
No operation on rid variable.
SERR2473
A RID variable type needed.
SERR2474
A call to pipe has failed.
SERR2475
A pipe closure has failed.
SERR2476
The file descriptor variable for a pipe must be an integer.
SERR2477
Output to a pipe has failed.
SERR2478
A pipeline fork has failed.
SERR2479
There has been abnormal pipeline member termination.
SERR2480
Too many or no pipeline tasks have been started.
SERR2481
Bad display justification type.
SERR2482
*** UNUSED ***
SERR2483
Bad arguments to system call.
SERR2484
There is no transaction to continue.
SERR2485
Bad display format.
SERR2486
Value is undefined.
SERR2487
Value type is bad.
SERR2488
Out of memory during display/format.
SERR2489
Bad format type.
SERR2490
Bad justification.
SERR2491
Bad boolean format.
SERR2492
Bad date format.
SERR2493
Bad time format.
SERR2494
Illegal default justification.
SERR2495
Truncated formatted value, buffer too short.
409
410
Error #
Error message
SERR2496
Cannot open the selected set temporary file.
SERR2497
Attempted an arithmetic operation with a null date.
SERR2498
Bad input character.
SERR2499
A field is required.
SERR2500
Bad sort descriptors.
SERR2501
A referenced form is not active. The transaction cannot be restarted.
SERR2502
There is an undefined boolean variable in a statement.
SERR2503
The CLEAR TO ADD command cannot be executed.
SERR2504
Unable to open the error file. Check file spelling and permissions.
SERR2505
Error in WRITE PIPELINE statement.
SERR2506
There was a bad type in type conversion.
SERR2508
The specified value is not in correct TIME format.
SERR2509
The specified value is not in correct BOOLEAN format.
SERR2510
The specified value is not in correct FLOAT format.
SERR2511
The specified value is not in correct NUMERIC format.
SERR2512
The specified value is not in correct AMOUNT format.
SERR2599
Exit the application.
Chapter 10: Runtime execution
10.1 Introduction
This section describes how ACCELL/IDS executes ACCELL/Language and user
commands. The information will be of interest primarily to experienced application
developers who need detailed information about how the ACCELL/Runtime
Environment works.
The introductory section begins by describing how ACCELL/IDS performs two
operations-CLEAR TO FIND and CLEAR TO ADD. After explaining how these
operations work, the introduction goes on to describe how ACCELL/IDS begins form
execution. The last part of the introduction describes the sequence of events after
form execution begins.
The last three parts of this section describe application, form, and field execution;
detail user mode execution; and provide notes on the execution of specific user
commands.
Clear To Find and Clear To Add operations
When the user presses CLEAR TO FIND, or ACCELL/IDS performs an implicit Clear
To Find, ACCELL/IDS discards the selected set and <evaluates all Clear To Find
expressions CLEAR_FIND_EXP variable attributes). The results are assigned to the
variables' Search Ranges Note that this evaluation changes the value of an attribute,
and not the value of the variable.
Similarly, when the user presses CLEAR TO ADD, or ACCELL/IDS performs an
implicit Clear To Add, ACCELL/IDS evaluates the Clear To Add expressions
CLEAR_ADD_EXP variable attributes) and assigns the values to the variables. If a
non-target field has a Clear To Add expression with a value of UNDEFINED, the field's
value does not change. Unlike Clear to Find, in Clear To Add, a variable's attribute is
evaluated, and the results change the value of the variable.
411
Execution of a form
When ACCELL/IDS begins executing a form, it performs three steps:
1. The value UNDEFINED is assigned to all variables.
2. ACCELL/IDS then assigns values to the variable attributes that have initial
values set in the ACCELL/Generator.
3. ACCELL/IDS executes all of the form's INIT FIELD sections, in an arbitrary
order, and then executes the BEFORE FORM Language section. The INIT
FIELD sections are executed only once upon entry into the form in the first
Find mode.
What ACCELL/IDS does next depends on how two form attributes - AUTO_FIND
(automatic Find) and AUD_ON_ENTRY (Add, Update, Delete on entry) are set.
ACCELL/IDS first tests the AUTO_FIND attribute:
•
If AUTO_FIND is TRUE, ACCELL/IDS performs a Clear To Find. After all
variables have search ranges, ACCELL/IDS performs a Find.
•
If AUTO_FIND is FALSE, ACCELL/IDS tests the AUD_ON_ENTRY attribute. If
AUD_ON_ENTRY is TRUE, ACCELL/IDS evaluates the Clear
To Add expressions of all form variables and enters Update mode. If
AUD_ON_ENTRY is FALSE, ACCELL/IDS performs a Clear To Find and enters Find
mode.
The default value for both attributes is FALSE<#010a>ACCELL/IDS performs a Clear
To Find and enters Find mode.
Find and Add/Update/Delete modes
After initializing the form, ACCELL/IDS will be in either Find or Add/Update/Delete
mode, depending on how AUTO_FIND and AUD_ON_ENTRY were set.
When ACCELL/IDS enters Find mode, it waits for input to the first target field. At this
point the user is in control. An ACCELL/IDS Standard form must have at least one
screen field for the cursor to stop on. If Find mode is to be used, the Standard form
must also have a target field. It is legal to have no fields on a Master Application form.
412
Similarly, when ACCELL/IDS enters Update mode it performs the BEFORE FIELD,
ON FIELD, and AFTER FIELD Language sections for each form field until it reaches a
field with a STOP_FOR_INPUT attribute set to TRUE. At this point, the user takes
control.
If all fields on a form have STOP_FOR_INPUT set to FALSE or if there are no fields
defined at all, the ACCELL/Manager will keep searching for a field to stop on. The
form processing will be caught in an infinite loop. Likewise, if all tab stop fields have
STOP_FOR_INPUT set to FALSE, the Manager will loop continuously, looking for a
tab to stop on.
Find mode
In Find mode, ACCELL/IDS will accept any commands except ADD/UPDATE,
DELETE RECORD, and the record movement commands, such as NEXT RECORD.
Thus, the user could move on to the next form, enter search criteria, perform a FIND,
do a CLEAR TO FIND or perform a CLEAR TO ADD to enter Add/Update/Delete
mode. The diagram in Figure 67 illustrates the options a user has in Find mode:
ANY OTHER
COMMANDS
EXCEPT
CLEAR TO FIND
ADD/UPDATE
DELETE RECORD
EANTER
SEARCH
CRITERIA
USER
RECORD
MOVEMENT
COMMANDS
NEXT FORM
PREVIOUS FORM
FIND
CLEAR TO ADD
NEXT FIELD
PREVIOUS FIELD
NEXT TAB
PREVIOUS TAB
NEXT FIELD
PREVIOUS FIELD
Runtime execution
413
In Add/Update/Delete mode, the user may perform any command except a FIND. A
CLEAR TO FIND command done in Update mode changes the mode to Find. The
diagram in Figure illustrates the user's options in Add/Update/Delete mode:
ANY OTHER
COMMANDS
EXCEPT
FIND
ENTER NEW
INFORMATION
USER
CHANGE
EXISTING
INFORMATION
ADD/UPDATE
NEXT FIELD
PREVIOUS FIELD
The next section describes how ACCELL/IDS executes FIND, ADD, UPDATE, and
DELETE RECORD commands. A FIND command can only be done in Find mode.
Similarly, ADD/UPDATE and DELETE RECORD commands can only be performed in
Add/Update/Delete mode.
Find, Add, Update, and Delete Execution
When ACCELL/IDS performs a FIND on a form, it begins by executing the BEFORE
FIND Language section. When the BEFORE FIND section is finished, the actual FIND
is performed. For each record found each record that meets the search criteria
ACCELL/IDS executes the ON FIND Language section once.
414
When the search is complete, ACCELL/IDS executes the AFTER FIND Language
section. If records were found during the search, the application enters Update mode.
If no records were found, ACCELL/IDS remains in Find mode.
ADD and UPDATE are actually a single command, ADD/UPDATE. ACCELL/IDS
determines from the context whether an ADD or an UPDATE will be performed.
Although ADD/UPDATE is a single command, different execution sequences are
followed, depending on the actual operation.
Performing an Add in response to an ADD/UPDATE causes execution of the BEFORE
ADD Language section. When the section is finished, ACCELL/IDS adds the record to
the database and then performs the AFTER ADD Language section.
Similarly, when performing an Update in response to an ADD/UPDATE command,
ACCELL/IDS executes the BEFORE UPDATE Language section, performs the
Update on the database, and executes the AFTER UPDATE Language section.
Performing a DELETE in response to a DELETE RECORD command produces a
similar execution sequence – BEFORE DELETE Language section, delete performed
on the database, execution of AFTER DELETE Language section.
NOTE:
Runtime execution
When the last record of the selected set is deleted, the Manager
performs an implicit CLEAR TO ADD command. If an ON CLEAR TO
ADD section exists in the current form's script, this section is executed.
415
10.2 Application, Form and Field execution
The previous sections outline how ACCELL/IDS executes a single form, how user
modes are initially selected, and how ACCELL/IDS performs CLEAR TO FIND,
CLEAR TO ADD, FIND, ADD/UPDATE and DELETE RECORD user commands. This
section describes how an application as a whole executes, how ACCELL/IDS
performs some specific form control sections, and how field control sections are done
for individual form fields.
Application execution
The ACCELL/Manager handles application execution. The Manager maintains the
runtime environment which executes forms and their screen fields, evaluates
expressions, and controls transactions and database access. An application's
execution sequence is controlled by the information specified in the ACCELL/
Generator and in the application's ACCELL/Language scripts, as well as by
commands entered by the user.
When an application begins, the first form to appear is the Master Application form, a
special form that serves as an application's entry point. The Master Application form
is always the first form displayed. The next form displayed is the one specified in the
ACCELL/Generator, or specified in the CHOOSE FIRST FORM Language section if
the section appears in the Master Application Language script. The CHOOSE FIRST
FORM section, if present, overrides any specifications in the ACCELL/Generator.
After the first form, application execution consists of choosing among one or more
candidate forms specified in either the ACCELL/Generator or the CHOOSE NEXT
FORM section of the executing form. The CHOOSE NEXT FORM section, if present,
overrides any specifications in the ACCELL/Generator.
The application end user controls the execution sequence by zooming to other forms,
choosing among multiple next forms, or backing up to previous forms or fields. Any
zooms that the application user performs are part of the current transaction.
More specifically, when an application runs, the ACCELL/Manager performs the
following tasks:
416
•
Clears the system area of the screen
•
Performs the INIT FIELD sections of the Master Application form script
•
Executes the BEFORE APPLICATION section of the Master Application form
script, if present
•
Executes sections of the Master Application form script
•
Repeatedly selects Standard forms to execute and executes scripts
associated with each form
•
For the current form, repeatedly executes the Field control sections for each
field on the form and executes user commands
•
Executes the AFTER APPLICATION section of the Master Application form
script, if present, before ending the application. Applications end because of
an ABORT APPLICATION user command, a CHOOSE NEXT FORM section
with an EXIT option, a NEXT ACTION IS EXIT statement, or a PREV FORM
command from the Master Application form.
The ABORT APPLICATION command does not execute the AFTER
APPLICATION section. ABORT APPLICATION executes the ON EXIT section
of the current form, if it exists.
Form execution
An individual form's execution sequence depends on the expressions and attributes
specified in Language and the ACCELL/Generator, as well as the sequence of
commands entered by the user. However, there are some general rules that apply to
the execution sequence of all forms.
To execute a form, ACCELL/IDS first does the following:
•
Initializes the form as specified in the ACCELL/Generator
•
Executes all INIT FIELD Language sections in arbitrary order
•
Performs the form's BEFORE FORM Language
Next, ACCELL/IDS performs these steps:
•
Cycles through the form's fields, executing any appropriate Field Control
Language sections along the way (In Find mode, ACCELL/IDS cycles through
the target table fields only.)
Runtime execution
417
•
Executes any user commands and their associated Language sections
•
Executes the form's ON NEXT FORM Language section, and chooses the
next form to execute if the user enters a NEXT FORM command or a NEXT
ACTION IS NEXT FORM statement is executed
The sections that follow describe the form sections related to Find execution, and
discuss the Form control sections involved in selecting the next form and its
transaction level.
NOTE:
Master Application forms are executed just like Standard forms except
that they have no target table.
Form Language related to Find
This section contains execution notes on the form control sections executed by a
FIND command BEFORE FIND, ON FIND, and AFTER FIND.
Before Find Language section
No Clear To Find expressions are evaluated in this section. Assignments may be
made to CLEAR_TO_FIND attributes in this section but they will not be evaluated until
the next time the form is executed or a CLEAR TO FIND is performed.
Search ranges can be directly set in the BEFORE FIND Language section.
There are some special conditions that affect the BEFORE FIND Language section.
These are outlined in the following list:
•
Because there are no target record variables until ACCELL/IDS performs a
successful FIND or CLEAR TO ADD it is an error to assign a value to a target
variable in the BEFORE FORM or INIT FIELD Language sections.
•
Screen variables that have a value of UNDEFINED are displayed as blanks in
the screen field window
•
For string valued target variables, you can use the Unify DataServer/ELS
metacharacters in search values
On Find Language section
418
The ON FIND Language section can be thought of as the body of a loop that executes
once for each record found. Within the ON FIND section, each newly found record is
treated as if it were the current record. Its values can be obtained through the target
record variables.
This is the only section that may contain a REJECT RECORD statement.
After Find Language section
The AFTER FIND Language section executes after the database search is
completed.
Next Form Language sections
On Next Form Language section
This Language section executes whenever the user issues a NEXT FORM command,
or a NEXT ACTION IS NEXT FORM statement processes.
Choosing the Next Form to execute
After the ON NEXT FORM Language section, the ACCELL/Manager looks for the
CHOOSE NEXT FORM Language section and executes it. If there is no CHOOSE
NEXT FORM section, the Manager uses the current form's Choose Next Form
characteristics from the ACCELL/Generator to determine the next form.
CHOOSE NEXT FORM section execution consists of selecting the next form by
evaluating the WHEN expressions in the NEXT FORM statements. The next form is
chosen as follows:
•
If more than one WHEN expression is true, the ACCELL/Manager
automatically displays a menu of forms using the menu label specified in the
ACCELL/Generator.
•
If only one WHEN expression is true, ACCELL/IDS chooses the form specified
in that expression.
•
If none of the WHEN expressions are true, ACCELL/IDS displays an error
message.
Runtime execution
419
Once ACCELL/IDS determines which form to execute, it evaluates any special criteria
for that form, such as any transaction level information, and begins execution of the
form.
Transaction levels
The NEXT FORM statements set the transaction level of the next form. The following
sections contain execution information for those clauses that change the transaction
level.
START TX RECORD_CONSISTENCY starts a new transaction at the level of current
record consistency. The following conditions are true for current record consistency:
•
Records added or updated by the current transaction, but not yet committed,
cannot be updated by other transactions.
•
Other transactions may not change the current record of this transaction.
At the current record consistency level, the current record does not change so long as
it remains current. Other records in the current set may change unpredictably. The
current record is share locked (SLOCK).
START TX SET_CONSISTENCY starts a new transaction at the selected set
consistency level. The following conditions are true for selected set consistency:
•
Records updated by the current transaction, but not yet committed, cannot be
updated by other transactions.
•
Other transactions may not change records in the form's selected set.
Records that a transaction has read will not change. If a record is read twice, the
same information will be retrieved each time.
All records in the selected set are SLOCKed. If records are encountered that
someone else has XLOCKed, they cannot be SLOCKed. In this case, the user is
informed of the conflict and is asked to choose whether to wait or to abort the
transaction. All locks are retained until the end of the transaction unless explicit
UNLOCKs are performed. Only SLOCKed records can be unlocked by UNLOCK
statements.
420
Field Execution
Field execution is the process of executing each field's Language sections. As each
field executes, ACCELL/IDS does the following:
•
Performs the BEFORE FIELD Language section, where field initialization
takes place.
•
Executes the ON FIELD Language section, where ACCELL/IDS accepts and
checks input from the user.
•
Executes the WHEN FIELD CHANGES Language section if the value of a
screen variable changes (WHEN FIELD CHANGES is executed only after ON
FIELD execution ends).
•
Executes the AFTER FIELD Language section, where accepted input is
processed.
Choosing the Next Field to execute
Two attributes affect the next field selection: the form attribute CUR_NEXT_FIELD
and the current field's NEXT_FIELD attribute. When ACCELL/IDS selects the next
field it simply looks at the value of the CUR_NEXT_FIELD form attribute and begins
execution of that field. However, several things may change the CUR_NEXT_FIELD
value.
Without an explicit assignment, the CUR_NEXT_FIELD attribute tracks the current
field's NEXT_FIELD value. Because a form's NEXT_FIELD attributes are initialized to
values specified in the ACCELL/Generator, this produces a default field order.
There are two ways to change the field order: assigning a field name to the
CUR_NEXT_FIELD form attribute or assigning a field name to a field's NEXT_FIELD
attribute.
An assignment to the form attribute CUR_NEXT_FIELD will remain in effect only until
the next field is entered. Thus, changing field order by making an assignment to
CUR_NEXT_FIELD can be thought of as a temporary change in the order.
Changing the value of a field's NEXT_FIELD attribute will, like an assignment to
CUR_NEXT_FIELD, change the field order because it results in the value of
CUR_NEXT_FIELD being changed when the field is executed. (Remember that
Runtime execution
421
CUR_NEXT_FIELD determines the next executed field and that CUR_NEXT_FIELD
tracks the value of the current field's NEXT_FIELD.
When a field's NEXT_FIELD attribute is modified, the change remains in effect for the
duration of the form. A field's NEXT_FIELD attribute value may be changed in any
Language section.
NOTE:
Modifying the value of the NEXT_FIELD attribute can be used to
produce conditional field orders in response to user input. This feature
can also produce disarray if used carelessly.
For example, the default ACCELL/Generator field order is arranged so the fields form
a loop, with the last field's next field set to the first field on the form. Carelessly
changing the next field attribute for the last field can make it impossible to get to some
fields using the NEXT FIELD or PREV FIELD commands.
Tab fields
Tab fields are found by following the current next field ordering until a field with the
TAB_STOP attribute set to TRUE is found. Tab fields are specified in the ACCELL/
Generator. They provide quicker access to frequently used fields.
Previous field order and the field order chain
The field order chain controls the previous field order. The chain keeps track of the
fields the user has moved the cursor to. The chain only records a field's last
occurrence. This may result in the previous field order changing. For example, for the
execution sequence field 1 > field 2 > field 3 > field 4 > field 2, the previous field for
field 2 becomes field 4.
Interactions between fields
When writing WHEN FIELD CHANGES sections, be sure you avoid creating a
situation in which two fields interact. If two fields modify each other in their WHEN
FIELD CHANGES sections, an infinite recursion may take place.
422
NOTE:
Do not modify the current field's value in the field's WHEN FIELD
CHANGES section. Modifying the value in the section will produce an
infinite loop.
Field display
The display format, the screen window length, and the justification specification
determine how information appears in a screen field. Every screen field has a display
format. The default display format is set in the ACCELL/Generator when the form is
created. This format can be changed by the DISPLAY statement's format specification
or by making an assignment to the screen attribute DISPLAY_FORMAT.
The screen window length is set in the ACCELL/Generator and interacts with the
display format. If the display format is longer than the window length, then the user will
have to scroll the field left or right in order to see the entire field. If the format length is
shorter than the window length, then the justification specification determines the
position of the information in the field.
The justification specification can be set in the ACCELL/Generator, in the DISPLAY
statement, or by assigning LEFT, RIGHT, or CENTERED to the screen attribute
DISPLAY_JUSTIFY.
Runtime execution
423
10.3 User Modes execution
ACCELL/IDS follows different execution sequences in the two user modes, Add/
Update/Delete (AUD) and Find. In general, users spend most of their time in AUD
mode, occasionally entering Find mode to retrieve a set of records. The next two
sections outline the execution sequences for the two modes.
There are three execution steps in Add/Update/Delete mode that are repeated until a
CLEAR TO FIND command is issued.
1. Initialization
First Case – if there is no selected set, an implicit Clear to Add is performed.
When a Clear to Add occurs the following takes place:
•
All variables' Clear to Add expressions are evaluated and the results
become the values of the variables.
•
If present, the ON CLEAR TO ADD Language section is executed.
•
Field Language sections are executed until ACCELL/IDS encounters a
field with STOP_FOR_INPUT set to TRUE.
Second Case – if there is a selected set, the application user may move
through it using the Record and Field user commands.
2. Input/Recall – After initialization, the user may enter or recall field data.
3. Command Execution – At any point the user may enter commands. Four
commands – ADD/UPDATE, DELTE RECORD,CLEAR TO ADD, and CLEAR
TO FIND – affect the execution order:
•
If an ADD/UPDATE command is issued, the added or updated record
becomes the new current record. Any new record is added to the end of
the selected set.
After the Add/Update, ACCELL/IDS returns to step one. If a Clear to Add was
done in step one and the CLEAR_AFTER_AU form attribute is TRUE, the
program returns to step one as if there were no current set (step one, first
424
case). Returning this way allows for continuous data entry. In any other case,
the program goes back to step one, second case.
•
If a DELETE RECORD command is issued, it removes the current record
from the current set and the database. The next record, as determined by
the display order, becomes the current record. If the last record in the set is
deleted, the previous record becomes the current record. ACCELL/IDS
then returns to step one. A lock held by another transaction or referential
integrity constraints may prevent the record from being deleted.
•
If a CLEAR TO ADD command is issued, it sends ACCELL/IDS back to
step one, first case.
•
If the user issues a CLEAR TO FIND command, ACCELL/IDS exits Add/
Update/Delete mode and starts Find mode. The selected set is canceled.
Find mode
Find mode works in three major steps. The sequence followed after the third step
depends on the search results or on the command given.
1. Initialization – all Clear to Find expressions of target variables are evaluated
and the results are assigned to the variables' search range attributes. Those
values with no default Clear to Find expressions have their search ranges set
to UNDEFINED. All screen fields not linked to target record fields are set to
blanks.
2. Specifying Search Criteria – after the form is initialized, the user may specify
search criteria for the target fields by positioning the cursor on a field and
making an entry.
3. Execution of Find – when the FIND command is issued, ACCELL/IDS
searches the database for all records that match the search criteria. (For the
Browse feature, ACCELL/IDS searches the first subset of records. The
number of records in the subset is specified in FIND_COUNT. See Chapter 4
for more information about Browse.)
•
If the search succeeds, the set found becomes the selected set and
ACCELL/IDS enters Add/Update/Delete mode.
•
If the search fails – there is an error message or there are no records
found – ACCELL/IDS stays in Find mode, the search criteria entries
remain on the screen and the process continues with step two.
Runtime execution
425
Find itself can be operated in two modes for STRING field searches:
•
explicit mode
•
default mode
In explicit mode, searches are performed for the exact match to the search criteria.
The asterisk (*) is not appended to the end of the search criteria.
In default mode, searches are performed by appending an asterisk (*) to the end of
the search criteria if the criteria does not end in a metacharacter. If a metacharacter is
the last character of the search criteria, the search is performed explicitly.
For more information on the two Find modes see Chapter 4.4, under Explicit and
Default Search Modes.
426
10.4 User command execution notes
This section includes execution notes only for those commands that have a complex
execution sequence. The commands discussed in this section are listed below.
CLEAR TO ADD
CLEAR TO FIND
FIND
NEXT FIELD
NEXT FORM
PREVIOUS FIELD
PREVIOUS FORM
PREVIOUS TAB
RECALL FIELD
TAB
CLEAR TO ADD
The execution sequence for the CLEAR TO FIND command is as follows:
If an ON CLEAR TO ADD section for the form exists, the section is processed.
If the form's first field has a STOP_FOR_INPUT attribute with a value of FALSE
(display-only), then all of the field's associated sections are executed. This is done for
any succeeding display only fields until ACCELL/IDS finds the first input field.
Next, ACCELL/IDS executes the BEFORE FIELD section of the first input field. Then
it executes the ON FIELD Language section of first input field up to the INPUT
statement.
CLEAR TO FIND
CLEAR TO FIND begins Find mode after it does the following:
•
Processes any ON CLEAR TO FIND
•
Language sections for the current form.
•
Fills all screen fields not linked to the target database with blanks.
Runtime execution
427
•
Evaluates the Clear to Find expressions of all variables to establish each
field's default search range.
The cursor stops at the first target table field where Stop for Input is set to TRUE,
FIND ACCELL/IDS performs Finds automatically if a form is entered with the
AUTO_FIND attribute set to TRUE.
FIND
ACCELL/IDS performs Finds automatically if a form is entered with the AUTO_FIND
attribute set to TRUE.
Clear to Find values and search ranges establish the limits on a Find and can usefully
be set several places in an application:
•
Assignments can be made to CLEAR_TO_FIND attributes in the INIT FIELD
or BEFORE FORM section. These assignments will be overridden if
AUTO_FIND is TRUE.
•
Search ranges may be directly specified in the BEFORE FIND section. These
search ranges override any user entered ranges.
•
Clear to Find expressions may appear in the ON FIND Language section but
will not affect the Find criteria until another Clear to Find is done.
Search ranges established by executing the BEFORE FIND section replace the
corresponding search ranges derived from Clear to Find expressions as well as user
entered search ranges.
Also, when FIND is entered, ACCELL/IDS accepts the information in the current input
field as part of the search criteria before beginning the Find.
Find execution involves the following sections and steps:
428
•
Executes BEFORE FIND section.
•
Performs Find, executing ON FIND section for each record. (For the Browse
feature, ACCELL/IDS searches the first subset of records. The number of
records in the subset is specified in FIND_COUNT. See Chapter 4 for more
information about Browse.)
•
Executes AFTER FIND section.
•
Executes all leading display only fields before first input field.
•
Performs BEFORE FIELD section of first input field.
•
Executes ON FIELD section of first input field up to the point where input is
required.
NEXT FIELD
NEXT FIELD performs the following steps:
•
Accepts data in the current field.
•
Performs any remaining ON FIELD section.
•
Executes WHEN FIELD CHANGES section, if necessary.
•
Executes AFTER FIELD section.
•
Executes any leading form display-only (STOP_FOR_INPUT is set to FALSE)
fields.
•
Performs BEFORE FIELD section of the next field.
•
Executes ON FIELD section of the next field up to the point where input is
required.
NEXT RECORD
NEXT RECORD performs the following steps:
•
Interrupts current field's ON FIELD section.
•
Processes ON NEXT RECORD section.
•
Activates the next record. (For the Browse feature, this may involve retrieving
the next subset of the selected set.)
•
Performs any Language for leading form fields with STOP_FOR_INPUT set to
FALSE.
•
Executes BEFORE FIELD section of the first input field.
•
Executes ON FIELD section of the first input field up to the point where input is
expected.
Runtime execution
429
NEXT FORM
NEXT FORM performs the following steps:
•
Suspends input in ON FIELD Language section.
•
Executes ON NEXT FORM Language section.
•
Performs CHOOSE NEXT FORM section.
•
Activates newly chosen form.
•
Performs the INIT FIELD sections.
•
Executes BEFORE FORM section.
•
FALSE.
•
•
Performs ON FIELD section of the first input field up to the point where input is
expected.
NEXT SET
For a single-occurrence form, NEXT SET works like NEXT RECORD. For a multioccurrence form, NEXT SET performs the following steps:
430
•
Interrupts current field's ON FIELD Language section.
•
Executes ON NEXT RECORD Language section.
•
Activates the next current set on the form.
(For the Browse feature, this may involve retrieving the next subset of the
selected set.)
•
Makes the first new record displayed the current record.
•
FALSE.
•
•
expected.
PREVIOUS FIELD
PREVIOUS FIELD performs the following steps:
•
•
Executes any remaining ON FIELD section.
•
Performs WHEN FIELD CHANGES section.
•
Executes AFTER FIELD section.
•
Performs BEFORE FIELD section of the previous input field.
•
Executes ON FIELD section of the previous field up to the point where input is
required.
PREVIOUS RECORD
PREVIOUS RECORD performs the following steps:
•
•
Processes ON PREVIOUS RECORD section.
•
Activates the previous record. (For the Browse feature, this may involve
retrieving the previous subset of the selected set.)
•
FALSE.
•
•
Executes ON FIELD section of the first input field up to the point where input is
expected.
PREVIOUS FORM
PREVIOUS FORM performs the following steps:
•
Executes ON PREVIOUS FORM section if not a Zoom form.
•
Performs AFTER ZOOM section if current form is a Zoom form.
•
Deactivates the current form.
Runtime execution
431
•
Performs AFTER FORM RETURN section of the previous form.
•
Resumes execution of the previously suspended input of previous form's ON
FIELD section.
On a Master Application form, PREV FORM, exits the application after performing the
AFTER APPLICATION section.
PREVIOUS SET
For a single-occurrence form, PREV SET works like PREV RECORD. For a multioccurrence form, PREVIOUS SET performs the following steps:
•
•
Executes ON PREVIOUS RECORD Language section.
•
Activates the previous current set on the form. (For the Browse feature, this
may involve retrieving the previous subset of the selected set.)
•
Makes the last new record displayed the current record.
•
FALSE.
•
•
expected.
PREVIOUS TAB
PREVIOUS TAB performs the following steps:
432
•
•
•
•
Performs AFTER FIELD section.
•
Executes BEFORE FIELD section of the previous. tab stopped field.
•
Performs ON FIELD section of the previous tab stopped field up to the point
where input is required.
RECALL FIELD
When RECALL FIELD is used, ACCELL/IDS determines the previous value as
follows:
•
If the last operation was an Add/Update or Delete, the previous value is taken
from the corresponding field in the record just Add/Updated or Deleted.
•
Under any other conditions a previous value does not exist.
TAB
TAB performs the following steps:
•
•
•
•
Performs AFTER FIELD section.
•
Executes BEFORE FIELD section of the next tab stopped field.
•
Executes ON FIELD section of the next tab stopped field.
•
Continues the sequence until encountering a field with STOP_FOR_INPUT
set to TRUE.
Runtime execution
433
434
Appendix A: ACCELL/Language
grammar
A.1 Introduction
This appendix contains a complete grammar for the ACCELL/Language. The
grammar is organized into six sections:
ACCELL/Language Scripts
Describes the declarations appearing at the beginning of a Language
script. A script begins with declarations for user functions, form name,
target table, and local variables. Specific Language sections such as
BEFORE ADD and ON FIELD make up the rest of the form.
Language Sections
Describes the major divisions of a Language script. A script is divided
into sections that apply to the application, a form, specific fields, or
user commands. Such sections include AFTER APPLICATION,
BEFORE FORM, INIT FIELD, and ON FIND.
Statements
Contains descriptions of ACCELL/Language statement blocks,
statement lists, individual statements, and specifiers used in
statements. Statements are used in Language sections to perform
many tasks: data base operations, screen display control, managing
the sequence of forms, and so on. Specifiers appear in a separate
subsection.
Expressions
Describes ACCELL expressions and lists all operators. Expressions
are parts of ACCELL statements and are evaluated during statement
execution. Operators are described in a separate subsection.
435
Variables and Constants
Describes ACCELL variables, identifiers, and constants. Variables,
constants and identifiers include form and screen variables, function
names, and numeric constants.
Attributes, Characteristics, and System Functions
Contains alphabetical lists of ACCELL attributes, form and field
characteristics, and system functions.
Attributes describe the properties of ACCELL variables and forms.
Applications can test any ACCELL attribute and can change many
attribute values during execution.
Characteristics document specific field and form attribute settings.
ACCELL system functions let you conveniently perform such
operations as manipulating strings and converting data types.
How to use the grammar
The syntax of most ACCELL sections, statements, and expressions can be found by
turning to the appropriate section. Other elements can be located as follows:
•
All elements ending with expression or operator appear in the Expressions
section.
•
Any elements ending with name appear under Variables and Constants.
•
A grammatical element ending with list appears with the corresponding item.
For example, expression_list appears with expression in the Expressions
section.
•
An element ending with spec appears under Specifiers.
•
Elements like IDENTIFIER, that are not reserved words but are part of the
grammar, are defined in Variables and Constants.
Typographical conventions
The grammar uses the following special symbols:
436
Unify DataServer/ELS Developer’s Reference
[]
Square brackets enclose optional elements. Brackets only identify
optional elements; they are not part of a statement.
*
An asterisk follows an item that appears zero or more times. The
asterisk is not part of the statement.
+
A plus sign appears after items that may appear one or more times.
The plus sign is not part of the statement.
()
All parentheses, except where noted, enclose a list of alternative items
and are not part of the statement.
|
A vertical bar indicates alternative elements. For example, (item1 |
item2 | item3) means you can use one of the elements item1, item2, or
item3. The vertical bar, except where noted, is not part of the
statement.
;
All semicolons are part of the statement or expression. A semicolon
ending a statement may be omitted.
ACCELL/Language grammar
437
A.2 ACCELL/Language scripts
This subsection describes the declarations appearing at the beginning of a Language
script. A script begins with declarations for user functions, form name, target table,
and local variables. Specific Language sections such as BEFORE ADD and ON
FIELD make up the rest of the form.
language_script ‘
user_function_declaration* [form]
user_function_declaration ‘
EXTERN C
(type_spec | VOID) FUNCTION function_name
( [[RESULT] variable_name [, [RESULT] variable_name]*] );
NOTE:
The final pair of parentheses is part of the statement.
form ‘
master_application
| standard
master_application ‘
mastapp_header
[form_characteristics]
mastapp_body
mastapp_header ‘
APPLICATION application_name;
[REQUIRED FORMS form_decl [, form_decl ]*; ]
NOTE:
The REQUIRED FORMS statement is required if the application
contains any Standard forms.
form_decl ‘
form_name IN 'archive_name.fa'
438
mastapp_body ‘
[before_application] [after application]
[choose_first_form]
[either_body]
standard ‘
standard_header
[form_characteristics]
standard_body
standard_header ‘
FORM form_name [TARGET_TABLE table_name] ;
[LOCAL local_variable_list];
local_variable_list ‘
variable_name [, variable_name]* ;
standard_body ‘
[choose_next_form ]
[before_add] [after_add]
[before_delete] [after delete]
[before_find] [on_find] [after_find]
[before_update] [after_update]
[on_clear_to_find]
[on_clear_to_add]
[on_previous_record]
[on_next_record]
[either_body]
either_body ‘
[before_form]
[screen_field]*d
[on_next_form]
[after_form_return]
[on_exit]
[after_zoom]
[on_previous_form]
439
A.3 Language sections
after_add‘
AFTER ADD statement_list
after_application‘
AFTER APPLICATION statement_list
after_delete‘
AFTER DELETE statement_list
after_find‘
AFTER FIND statement_list
after_form_return‘
AFTER FORM RETURN statement_list
after_update‘
AFTER UPDATE statement_list
after_zoom
AFTER ZOOM statement_list
before_add‘
BEFORE ADD statement_list
before_application‘
BEFORE APPLICATION statement_list
before_delete‘
BEFORE DELETE statement_list
before_find‘
BEFORE FIND statement_list
440
before_form‘
BEFORE FORM statement_list
before_update‘
BEFORE UPDATE statement_list
choose_first_form ‘
CHOOSE FIRST FORM (next_form_statement*)
choose_next_form‘
CHOOSE NEXT FORM (next_form_statement*)
on_clear_to_add‘
ON CLEAR TO ADD statement_list
on_clear_to_find‘
ON CLEAR TO FIND statement_list
on_exit‘
ON EXIT statement_list
on_find‘
ON FIND statement_list
on_next_form‘
ON NEXT FORM statement_list
on_next_record‘
ON NEXT RECORD statement_list
on_previous_form ‘
ON PREVIOUS FORM statement_list
on_previous_record‘
ON PREVIOUS RECORD statement_list
screen_field‘
FIELD screen_field_name
[field_characteristics]
441
([AFTER FIELD statement_list]
| [INIT FIELD statement_list]
| [BEFORE FIELD statement_list]
| [ON FIELD statement_list]
| [WHEN FIELD CHANGES statement_list])
;
442
A.4 Statements
statement_block‘
BEGIN statement_list END;*
statement_list‘
statement*
statement‘
close_pipeline
| commit_statement
| create_pipeline
| delete_statement
| display_statement
| erase_statement
| expression;
| for_statement
| function_call
NOTE:
Only functions not returning a value
| if_statement
| input_statement
| lock_statement
| next_action
| next_form_statement
NOTE:
next_form_statement may only appear in CHOOSE FIRST FORM and
CHOOSE NEXT FORM sections.
| record_insert
| record_update
| refresh_screen
| reject_operation
| reject_record
| repaint_screen
443
| repeat_statement
| restart_field
NOTE:
Only the expressions SET and function_call may appear as
statements.
| statement_block
| switch_statement
| while_statement
| write_pipeline
| zoom_statement
|;
NOTE:
A semicolon (;) by itself is a null statement.
close_pipeline‘
CLOSE PIPELINE variable_name;
commit_statement‘
COMMIT TX
create_pipeline‘
CREATE PIPELINE variable_name pipe_spec
[ OUTPUT [IS] path_name];
delete_statement‘
DELETE table_name [WHERE logical_db_expression];
| DELETE CURRENT RECORD;
display_statement‘
DISPLAY TRIM [FOR form_expression]
[AT [@] (row_expression, column_expression)]
[WAIT]
NOTE:
Parentheses ( ) are part of the statement.
| DISPLAY [expression]
[FOR (screen_field_name | FYI_MESSAGE)]
444
[WAIT] [USING format_expression]
[DISPLAY_JUSTIFY [IS] justify_spec];
erase_statement‘
ERASE TRIM [FOR form_expression]
[AT [@](row_expression, column_expression)];
NOTE:
for_statement‘
FOR ([expression]; [logical_expression];
[expression]) statement
NOTE:
function_call‘
function_name ([expression_list])
| system_function
if_statement‘
IF expression THEN statement [ELSE statement]
input_statement‘
INPUT
lock_statement‘
(SLOCK | XLOCK | UNLOCK) table_name
[WHERE logical_db_expression];
next_action‘
NEXT ACTION [IS] action_spec;
next_form_statement‘
[WHEN logical_expression]
transaction_level_spec
USING (form_expression | EXIT);
445
record_insert‘
INSERT INTO table_name
[(]db_field_name_list[)]:expression_list;
NOTE:
Parentheses ( ) are an optional part of the statement.
record_updat‘
UPDATE table_name SET db_field_name_list TO
expression_list [WHERE logical_db_expression];
| UPDATE CURRENT RECORD;
refresh_screen‘
REFRESH SCREEN;
reject_operation‘
REJECT OPERATION;
reject_record‘
REJECT RECORD;
repaint_screen‘
REPAINT SCREEN;
restart_field‘
RESTART ON FIELD;
repeat_statement‘
REPEAT statement_list UNTIL logical_expression;
set_expression‘
SET variable TO expression
set_select_expression‘
[AND (SLOCK | XLOCK)]
db_expression_list FROM table_name
[WHERE logical_db_expression]
[ORDER BY db_field_sort_spec_list]
446
switch_statement‘
SWITCH expression
BEGIN
((CASE constant: | DEFAULT:) + statement_list) +
END;
while_statement‘
WHILE logical_expression statement
write_pipeline‘
zoom_statement‘
ENABLE ZOOM [RECORD_CONSISTENCY | SET_CONSISTENCY]
TO form_expression
[AT [@](row_expression, column_expression)]
[REPEATED numeric_expression] [RETURN KEY];
| DISABLE ZOOM TO form_expression;
Specifiers
action_spec‘
CLEAR [TO] ADD
| CLEAR [TO] FIND
| EXIT
| FIND
| NEXT FORM
| PREVIOUS FORM
| NEXT RECORD
| PREVIOUS RECORD
conversion_spec‘
LOWER
| NONE
| string_expression
| UPPER
db_field_sort_spec‘
db_field_name sort_spec
447
db_field_sort_spec_list‘
db_field_sort_spec (, db_field_sort_spec)*
justify_spec‘
CENTERED
| LEFT
| RIGHT
| string_expression
pipe_spec‘
ASCENDING
DESCENDING
| pipe_name [, pipe_name]*
sort_spec‘
ASCENDING
DESCENDING
| string_expression
type_spec‘
AMOUNT
| BOOL
| DATE
| FLOAT
| NUMERIC
| STRING
| TIME
transaction_level_spec‘
CONTINUE TX RECORD_CONSISTENCY
| CONTINUE TX SET_CONSISTENCY
| RESTART TX
| START TX RECORD_CONSISTENCY
| START TX SET_CONSISTENCY
448
A.5 Expressions
column_expression‘
numeric_expression
db_expression‘
expression
NOTE:
db_field_names are allowed.
db_expression_list‘
db_expression [, db_expression]*
expression‘
expression [binary_operator expression]*
| unary_operator expression
| ( expression )
NOTE:
Parentheses are part of the expression.
| variable
| constant
| search_range_list
| function_name ([expression_list])
NOTE:
Parentheses are part of the expression.
| set_expression‘
| set_select_expression
expression_list‘
expression [, expression]*
format_expression‘
See the entry for the DISPLAY statement in Chapter 8.2.
449
form_expression‘
form_name
| string_expression
logical_db_expression‘
db_expression
NOTE:
db_field_names are allowed.
logical_expression‘
expression
NOTE:
logical_expression must evaluate to a boolean (TRUE or FALSE)
value.
numeric_expression‘
expression
row_expression‘
numeric_expression
search_range‘
[expression] [=> expression]
| expression =>
search_range_list‘
search_range [, search_range]*
set_expression‘
SET variable TO expression
set_select_expression‘
[AND (SLOCK | XLOCK | UNLOCK)]
db_expression_list FROM table_name
[WHERE logical_db_expression]
[ORDER BY db_field_sort_spec_list]
450
string_expression‘
expression
Operators
add_operator‘ + | binary_operator‘
add_operator
| bit_and_operator
| bit_or_operator
| equality_relational_operator
| multiplication_operator
| non_equality_relational_operator
| logical_and_operator
| logical_or_operator
bit_and_operator‘ &
bit_or_operator ‘ | | ^
equality_relational_operator ‘ = | <>
logical_and_operator ‘ AND
logical_or_operator ‘> OR
multiplication_operator ‘ * | / | %
non_equality_relational_operator‘ > | >= | < | <=
unary_operator ‘ + | - | ~ | NOT
451
A.6 Variables and constants
application_name‘
IDENTIFIER
archive_name‘
Name of form archive.
db_field_name‘
table_name.[$] IDENTIFIER
| # IDENTIFIER
db_field_name_list‘
db_field_name [, db_field_name]*
form_name‘
IDENTIFIER
function_name‘
variable_name
IDENTIFIER‘
A string of up to 44 letters, digits, and underscores, beginning with a letter.
path_name‘
the pathname of a file
pipe_name‘
program name that forms a standard operating system pipeline
screen_field_name‘
[$] IDENTIFIER
table_name‘
[$] IDENTIFIER
452
variable‘
[form_name:] [variable_name:] attribute
| application_name:: [variable_name:] attribute
| application_name:: variable_name
| system_variable
| variable_name
| db_field_name
variable_name‘
[ $ ] IDENTIFIER
variable_list‘
variable [, variable]*
Constants
The maximum precisions given for AMT_CONST, DATE_CONST, FLT_CONST,
INT_CONST, and TIME_CONST are machine-dependent. The values given assume
32-bit twos-complement integers and 64-bit floating point values.
constant‘
INT_CONST
| FLT_CONST
| AMT_CONST
| TRUE | FALSE
| STR_CONST
| DATE_CONST | NULLDATE
| TIME_CONST
| UNDEFINED
NOTE:
TRUE, FALSE, NULLDATE, and UNDEFINED are reserved words for
the corresponding constants and can be used in statements.
AMT_CONST‘
A numeric constant of up to eleven digits including two decimal places.
DATE_CONST‘
A nine digit integer constant.
453
FLT_CONST‘
A numeric constant of up to seventeen digits. Up to 9 digits may be decimal
places.
INT_CONST‘
A numeric constant of up to nine digits with no decimal place.
STR_CONST‘
A string of up to 256 characters enclosed in apostrophes.
TIME_CONST‘
A numeric constant representing the number of minutes since midnight.
454
A.7 Attributes, characteristics, and system functions and
variables
Attributes
Abbreviations after form, target, screen, and variable attributes indicate the attribute
type:
bool
Boolean or logical attribute
expr
Expression valued attribute
num
Numeric attribute
str
String valued attribute
An s in parentheses (s) after the attribute's type indicates the attribute can be set.
attribute‘
form_attribute
| variable_attributes
variable_attributes‘
variable_attribute
(screen_attribute
NOTE:
Undefined for non-screen variables.
| target_attribute)
NOTE:
Undefined for non-target variables.
form_attribute‘
ADD_ALLOWED
| AUD_ON_ENTRY
| AUTO_COMMIT
| AUTO_FIND
(bool)
(bool)
(bool)
(bool)
(s)
(s)
(s)
(s)
455
| CLEAR_AFTER_AU
| COL_ORIGIN
| CUR_NEXT_FIELD
| DELETE_ALLOWED
| FIND_ALLOWED
| FIND_COUNT
| FIRST_FIELD
| FORM_NAME
| HEIGHT
| MENU_LABEL
| OCCURRENCES
| PREV_FIELD
| PREV_FORM
| ROW_ORIGIN
| TARGET_TABLE
NOTE:
(s)
(s)
(s)
(s)
(s)
(s)
(s)
Value is UNDEFINED if there is no table.
| UPDATE_ALLOWED
| WIDTH
screen_attribute‘
AUTO_ACCEPT
| AUTO _ZOOM
| BLINK
| CASE_CONVERSION
| COL
| DATA_TYPE
| DISPLAY_FORMAT
| DISPLAY_JUSTIFY
| FIELD_LENGTH
| FIELD_NAME
| FINDABLE
| FYI_COL
| FYI_MESSAGE
| FYI_ROW
| HELP_ARCHIVE
| HELP_FORM_NAME
| HELP_FORM_COL
456
(bool)
(num)
(str)
(bool)
(bool)
(num)
(str)
(str)
(num)
(str)
(num)
(str)
(str)
(num)
(str)
(bool)
(num)
(s)
(bool)
(bool)
(bool)
(str)
(num)
(str)
(str)
(str)
(num)
(str)
(bool)
(num)
(str)
(num)
(str)
(str)
(num)
(s)
(s)
(s)
(s)
(s)
(s)
(s)
(s)
(s)
(s)
| HELP_FORM_ROW
| LOW_INTENSITY
| MULTI_VALUED
| NEXT_FIELD
| REQUIRED
| REVERSE
| ROW
| STOP_FOR_INPUT
| TAB_STOP
| UNDERLINE
| UPDATEABLE
| WINDOW_WIDTH
(num)
(bool)
(bool)
(str)
(bool)
(bool)
(num)
(bool)
(bool)
(bool)
(bool)
(num)
target_attribute‘
CLEAR_FIND_EXP
| DB_LENGTH
| DB_TYPE
| SEARCH_RANGES
| TARGET_FIELD
(expr)
(num)
(str)
(expr)
(str)
variable_attribute‘
ACCELL_TYPE
| CLEAR_ADD_EXP
(str)
(expr)
(s)
(s)
(s)
(s)
(s)
(s)
(s)
(s)
(s)
(s)
(s)
(s)
(s)
(s)
Characteristics
Field and form characteristics are comment sections only. (s) after a characteristic
indicates a string-valued characteristic. (u) means that a value of UNDEFINED
indicates the system area.
field_characteristics‘
CHARACTERISTICS
[ACCELL_TYPE type_spec;]
[TARGET_FIELD db_field_name;]
[DB_TYPE type_spec;]
[DB_LENGTH numeric_expression;]
[MULTI_VALUED logical_expression;]
[REVERSE logical_expression;]
[BLINK logical_expression;]
(s)
(s)
(s)
457
[UNDERLINE logical_expression;]
[LOW_INTENSITY logical_expression;]
[DATA_TYPE type_spec;]
[DISPLAY_FORMAT string_expression;]
[[FIELD_LENGTH numeric expression;]]
[DISPLAY_JUSTIFY justify_spec;]
[ROW numeric_expression;]
[COL numeric_expression;]
[WINDOW_WIDTH numeric_expression;]
[STOP_FOR_INPUT logical_expression;]
[AUTO_ZOOM logical_expression;]
[AUTO_ACCEPT logical_expression;]
[NEXT_FIELD screen_field_name;]
[TAB_STOP logical_expression;]
[REQUIRED logical_expression;]
[UPDATEABLE logical_expression;]
[FINDABLE logical_expression;]
[CASE_CONVERSION conversion_spec;]
[FYI_MESSAGE string_expression;]
[FYI_ROW numeric_expression;]
[FYI_COL numeric_expression;]
[HELP_FORM_NAME form_name;]
[HELP_ARCHIVE string_expression;]
[HELP_FORM_ROW numeric_expression;]
[HELP_FORM_COL numeric_expression;]
;
(s)
(s)
(s)
(s)
(u)
(u)
(s)
form_characteristics‘
CHARACTERISTICS
[FIND_ALLOWED logical_expression;]
[UPDATE_ALLOWED logical_expression;]
[DELETE_ALLOWED logical_expression;]
[ADD_ALLOWED logical_expression;]
[ORDER_BY [db_field_name_list];]
[MENU_LABEL string_expression;]
[OCCURRENCES numeric_expression;]
[WIDTH numeric_expression;]
[HEIGHT numeric_expression;]
[AUD_ON_ENTRY logical_expression;]
458
[CLEAR_AFTER_AU logical_expression;]
[AUTO_COMMIT logical_expression;]
[ROW_ORIGIN numeric_expression;]
[COL_ORIGIN numeric_expression;]
[FIRST_FIELD string_expression;]
[AUTO_FIND logical_expression;]
;
System functions and variables
Abbreviations after the function or variable name indicate the type of any arguments
and the type of value returned.
amt
Amount value
bool
Boolean or logical value
date
Date value
float
Floating point value
num
Numeric value
time
Time value
The symbol "‘ " separates the argument type from the return value type. For example,
(num ‘date) indicates the function takes a numeric argument and returns a date value.
Multiple types separated by slashes (/) indicate the function argument may be of more
than one type.
system_function
| aud_mode$
| beep$
| char_code_to_str$
| clip_str$
| close_message_file$
| current_date$
| current_record_count$
(‘bool)
(num)
(num‘single_char_str)
(st‘str)
( ‘ num)
( ‘ date)
( ‘ num)
459
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
current_record_num$
current_time$
flush_to_disk$
get_message$
getenv$
glob_str_compare$
group_id$
group_name$
is_current_record_stored$
last_command$
open_message_file$
pad_str_left$
pad_str_right$
push_shell$
record_is_current$
reg_exp_str_compare$
sleep$
status$
strlen$
str_to_char_code$
str_to_date
str_to_time$
str_to_val$
substr$
system$
user_id$
user_name$
val_to_str$
| yesno$
system_variable$‘
| add_allowed$
| delete_allowed$
| find_allowed$
460
(‘ num)
( ‘ time)
(num‘ str)
(str‘ tr)
(str,str‘ bool)
( ‘ num)
( ‘ str)
( ‘ bool)
( ‘ num)
(str ‘ num)
(str, single_char_str, num‘str)
(str, single_char_str, num‘str)
(No arguments or return value)
(‘ bool)
(str, str ‘ bool)
(num ‘ num)
( ‘ num)
(str ‘ num)
(single_char_str‘num)
(str ‘ date)
(str ‘ time)
(str ‘ num/float)
(str,num,num‘str)
(str ‘ num)
( ‘ num)
( ‘ str)
(num/float/bool/amt/
date/time/‘ str)
(str,num ‘ bool)
( ‘ bool)
( ‘ bool)
( ‘ bool)
| info_level$
| update_allowed$
type conversion functions‘
| to_amount$
| to_bool$
| to_date$
| to_float$
| to_num$
| to_time$
( ‘num)
( ‘ bool)
(num/float ‘ amt)
(num ‘ bool)
(num ‘ date)
(num/amt ‘ float)
(float/bool/amt/date/time
‘ num)
(num ‘ time)
461
462
Appendix B: Setting up the system
B.1 Introduction
ACCELL/IDS makes extensive use of the termcap file to control terminal character
display. ACCELL/IDS also uses the UNIFY file unicap to link keyboard characters to
ACCELL/IDS commands. Standard unicap and termcap files are distributed with
ACCELL/IDS and consist of entries organized by terminal type. You only need to
modify the termcap and unicap files if your system includes terminals that are not
listed in the files. You may also modify the unicap file if you want to customize the
ACCELL/IDS commands.
To modify the termcap or unicap file, begin by modifying a copy of the file distributed
with ACCELL/IDS rather than creating the file from scratch. When you are ready to
test the file you modified, change the TERMCAP and UNICAP environment variables
to point to the modified copy of the file.
The sections below first outline the termcap entries needed by ACCELL/IDS and then
describe the unicap entries used to customize commands. Note that these sections
describe only additions to the files. For more information about the termcap and
unicap files see the operating system and ACCELL/IDS DBMS Reference manuals.
463
B.2 Additional termcap file entries
ACCELL/IDS uses the termcap file to control the display of forms. Because a form can
have reverse low-intensity underline and blinking fields as well as business line
graphics, ACCELL/IDS must know exactly how the terminal handles these video
attributes.
NOTE:
Make sure line wrap is set on before trying to run ACCELL/IDS.
The termcap file must indicate whether or not the video attributes–reverse, lowintensity, underline, and blink–are embedded and whether they work independently or
in combination. ACCELL/IDS also requires additional termcap entries for terminals
that use line graphics.
The four sections below describe the format of the additional termcap entries and the
entries for embedded, combined, and independent attributes and line graphics
capability. Only the entries for combined and independent attributes interact. All other
entries act independently.
Note that because the termcap file contains an entry for each terminal type, these
entries must be made for each terminal type in your system. The termcap entries
must match the terminal capabilities.
464
B.3 termcap entry formats
The ACCELL/IDS termcap entries use only numeric and string capability codes. A
numeric capability code has the following form:
code#number
For example, the ACCELL/IDS numeric capability code sg would appear in the file as
sg#1.
String capability codes appear in the following form:
code=string
The standard termcap code dc would be assigned the string Â by the entry dc=Â. (
signifies the escape character and Â signifies control/A.)
Setting up the system
465
B.4 Screen SIZE entries
ACCELL/IDS automatically adjusts to different screen sizes using entries in the
termcap file. The entry li# gives the number of lines on the screen; co# determines the
number of columns. The default values are 24 lines and 80 columns.
Some terminals, however, have 25 lines instead of 24. If your terminal has 25 lines,
make sure you include a li#25 entry in your termcap file. The termcap entries must
match your terminal.
A new, expanded terminal with 60 lines and 132 columns would have li#60 and
co#132 in its termcap entry.
466
B.5 Embedded attributes
There are four capability codes for embedded attributes. These are listed in the
following table:
Capability code attributes
sg
reverse
ug
underlined
wg
low-intensity
yg
blinking
These codes appear in the termcap file if the attribute is embedded. The codes are
numeric capability codes assigned the value one. The absence of a capability code
indicates that the attribute is not embedded. For example, to indicate that reverse is
embedded, the entry sg#1 would appear in the file. Below is a partial termcap entry
for the Data 2000 terminal that includes the capability code sg:
d2|d2000data2000:is=\EU\Ef\E7\E5\E8:am:bs:cd=\E^C:sg#1:mi:nd=\E=:
Types of terminals
The method used to specify and represent embedded video attributes varies between
terminal types. Generally, terminals can be categorized as embedded or nonembedded.
For example, the Wyse 50 is a terminal with embedded attributes. The Freedom 110
and ANSI VT100 are non-embedded attribute terminals. You can determine the
attribute type of your terminal by referring to your terminal's Owner Manual or
contacting the hardware manufacturer.
Non-Embedded attribute terminals
You can display information on an non-embedded terminal by sending a special
sequence (a video control character) to turn on the video mode, such as blinking.
467
Then, any characters sent to the terminal will be presented in the specified video
mode up to the point where a new video mode is specified.
The video control character does NOT occupy any character position on the screen.
The video mode specified is time- dependent. This means that all characters
displayed after a video mode is turned on have the specified attribute until the video
mode is changed.
Embedded attribute terminals
Information that is displayed on an embedded terminal is somewhat different. The
video control character is position- dependent and occupies 1 or more character
positions on the screen.
For example, to display "xyz" at coordinates (1,1) in blinking video mode on normal
video background, you must first place a blink on video control character at (0,1) and
a normal on control character at (4,1). Then write "xyz" at (1,1) through (3,1).
NOTE:
If xyz had non-blank characters on either side of it (at (0,1) or (4,1)),
the non-blank characters would NOT be visible when the video control
characters were placed over them.
For example, if you had "--xyz--" and changed the alphabetic
characters to a blink attribute, you would see "- xyz -", because the "-"
on either side of the "xyz" would be overwritten by the video control
character.
Setting up termcap for an embedded terminal
In addition to the normal entries, the following entries must also be included to set up
termcap for an embedded terminal:
"yg":
"wg":
"sg":
"ug":
"rg":
"Va":
"Vb":
468
/*
/*
/*
/*
/*
/*
/*
# chars left by blink on/off */
# chars left by write protect on/off */
# chars left by reverse on/off */
# chars left by underline on/off */
# chars left by reverse + underline on/off */
reverse-OFF underln-OFF low-OFF blink-OFF */
reverse-OFF underln-OFF low-OFF blink-ON */
"Vc":
"Vd":
"Ve":
"Vf":
"Vg":
"Vh":
"Vi":
"Vj":
"Vk":
"Vl":
"Vm":
"Vn":
"Vo":
"Vp":
/*
/*
/*
/*
/*
/*
/*
/*
/*
/*
/*
/*
/*
/*
reverse-OFF
reverse-OFF
reverse-OFF
reverse-OFF
reverse-OFF
reverse-OFF
reverse-ON
reverse-ON
reverse-ON
reverse-ON
reverse-ON
reverse-ON
reverse-ON
reverse-ON
underln-OFF
underln-OFF
underln-ON
underln-ON
underln-ON
underln-ON
underln-OFF
underln-OFF
underln-OFF
underln-OFF
underln-ON
underln-ON
underln-ON
underln-ON
low-ON
low-ON
low-OFF
low-OFF
low-ON
low-ON
low-OFF
low-OFF
low-ON
low-ON
low-OFF
low-OFF
low-ON
low-ON
blink-OFF
blink-ON
blink-OFF
blink-ON
blink-OFF
blink-ON
blink-OFF
blink-ON
blink-OFF
blink-ON
blink-OFF
blink-ON
blink-OFF
blink-ON
*/
*/
*/
*/
*/
*/
*/
*/
*/
*/
*/
*/
*/
*/
Embedded terminals and ACCELL/IDS forms
Video control characters occupy character positions on an embedded terminal.
Therefore, when designing a form, you can avoid problems by leaving a space around
areas where the video attributes are not normal. This includes leaving a space
between the area and the window border.
If spaces are not left for the video control characters, then a number of situations can
occur that affect the visual appearance of the form. The following is a list of cases that
will cause problems:
1. Marking an area with 1 or more video attributes beginning with the leftmost
column (against the left border) or ending with the rightmost column (against
the right border).
Effect:
The video control character will be placed at the first
character position just inside the border. The character
occupying this position will not be visible.
Example:
Given "|" represents a border, if you try to display "xyz |"
and "xyz" is reverse, "yz |" is displayed. "xyz|" would be
displayed as " y |".
2. Marking two areas with different video attributes adjacent to each other (0
spaces dividing the areas).
469
Effect:
The video control character for the area on the right
must be placed either over the last character of the area
on the left or over the first character of the area on the
right. This is determined by the order in which the areas
are displayed.
If the area on the left is displayed first (as in a repaint),
the video control character will be placed over the last
character of the left area. If the right area is displayed
first (if you change the contents in code, etc.), the
control character will be placed in the first position of the
right area.
In general, the placement is time dependent: the last
area displayed has precedence over the other areas,
and therefore, has its entire area displayed (not
covered) if possible. One exception to this is the
following:
If a control character is placed over a character other
than a space and the character just inside the area
being marked by the video control character is a space
that is neither reverse nor underline, then the control
character is placed over the space rather than the
character.
Example:
Given that you try to display "xxxyyy ", where "xxx" is
blinking and "yyy" is reverse, if "xxx" is displayed before
"yyy", " xx yyy " will be displayed. If "yyy" is displayed
before "xxx", then " yy xxx " will be displayed.
3. Placing screen fields (that will accept input) adjacent to each other (0 spaces
dividing the fields).
Effect:
470
Since the current input field is highlighted by changing
the field to reverse video, adjacent input fields that are
not separated by spaces will have the same effect as in
case 2 above.
4. Placing a screen field (that will accept input) adjacent to a border (either left or
right border or both ).
Effect:
Since current input fields are highlighted by changing
the fields to reverse video, a video control character
must be placed to the left and right of the field to turn on
and off reverse.
However, only another window border can overwrite a
window border. Therefore, the control character must be
placed inside the input field at the first and/or last
character position. Then, when a character is entered at
the position of the video control character, it will not be
displayed, although it is placed in the input buffer.
Example:
Given that you have a STRING field of length 4
positioned against the left border ("|SSSS"), if you have
entered "123" in the field, "| 23" is displayed. If you have
entered "1" in the field, "| " is displayed.
The precautions presented in this subsection reflect situations that can occur with any
software package when using an embedded attribute terminal. To obtain the best
software use from a terminal, it is suggested that you select a non-embedded attribute
terminal with a good processing speed.
Additional information on termcap and unicap can be found in the DBMS Developer's
Reference Manual, Chapter 6, termcap and unicap.
471
B.6 Combined and independent attributes
Some terminals can only set combinations of reverse (R), low-intensity (L), blinking
(B), and underline (U) attributes and cannot set the attributes separately. These
terminals use what are called combined attributes. Terminals that set reverse, blink,
underline, and low-intensity separately use independent attributes.
Combination and independent attributes require special, separate entries in the
termcap file. If combination and independent attribute codes both appear in a
terminal's entries, the combination code overrides any corresponding independent
code.
Combined attributes
Terminals that use combination settings require special entries in the termcap file that
indicate which attributes are used in combination and the specific strings that invoke
the combinations.
Because there are four attributes and each can be set to on or off, there are sixteen
possible combinations, each requiring a unique capability code. The capability codes
for the various combinations are Va through Vp. The table that follows shows which
capability codes are set for various attribute combinations (note that the table is
divided into two pages). The following abbreviations are used for the video attributes.
R = Reverse
U = Underline
L = Low-intensity
B = Blink
Figure 69 Attributes and capability codes
Code L.B.
472
U.B. U.L. R.B. R.L.
R.U. U.L.B.
R.L.B. R.U.B. R.U.L. R.U.L.B.
✔
✔
✔
✔
✔
✔
✔
✔
✔
✔
✔
Va
✔
✔
Vb
✔
✔
Vc
✔
Vd
✔
✔
✔
Vf
✔
✔
✔
✔
Ve
✔
✔
✔
✔
✔
✔
✔
✔
✔
✔
✔
✔
✔
✔
✔
✔
✔
Figure 69 Attributes and capability codes (Continued)
Code L.B.
U.B. U.L. R.B. R.L.
R.U. U.L.B.
✔
Vg
R.L.B. R.U.B. R.U.L. R.U.L.B.
✔
✔
✔
Vh
Vi
✔
Vj
✔
✔
✔
✔
✔
Vk
✔
✔
✔
✔
✔
✔
✔
✔
✔
✔
✔
✔
✔
Vo
✔
✔
✔
Vn
✔
✔
✔
Vl
Vm
✔
✔
✔
Vp
For example, if underline and blink (U,B) are the only combined attributes, then the
capability codes Va, Vb, Ve, and Vf would appear in the file. If all four attributes are set
in combination then all sixteen codes would be included in the file.
Each capability code represents a specific combination of on and off settings for the
four attributes. These combinations appear in the table that follows.
Figure 70 Capability codes meaning
Code
Reverse
Underline Low
Blink
Va
✔
Vb
Vc
✔
Vd
✔
Ve
✔
Vf
✔
Vg
✔
✔
Vh
✔
✔
✔
Vi
✔
Vj
✔
Vk
✔
✔
Vl
✔
✔
✔
✔
✔
✔
473
Figure 70 Capability codes meaning (Continued)
Code
Reverse
Underline Low
Vm
✔
✔
Vn
✔
✔
Vo
✔
✔
✔
Vp
✔
✔
✔
Blink
✔
✔
Assuming that the terminal sets only underline and blink in combination, we know
from the Attributes and Capability Codes table that the Va, Vb, Ve, and Vf capability
codes must appear in the file. From the Capability Code Meaning table we can tell that
Va must be assigned the string that turns both underline and blink off. Similarly, Vb
must be assigned the string that turns underline off and blink on.
Strings assigned to the combined attribute capability codes must consist of the actual
characters transmitted to the terminal. An entry for Va, the code that turns on only
blink, added to our entry for the Data 2000 terminal might look like this:
d2|d2000data2000:is=\EU\Ef\E7\E5\E8:am:bs:cd=\E^C:sg#1:mi:nd=\E=::Va=ÂÂ:
Independent attributes
The table below shows the codes for independent attributes and their meanings:
474
Abbreviation
Meaning
Abbreviation
Meaning
so
start reverse video
ws
start low-intensity
se
end reverse video
we
end low-intensity
us
start underline
ys
start blinking
ue
end underline
ye
end blinking
B.7 Graphics capabilities
If your terminal uses line graphics, you need to include assignments to the capabilities
codes below:
Abbreviation
Meaning
Abbreviation
Meaning
gs
start graphics mode
gh
square lower right corner
gx
end graphics mode
gi
single line intersection
ga
round lower left corner
gj
viertical line
gb
round upper left corner
gk
horizontal line
gc
round upper right corner
gl
right tee
gd
round lower right corner
gm
left tee
ge
square lower left corner
gn
top tee
gf
sqare upper left corner
go
bottom tee
gg
square upper left corner
ACCELL/IDS assumes that graphics characters are not embedded. If there are no line
graphics capability codes in the file, ACCELL/IDS assumes that graphics are done
using the minus (-), pipe ( | ), and plus ( + ) characters.
unicap file entries
The ACCELL/IDS/Generator includes both extensive forms design and screen editing
command sets. The unicap file links these commands to specific keyboard
combinations. You need to modify the unicap file only if you want to customize the
keyboard commands or if your terminal type is not included in the distributed unicap
file.
For information about the unicap file and its format see the ACCELL/IDS DBMS
Developer's Reference Manual, Chapter 6.2, unicap. The current command key
assignments are summarized on the Developer's Command Summary card following
Appendix B.
475
Customizing function key names
The function key names ACCELL/IDS displays can be customized by changing the
first item in the function key entry. Each entry has the following syntax:
command = [key_label] | <fn> | character_sequence
To change a function key name, replace key_label with your name for the key. The
square brackets ([ ])are part of the entry.
The current command key assignments are summarized on the Developer's
Command Summary card following Appendix B.
Special considerations
You must modify your unicap file if either of the following two conditions apply to your
system:
476
•
If DOWN ARROW and RETURN send the same character sequences on your
terminal, you must modify the entries in your unicap file so the two keys send
different character sequences.
•
If CTRL Z is a signal on your system, the ZOOM command must be changed
to another character sequence.
B.8 Developer’s command summary
ACCELL/IDS/Manager commands
ABORT APPLICATION
ADD/UPDATE
CANCEL ZOOM
CLEAR FIELD
CLEAR TO ADD
CLEAR TO FIND
DELETE CHAR
DELETE CHAR LEFT
DELETE RECORD
EXIT HELP
EXPLAIN ERROR
FIELD HELP
FIND
FIRST RECORD
HELP MENU
LAST RECORD
LEFT EDGE OF DATA
LEFT EDGE OF FIELD
LEFT EDGE OF WINDOW
MENU CANCEL
MENU DOWN
MENU SELECT
MENU UP
MORE KEY
MOVE LEFT
MOVE RIGHT
NEXT FIELD
NEXT FORM
NEXT RECORD
NEXT SET
NEXT TAB
PREVIOUS FIELD
PREVIOUS FORM
PREVIOUS RECORD
PREVIOUS SET
PREVIOUS TAB
RECALL FIELD
REPAINT SCREEN
REPLACE/INSERT
RIGHT EDGE OF DATA
RIGHT EDGE OF FIELD
RIGHT EDGE OF WINDOW
SHOW ERRORS
UNREPLACE LEFT
ZOOM
^c
\Eau
\E^z
^y
\Eca
\Ecf
^f
^x
\Edr
\Eeh
\Eee
\Eh
\Efi
\Efr
\EH
\Elr
\Eld
\Elf
\E<left arrow>
\Emc
<down arrow>
<RETURN>
û
\Emo
<left arrow>
<right arrow>
<RETURN>
\EnF
<down arrow>
\Ens
î
û
\EpF
<up arrow>
\Eps
\E^j
\Erc
^r
ê
\Erd
\Erf
\E<right arrow>
\Ese
^g
^z
<F9>
<F19>
<F7>
<F13>
<DEL>
<F18>
<F12>
<F5>
<F3>
<F16>
<F6>
<F17>
<F1>
<F2>
<up arrow>
<F10>
<F2>
<F4>
<F15>
<F1>
<F3>
<F14>
<F11>
<F8>
<F20>
Unify Corporation, by this statement, hereby extends its permission to the original licensee to reproduce this summary card.
This permission is limited to and applies only to this summary card and is extended to the original licensee only.
477
ACCELL/IDS/Generator commands
ABORT GENERATOR
ADD FIELD
ADD HELP
CENTER ALL TRIM HORIZONTALLY
CENTER FORM
CENTER FORM HORIZONATALLY
CENTER FORM VERTICALLY
CENTER LINE
CHANGE FORM SIZE MOVING TRIM
CURSOR LEFT BEGINNING WORD
CURSOR RIGHT BEGINNING WORD
DELETE CHAR
DELETE CHAR LEFT
DELETE FIELD
DELETE FIELD LEFT
DELETE FIELD RIGHT
DELETE LINE
DELETE REPEATING TRIM
DOWN
EDIT NEW FORM
EXIT HELP
EXPLAIN ERROR
FIELD HELP
GRAPHICS
HELP MENU
INSERT LINE
MARK FIXED TRIM
MARK REPEATING AREA
MARK REPEATING TRIM UP
MARK VIDEO AREA
MORE KEY
MOVE FIELD
MOVE FORM
MOVE LEFT
MOVE RIGHT
NEXT FIELD
NEXT FORM
PREVIOUS FORM
REPAINT SCREEN
REPLACE/INSERT
ROWL/COL DISPLAY
SET EDIT TAB STOPS
SET VIDEO DEFAULTS
SHOW ERRORS
SHOW REPEATING AREA
SIZE FIELD LEFT
SIZE FIELD RIGHT
SIZE FORM
UNREPLACE LEFT
UP
WORD LEFT END WORD
WORD RIGHT END WORD
478
^c
\Eaf
\Eah
\Ect
\Ewa
\EcF
\Ewv
\Ecl
\Est
\Elw
\ErW
^f
^x
^df
^dl
^dr
\Edl
\Edt
^dt
<down arrow>
\EeF
\Eeh
\Eee
\Eh
\Eg
\EH
\Eil
\Etf
\Emr
\Etu
\Emv
\Emo
\Emf
\EmF
<left arror>
<right arrow>
<RETURN>
\EnF
\Epf
^r
ê
\Etc
\Ets
\Esd
\Esv
\Ese
\Esa
\Esl
\Esr
\EsF
^g
<up arrow>
\Ewl
\Ewr
<F11>
<F11>
<DEL>
<F15>
<F19>
<F12>
<F5>
<F20>
<F6>
<F18>
<F17>
<F16>
<F10>
<F12>
<F4>
<F2>
<F1>
<F8>
<F7>
<F14>
Appendix C: Unify ACCELL/IDS Error
messages
C.1 ACMB error messages
1801 ACMB ERROR: There was an error in reading the file %s
Explanation:
This error refers to an unsuccessful attempt to read a .fq or .aq file.
This error occurs for one of five reasons:
•
the .fq or .aq file could not be opened or closed with calls to fopen or fclose
•
the .fq or .aq file may have been opened, but according to the internal
magic number, the file was not a screen form
•
the maximum number (62) of file descriptions allowed for ACCELL/IDS
files has been reached
•
an fread or fseek call failed
•
the system is out of memory
1802 ACMB ERROR: There was a bad magic number
Explanation:
Every ACCELL/IDS file type has a magic number associated with it.
This number is stored in the file to help executables distinguish an
archive from a screen file. For example, this error can occur when the
Combiner is asked to open an archive, and a file is already in the
specified location; the file has the same name, and does not contain
the correct magic number for an archive file.
This error could be caused by the user, or the file may have been
corrupted by some system or program failure.
479
Correction:
In most cases removing the archive file and trying to ACMB again will
correct the problem. See section 9.1, under Types of ACCELL/IDS
Files, for a description of the suffix ACCELL/IDS uses to determine
which file to remove.
1803 ACMB ERROR: The Combine failed in malloc memory
Explanation:
This error refers to malloc failures that are allocating space for
attributes or form information, etc., when the Combiner is writing the
combined temporary file or adding the combined file to the archive.
This error will indicate:
•
the system is out of memory, or
•
ulimit is set too low
1804 ACMB ERROR: Couldn't find a 'next field'
Explanation:
When a .fq/.aq file is created, the Generator sets up a list of the fields
on the form. Indexes into this list are used to set the initial next field
attribute for each field in the list. During processing, the Combiner
creates a temporary file containing information from the .fq/.fo, or .aq/
.ao file pair for a form. One of the steps in setting up the file information
is to change the initial next field attribute for each field in the list, as set
by the Generator, to index the symbol table built from the information in
the .fo/.ao and .fq/.aq files. This error will be set if a field occurs in the
list set up by the Generator, but cannot be found in the new symbol
table built from the symbol tables in the .fo/.ao and .fq/.aq files.
1805 ACMB ERROR: Checksum error. Verify .fs and .fq target table names match
Explanation:
•
480
When a .fs language script is compiled, a checksum is calculated,
based on the target relation id for the form in the current data base.
This checksum is stored in the resulting .fo file. The same type of
checksum is calculated for a screen and stored in the .fq file. When the
Combiner is processing a form that has a language script, it checks to
make sure the checksum stored in the language script file is equal to
that in the form's screen file. This is one of the checks done by the
Combiner to make sure both the script and screen refer to the same
target table in the data base. This error can occur if:
the target table names in the .fo and .fq files do not match
•
the data base schema has been changed since the .fo or .fq file was
created.
NOTE:
Even if a .fs file does not refer to a field that has been added to its
associated target table, it still must be recompiled so that its checksum
will be calculated according to the updated data base.
1806 ACMB ERROR: The field %s is not in the file %s.[af]q
Explanation:
When a language script is compiled (by ACPL), a list of all screen
fields referenced by the script is made and stored in the compiled
script. When a screen file (/.aq) is created, it also contains a list of all
the screen fields for the screen. When the Combiner is processing a
form that has a language script, it checks to make sure that each field
listed as a screen field by the script is indeed a screen field on the
screen. If a field is in the list in the .fs file but not in the list in the .fq file,
then this error is set.
1807 ACMB ERROR: There was a form name mismatch
Explanation:
When the Combiner is processing a form that has a language script, it
does some checks to make sure the information in the compiled script
matches the information in the form's screen file. One of these checks
is to make sure that the form/application name (specified in the
form_declaration of a .fs or .as file) stored in the compiled form
matches the form/application name stored in the screen file. If they do
not match, then this error is set.
1808 ACMB ERROR: There was a form/application mismatch
Explanation:
When a screen for a form is created, a flag specifying whether the
screen is for a Master Application or a Standard form is stored in the
.fq or .aq file. When the Combiner is processing a form that has a
language script, it checks to make sure that the form's screen file and
the form's compiled language script file both specify the same type of
form (Master Application or Standard). If they do not, then this error is
set.
Unify ACCELL/IDS Error messages
481
1809 ACMB ERROR: There is a corrupt file
Explanation:
This error refers to unsuccessful attempts by the Combiner to read all
or part of the archive index of an ACCELL/IDS file. The error can occur
under one of these conditions:
•
an fseek call failed
•
an fread call failed
1810 ACMB ERROR: There was an error in adding the form
Explanation:
This error occurs when the Combiner is unsuccessful in adding
(writing) a form unit (FMUN) to an ACCELL/IDS file. A FMUN is a
structure containing information on a form. This error can occur under
the following conditions:
•
the Combiner creates a FMUN from information in the .fo/.fq or .ao/.aq file
pair for a form to be added to an application archive. The FMUN is written
(added) to a temporary file before it is combined into the archive. If the
attempt to write it to the temporary file fails, then this error will be set
•
when a form is to be combined into an existing application archive file, the
Combiner reads in the existing FMUNs in the archive file and sorts them
along with the FMUN for the form to be added to the archive. It then writes
all the FMUNs out to the archive file. If an attempt to add a FMUN (either a
pre-existing FMUN or the new FMUN stored in a temporary file) to the
archive file fails, this error will be set
1811 Not applicable
1812 ACMB ERROR: There was an error in reading the form
Explanation:
482
Once the Combiner has produced the temporary file of information
from the form's .fo/.fq or .ao/.aq file pair, it merges this information into
the application archive file if it exists, otherwise it creates a new archive
file. This error occurs when the Combiner is merging the information in
the temporary file into an existing archive file if the Combiner is unable
to read a Form Unit (FMUN) structure for a form specified in the
application archive file or for the form to be added.
C.2 ALNK error messages
2201 ALNK ERROR: The application linker does not have enough memory.
Explanation
The Linker tries to read information from the appropriate archive for
each required form for an application. The Linker uses malloc to
allocate space in which to read the information. This error is set when
the malloc fails, and will indicate that:
•
•
2202 ALNK ERROR: There is a duplicate required form %s in the application.
Explanation
The Linker sets up an internal table containing information on all the
required forms for an application. When it is building this table, as it
processes each form, the Linker first verifies that it has not built an
entry for a form with the same name. If it has, then this error is set.
NOTE:
The application form is not treated as a required form. Thus, there may
be a form in the required forms list with the same name as the
application.
2203 Not applicable
2204 ALNK ERROR: Form %s is not in the archive or the archive doesn't exist.
Explanation
The Linker sets up an internal table containing information on all the
required forms for an application, including an index into the Linker's
internal list of archive file names containing forms used by the
application being processed. After the table is built, the Linker checks
each entry to see that each form has an index into the list of archive file
names so that the form can be found. If a form does not have an index,
then this error is set.
2205 ALNK ERROR: Error opening application archive file %s, Status = %s
Explanation
In general, this error occurs if an attempt to open an archive file (.fa
file) fails. Since the Linker does some initialization processing when
483
opening an archive file, this error can occur for any of the following
conditions:
1. the .fa file could not be opened with a call to fopen
2. an fread or fseek call failed. freads and fseeks are called to read in the magic
number and archive index header for the .fa file
3. the maximum number (62) of file descriptions allowed for ACCELL/IDS files
has been reached
4. every ACCELL/IDS file has a magic number associated with it. This number is
stored in the file to help executables distinguish an archive from a screen file.
This error occurs when the Linker opens an archive file but it does not contain
the magic number for an archive file. This error could be caused by the user or
the file may have been corrupted by some system or program failure.
Status will be set to one of the following:
•
the value of errno for case 1 and 2 above
•
the value -11 for case 3 above
•
the value -2 for case 4 above
2206 ALNK ERROR: Ran out of memory while allocating archive index space.
Explanation
This error occurs when a malloc call to allocate space in which to read
in the archive index of an archive file (.fa file) fails. It will indicate that:
•
•
2207 ALNK ERROR: There was an error reading an archive index, Status = %s
Explanation
This error occurs when an attempt to read in the archive index of an
archive file (.fa file) fails. This can occur if an fseek or fread call fails.
Status will indicate the value of errno.
2208 ALNK ERROR: The specified master application form %s not in archive %s
Explanation
484
Before processing the required forms for an application, the Linker
opens the archive file (.fa file) specified by the command line. The
Linker then searches its archive index for an application entry (as
opposed to an entry for a form) whose application name matches the
application name specified by the command line. If a matching entry is
not found, then this error is set.
2209 ALNK ERROR: Error closing an application archive file, Status = %s
Explanation
This error will be set if an attempt to close (using fclose) an archive file
fails. Status will be set to EOF if fclose failed because EOF was
reached.
2210 ALNK ERROR: There was an error while reading a form file, Status = %s
Explanation
Before it can process the forms for an application, the Linker needs to
know what forms make up the application, and in what archives the
forms reside. The Linker gets this information from the application
archive file. The Linker searches the FMUN , or form unit–a structure
containing information about a form) that contains the application
information as opposed to a FMUN containing information on a form).
Once it has found its location, the Linker attempts to read in the
application FMUN. If an error occurs while reading in the FMUN, then
this error will be set. The read attempt may fail for one of the following
reasons:
•
an fseek or fread call failed
•
the system is out of memory
Status will indicate the value of errno if an fseek or fread call failed.
Otherwise, status will be -5, to indicate the system is out of memory.
2211 ALNK ERROR: Ran out of archive name space.
Explanation
The Linker keeps an internal table of all the archive files that contain
forms (the application form and all its required forms) for the
application being processed–that is, for all the archives that are used
by the application. If– while the Linker is setting up this table of archive
names–either the table has reached its ACCELL/IDS defined limit (512
entries), or an attempt to malloc storage for an entry fails, then this
error will be set.
2212 Not applicable
485
2213 ALNK ERROR: %s: BAD Exit Status = %s
Explanation
This is a general error code, returned to indicate that the Linker
encountered some type of error while attempting to link the application.
This error message should be preceded by another, more specific
error message, indicating why the Linker was unsuccessful. Status will
be the error code for the more specific error message.
2214 ALNK ERROR: Could not open or create the .al file.
Explanation
Once the Linker has read in all the information it needs from the
archive files, it attempts either to create the application file (.al file) if it
does not exist, or to open the file to rewrite it, if it does exist. This error
will be set if the Linker is unable to open or create the file (e.g., if a call
to fopen fails).
2215 ALNK ERROR: There was an error while closing the .al file, Status = %s
Explanation
This error will be set if the Linker's attempt (using fclose) to close the
newly created application file fails. Status will indicate the value of
errno.
2216 ALNK ERROR: There was an error while seeking or writing the .al file.
Explanation
Once the Linker has read in all the information it needs from the
archive files, it attempts to write the information to the application file to
be created (or re-created). This error will be set if an attempt to write to
the file fails (e.g., if an fseek or fwrite call fails).
2217 ALNK ERROR: Error reading data base checksum out of form %s, Status = %s
Explanation
486
For each form to be included in the application, the Linker reads its
target relation id and target relation checksum from the archive in
which the form is located. This error will be set if one of the following
conditions occurs while attempting to read this information:
•
an fread or fseek call fails
•
a call to allocate memory to hold the information to be read fails
NOTE:
The checksum is a value calculated from the target relation id of a
target table. The checksum is used by various executables to ensure
the most recent version of the data base is being used.
2218 ALNK ERROR: Could not find the %s form in the %s archive.
Explanation
The Linker attempts to locate each form in the archive in which the
user specifies the form resides, by searching the archive's index for an
entry for a form whose name matches the form name. If an entry for
the form is not found in the specified archive, then this error is set.
2219 ALNK ERROR: Ran out of archive names getting checksums
Explanation
The Linker keeps a list of all the archives containing forms for the
application. It also keeps a list of the application's required forms and
their associated archive files, and sorts the list in archive file order.
Thus, when the Linker tries to read the checksums and target relation
ids, it processes all the forms that are stored in the same archive file at
the same time. This error will be set if the Linker has read all the
archives in the list and it still has forms for which it has not read the
target relation information.
487
C.3 ACPL error messages
2801 ACPL ERROR: A "(" operator was expected.
Explanation
This error occurs when the Compiler is expecting an open
parentheses, "(", and it is not found.
Correction
The "(" is required under these conditions:
•
after the keyword FOR in a for_statement.
•
in a user_function_declaration, after the function_name and before any
function arguments.
•
in an AT POSITION clause, a "(" must precede the row and column
specified as the position. This clause can appear in the display_statement,
zoom_statement, or erase_statement.
2802 ACPL ERROR: A ")" operator was expected.
488
Explanation
This error occurs when the Compiler expects a ")" but none is found.
Correction
The ")" is required in the following instances:
•
in a for_statement, after the expression to be evaluated at the end of each
loop iteration is specified.
•
in a user function declaration after the function's parameters are specified.
Note that parenthesis are required even if the function has no parameters
"( )".
•
in an AT position clause, a ")" must follow the column specified for the
position. This clause can appear in the display_statement,
zoom_statement, or erase_statement.
•
if the db_field_name_list of a record_insert statement is preceded by a "(",
then it must be followed by an ")".
•
if an expression contains a function call, signaled by an identifier followed
by a "(", then a ")" must follow the list of arguments passed to the function.
•
if an expression contains a "(" then it must be ended with a ")".
2803 ACPL ERROR: A "," was expected.
Explanation
This error occurs when the Compiler requires a "," (not when it is
optional) and it is not found.
Correction
The "," is required in an AT POSITION clause, where a "," must separate
the row and column specified for the position. This clause can appear
in the display_statement, zoom_statement, or erase_statement.
2804 Not applicable
2805 ACPL ERROR: A ":" was expected.
Explanation
This error occurs when the Compiler is expecting a ":" and it is not
found.
Correction
The ":" is required in the following instances:
•
a ":" must separate the db_field_name_list and the expression_list in a
record_insert statement
•
in a switch_statement, a ":" must follow the keyword DEFAULT
•
in a switch_statement, a ":" must follow the constant specified in a CASE
clause
2806 ACPL ERROR: A ";" was expected.
Explanation
This error occurs when the Compiler is expecting a ";" and it is not
found.
Correction
The ";" is required in the following instances:
•
in a for_statement after the expression to be evaluated once at the
beginning of the for loop. Note that the ";" is required even if no expression
is specified.
•
in a for_statement after the expression to be evaluated at the beginning of
each loop iteration. Note that the ";" is required even if no expression is
specified.
2807 Not applicable
489
2808 Not applicable
2809 Not applicable
2810 Not applicable
2811 Not applicable
2812 ACPL ERROR: The 'BEGIN' keyword was expected.
Explanation
This error occurs when the Compiler is expecting the keyword BEGIN
and it is not found.
Correction
The keyword BEGIN is required in the following instances:
•
the statement block after an EXECUTING clause must start with the
keyword BEGIN . The EXECUTING clause can appear in a
set_select_expression.
•
after the expression following the keyword SWITCH in a switch_statement.
2813 Not applicable
2814 Not applicable
2815 ACPL ERROR: A data base type expected.
ExplanationThis error occurs when the Compiler is expecting the next token to be a
data base type as specified by the type_spec specifier (AMOUNT,
STRING, BOOL, DATE, ...) and it is not.
CorrectionDo not use the DB_TYPE clause in the field_characteristics statement of a
SCREEN FIELD language section. Include a type_spec specifier after the
keyword DB_TYPE.
2816 Not applicable
2817 ACPL ERROR: The 'END' keyword was expected.
490
Explanation
This error occurs when the Compiler is expecting the keyword END and
it is not found.
Correction
The END keyword is required in the following instances:
•
a statement block (started with a BEGIN keyword) must end with the
keyword END.
•
at the end of a switch_statement.
2818 ACPL ERROR: The 'FIELD' keyword was expected.
Explanation
This error occurs when the Compiler is expecting the keyword FIELD
Correction
The FIELD keyword is required in the following instances:
•
in a restart_field statement after the keywords RESTART ON.
•
in the WHEN FIELD CHANGES clause of a SCREEN FIELD language
section, the keyword FIELD is required after the keyword WHEN.
2819 Not applicable
2820 ACPL ERROR: The 'FORM' keyword was expected.
Explanation
This error occurs when the Compiler is expecting the keyword FORM
Correction
The FORM keyword is required in the following instances:
•
in a CHOOSE NEXT FORM language section after the keyword NEXT if the
form is a Standard form.
•
in a CHOOSE NEXT FORM language section, after the keyword, FIRST, if
the form is a Master Application form.
2821 ACPL ERROR: The 'FORMS' keyword was expected.
Explanation
This error occurs when the Compiler is expecting the keyword
Correction
The FORMS keyword is required in the REQUIRED FORMS clause, in
the form_declaration of a Master Application form.
FORMS
2822 ACPL ERROR: The 'FROM' keyword was expected.
Explanation
This error occurs when the Compiler is expecting the keyword FROM
491
The FROM keyword is required in a set_select_expression; the
keyword FROM must appear after the db_field_name_list.
Correction
2823 ACPL ERROR: The 'FUNCTION' keyword was expected.
Explanation
FUNCTION and it is not found.
Correction
The declaration of a user function must have the FUNCTION keyword
after the function's return type specification.
2824 ACPL ERROR: A field identifier was expected.
492
Explanation
This error occurs when the Compiler is expecting the next token to be a
db_field_name or an identifier, and it is not.
Correction
The Compiler expects a db_field_name or identifier in the following
instances:
•
when it is processing a db_field_name_list (in a record_insert or
record_update statement, or in an ORDERED_BY clause in a FORM
CHARACTERISTICS section), the list must be composed of one or more
comma separated db_field_names where each db_field_name either
begins with '#' or is an identifier. If a comma is present and is not followed
by a db_field_name, then this error will be set.
•
when it is processing a db_field_sort_spec_list in an ORDER BY clause of
a set_select_expression, each db_field_sort_spec specifier must begin
with a db_field_name.
•
when it is processing a db_field_name, if it is of the form
table_name.[$]IDENTIFIER, the '.[$]' must be followed by an identifier.
•
when it is starting to process a SCREEN FIELD language section, the initial
keyword of the section, FIELD, must be followed by an identifier to specify
the screen_field_name.
•
when it is processing a FIELD CHARACTERISTICS section, if present, the
INITIAL_NEXT_FIELD clause must have an identifier after the keyword
INITIAL_NEXT_FIELD.
•
in any other instance, when the Compiler thinks it is processing a
db_field_name, it must begin with '#' or an identifier.
2825 ACPL ERROR: A file identifier was expected.
Explanation
UNIX file name, and it is not.
Correction
A file name is required in the REQUIRED FORMS clause of a
form_declaration for a Master Application form, for each form_spec, the
IN clause must specify a file name for the application archive.
2826 ACPL ERROR: A form identifier was expected.
Explanation
This error occurs when the Compiler is expecting the next token to be
an identifier for a form and it is not.
Correction
A form identifier is required in the REQUIRED FORMS clause of a
form_declaration for a Master Application form, each form_spec must
being with an identifier for the form.
2827 ACPL ERROR: A form or user function definition was expected.
Explanation
A language script must begin with either a form_declaration or a
user_function_declaration. This error will be set if neither is found.
Correction
Begin a language script with either a form_declaration or a
user_function_declaration.
2828 ACPL ERROR: Display location was expected.
Explanation
This error occurs when the Compiler is processing a
display_statement.
Correction
If the FOR clause is used, the keyword FOR must be followed by either
a screen_field_name or the FYI_MESSAGE keyword.
493
2829 Not applicable
2830 Not applicable
2831 ACPL ERROR: The 'INTO' keyword was expected.
This error occurs when the Compiler is expecting the INTO keyword, and it is not
found.
The INTO keyword is required in a record_insert statement; INTO must
follow the INSERT keyword.
Correction
2832 ACPL ERROR: A form or application identifier was expected.
Explanation
an identifier for a form or an application name and it is not.
Correction
Such an identifier is required in the following instances:
•
•
in the form_declaration for a Standard form, the keyword FORM must be
followed by an identifier specifying the form_name.
in the form_declaration for a Master Application form, the keyword
APPLICATION must be followed by an identifier specifying the
application_name.
2833 ACPL ERROR: A justification specification was expected.
Explanation
This error occurs when the Compiler is expecting a valid justify_spec
specifier and it is not found.
Correction
The justify_spec specifier is required when the optional
DISPLAY_JUSTIFY clause is used in the display_statement.
2834 Not applicable
2835 Not applicable
2836 ACPL ERROR: A lock specification was expected.
Explanation
494
lock specification and it is not.
A lock specification is required in a set_select_expression; if the
keyword AND follows the keyword SELECT, the AND must be followed
by a lock specification (e.g. SLOCK, XLOCK, UNLOCK ).
Correction
2837 Not applicable
2838 Not applicable
2839 ACPL ERROR: The 'NEXT' keyword was expected.
Explanation
the NEXT keyword and it is not.
Correction
The keyword NEXT is required in a Standard form after the keyword
CHOOSE in the CHOOSE NEXT FORM language section.
2840 Not applicable
2841 ACPL ERROR: The 'RECORD' keyword was expected.
Explanation
Correction
The RECORD keyword is required in the following instances:
RECORD
•
in a delete_statement where the keyword CURRENT is specified, it must be
followed by the keyword RECORD.
•
in a record_update statement where the keyword CURRENT is specified, it
must be followed by the keyword RECORD.
•
in a reject_record statement the keyword RECORD must follow the
keyword REJECT. Since the Compiler can not determine if a reject_record
or a reject_operation statement was to be specified, error 2920 will also be
set in this case.
•
in an ON NEXT RECORD language section after the keywords ON NEXT.
•
in an ON PREVIOUS RECORD language section after the keywords ON
PREVIOUS.
495
2842 Not applicable
2843 ACPL ERROR: A relation ID specification was expected.
Explanation
an identifier specifying a table_name (relation) and it is not.
Correction
The Compiler expects a table_name identifier in the following
instances:
•
in a delete_statement when the CURRENT RECORD clause is not used, a
table_name must follow the keyword DELETE.
•
in a record_insert statement a table_name must follow the keyword INTO.
•
in a record_update statement when the CURRENT RECORD clause is not
used, a table_name must follow the keyword UPDATE.
•
in a lock_statement a table_name must follow the first keyword (which
specifies the type of lock).
•
in a SELECT clause, the keyword FROM must be followed by a table_name.
2844 ACPL ERROR: The 'SELECT' keyword was expected.
Explanation
This error occurs when the Compiler is expecting the keyword SELECT
Correction
The keyword SELECT is required in a set_select_expression after the
keyword TO. A set_select_expression is distinguished from a
set_expression by the presence of a variable_list after the keyword
SET and not just a single variable.
2845 ACPL ERROR: The 'SET' keyword was expected.
496
Explanation
the SET keyword and it is not.
Correction
The Compiler expects the SET keyword in a record_update statement
when the CURRENT RECORD clause is not used. Under these
conditions, the keyword SET must follow the table_name.
2846 ACPL ERROR: An ACCELL/IDS type was expected.
Explanation
valid ACCELL/IDS variable type (AMOUNT, FLOAT, STRING,) ...and it
is not.
Correction
A valid ACCELL/IDS variable type is expected after the keywords
ACCELL_TYPE and DATA_TYPE in the field_characteristics comment
section for a field.
2847 Not applicable
2848 Not applicable
2849 Not applicable
2850 ACPL ERROR: The 'THEN' keyword was expected.
Explanation
the THEN keyword, and it is not.
Correction
The THEN keyword is required in an if_statement after the expression
to be evaluated.
2851 Not applicable
2852 Not applicable
2853 ACPL ERROR: The 'TO' keyword was expected.
Explanation
the TO keyword and it is not.
Correction
The Compiler expects the TO keyword in the following instances:
•
in a zoom statement when the DISABLE ZOOM clause is used, the keyword
TO must follow the keyword ZOOM.
•
in a zoom statement when the ENABLE ZOOM clause is used, the keyword
TO must follow the optional transaction consistency specification if present
(otherwise it must follow the keyword ZOOM).
497
•
in a record_update statement the keyword TO must follow the
db_field_name_list.
•
in a set_expression or set_select_expression statement, the keyword TO
must follow the variable or variable_list specification.
2854 ACPL ERROR: The 'TRIM' keyword was expected.
Explanation
the TRIM keyword and it is not.
Correction
The TRIM keyword is required in an erase_statement after the ERASE
keyword.
2855 ACPL ERROR: The 'TX' keyword was expected.
Explanation
the TX keyword and it is not.
Correction
The Compiler expects the TX keyword in the following instances:
•
In a commit_statement the keyword TX must follow the keyword COMMIT.
•
If the CONTINUE clause is used in a transaction_level_spec of a
next_form_statement, the keyword TX must follow the keyword CONTINUE.
•
If the START clause is used in a transaction_level_spec of a
next_form_statement, the keyword TX must follow the keyword START.
•
If the RESTART clause is used in a transaction_level_spec of a
next_form_statement, the keyword TX must follow the keyword RESTART.
NOTE:
This error code is also set if neither the CONTINUE/START/RESTART
clauses are found when a transaction_level_spec is expected in a
next_form_statement.
2856 ACPL ERROR: The 'UNTIL' keyword was expected.
498
Explanation
the UNTIL keyword and it is not.
Correction
The UNTIL keyword is required in a repeat_statement after the
statement_list.
2857 ACPL ERROR: The 'USING' keyword was expected.
Explanation
the USING keyword, and it is not.
Correction
The USING keyword is required in a next_form_statement after the
transaction_level_spec.
2858 ACPL ERROR: A user name was expected.
Explanation
user defined name, and it is not.
Correction
The Compiler expects such a name in the following instances:
•
for the function_name in a user_function_declaration.
•
in a user_function_declaration, for variable_name specifications (if the
function has parameters).
2859 Not applicable
2860 ACPL ERROR: A variable was expected.
Explanation
This error occurs when the Compiler expects the next token to be a
variable specification, and it is not.
Correction
It can be set whenever the grammar calls for a variable specification
and one is not found.
2861 Not applicable
2862 Not applicable
2863 Not applicable
2864 ACPL ERROR: %s: There is not enough memory.
Explanation
This error occurs when the Compiler tries to allocate memory for its
internal use and the memory allocation is unsuccessful. Thus, it is not
caused by a syntax error on the user's part. The Compiler allocates
storage for internal structures and arrays that it uses in processing an
input form file.
499
2865 ACPL ERROR: %s: Cannot open file %s.
Explanation
This error occurs when the Compiler cannot open a file.
Correction
This error will be set in the following cases:
•
if the Compiler was invoked with the -s option and it was unable to open
the symbol table output file.
•
if the Compiler was invoked with the -c option and it was unable to open
the code output file.
•
if the Compiler could not open the input form file to be compiled. One
instance in which this error will occur is if the -a flag is left off the command
line for a MAF (and -i is not used).
2866 ACPL ERROR: An illegal character was ignored.
Explanation
This error occurs when a token was encountered in the form file that
the Compiler could not interpret.
2867 ACPL ERROR: An ACCELL/IDS statement was expected.
Explanation
This error occurs when the Compiler is processing a statement and it
expects the next token to be the start of another statement (including a
no_operation statement, ';'), and it is not. This can happen in control
flow statements (e.g., for_statement, if_statement, repeat_statement,
while_statement, switch_statement) when the statement being
controlled by the control flow statement is not specified.
Correction
Be sure to specify the statement under control of the control flow
statement.
2868 ACPL ERROR: An attribute was expected.
500
Explanation
an attribute and it is not.
Correction
An attribute is expected when a variable is being processed and the
variable includes a variable_name followed by a ':'. The ':' must be
followed by an attribute.
2869 ACPL ERROR: A form code section name was expected.
Explanation
This error occurs when the Compiler has processed the keyword
BEFORE or AFTER and thus expects the next keyword to identify a
before or after form code section (such as before_form , after_zoom,
etc.), and it does not.
2870 Not applicable
2871 Not applicable
2872 Not applicable
2873 ACPL ERROR: The 'KEY' keyword was expected.
Explanation
the KEY keyword, and it is not.
Correction
The KEY keyword is required in an ENABLE ZOOM zoom_statement if
the RETURN clause is used in which case KEY must follow the keyword
RETURN.
2874 Not applicable
2875 ACPL ERROR: The 'CASE' or 'DEFAULT' keyword was expected.
Explanation
the CASE or DEFAULT keyword, and it is not. This can occur when a
switch_statement is being processed.
Correction
After the BEGIN keyword, the next token must be either CASE or
DEFAULT.
2876 Not applicable
2877 ACPL ERROR: The 'CHANGES' keyword was expected.
Explanation
the CHANGES keyword, and it is not.
Correction
The keyword CHANGES is required after the keyword FIELD in the
WHEN FIELD CHANGES clause of a screen_field language section.
501
2878 ACPL ERROR: There was an internal parser error.
Explanation
In general, this error should not occur. It is included mostly as a
safeguard to detect an internal error in the Compiler code. This error
will be set under any of these conditions:
•
if a field characteristic is to processed but there is no Compiler code to
process it
•
if a form characteristic is to processed but there is no Compiler code to
process it
•
if a screen field code section is to be processed but there is no Compiler
code to process it
•
if a variable or form attribute is to be processed but there is no Compiler
code to process it
•
if a loop statement (not a control statement) of some type is to be
processed (currently, the restart_field statement is the only one of this
type) but there is no Compiler code to process it
•
when printing the compiled form code, if a variable or form attribute to be
printed is not in the Compiler's internal table of allowed variable and form
attributes
2879 ACPL ERROR: A help form ID was expected.
Explanation
field_characteristics section.
Correction
If present, the HELP_FORM_NAME clause must have an identifier after
the keyword HELP_FORM_NAME to specify the form_name.
2880 ACPL ERROR: There was a bad conversion.
Explanation
502
When the Compiler encounters a constant (e.g., INTEGER, AMOUNT,
FLOAT, 'TRUE', DATE, ...) in an input form file, it is read in as a
character string. Before storing it internally, the Compiler converts it to
its constant type. This error code is returned if the conversion fails.
2881 ACPL ERROR: There are too many %s symbols.
Explanation
As the Compiler processes an input form file, it builds some internal
tables to keep track of its processing. Three of these tables are used to
keep track of symbols encountered in the form. A symbol is basically
just a term for a user defined token (as opposed to a ACCELL/IDS
keyword). The compiler builds a table of local, external, and
ambiguous symbols. If any of these tables runs out of space, this error
code will be set.
2882 ACPL ERROR: No free registers, the expression is too complex.
Explanation
This error can occur when the Compiler is converting a parsed
expression into ACCELL/IDS code. Registers are used to store
intermediate information. The number of available registers is limited to
128. If this limit is reached while an expression is being processed, this
error will be set.
2883 ACPL ERROR: An attribute needs a variable name specified.
Explanation
This error occurs when the Compiler expects the next token to be a
variable specification. If it finds a field attribute instead, then this error
will be set.
2884 ACPL ERROR: Too many errors, can't continue.
Explanation
The Compiler does not stop processing a form file when an error is
found. Instead, it attempts to check the whole file for errors. However, if
the Compiler has found the maximum number of errors allowed (10), it
will end processing with this error set.
2885 ACPL ERROR: There is a bad system variable.
Explanation
This error occurs when the Compiler thinks it is processing an
ACCELL/IDS system variable but the variable's name is not valid (e.g.,
it does not match any of the valid ACCELL/IDS system variable
names).
503
2886 Not applicable
2887 ACPL ERROR: Relation ID not found in data dictionary.
Explanation
This error occurs when the Compiler expects the next token to be an
identifier specifying a table_name, but the Compiler can not find the
identifier in the list of table names in the data base. The Compiler
checks a table_name identifier against the data base in the following
instances:
•
in all DML statements where a table_name can be specified (e.g.,
delete_statement, record_update, record_insert, lock_statement,
set_select_expression).
•
in the TARGET_TABLE clause of the form_declaration.
Be sure that the specified table_name is valid – The data dictionary
may have been corrupted.
Correction
2888 ACPL ERROR: No fields can be found.
Explanation
This error occurs when the Compiler checks the data base to get
information on the fields comprising a table or to get information on
one field in a table and the field(s) information can not be found in the
data base. The Compiler checks the data base for field information in
the following instances:
•
when processing a form, the data base is checked to locate information on
the fields comprising the table specified by table_name in the
TARGET_TABLE clause of the form_declaration.
•
before the Compiler writes the compiled form out to a file, the data base is
checked to locate information on each local symbol that is a target field
(including screen/target fields).
2889 ACPL ERROR: Data base access error - target table has no fields.
Explanation
504
This error occurs when the Compiler has finished processing the input
form file and is preparing to create the output file containing the
compiled form. Included in the output file is the checksum for the target
table (if the form has an associated target table). This error will be set if
one of the following occurs when the Compiler accesses the data base
to calculate the checksum:
•
the target table has no fields
•
a malloc call failed
The checksum is a value calculated from the target relation id of a
target table. It is used by various executables to make sure that the
most recent version of the data base is being used.
NOTE:
2890 ACPL ERROR: An expression was expected.
Explanation
This error occurs when a search_range_list is being processed for a
set_expression for a CLEAR_FIND_EXP target attribute.
Correction
Each search_range must begin with either an expression or a range
character, =>.
2891 ACPL ERROR: The 'ACTION' keyword was expected.
Explanation
Correction
The keyword ACTION is required in a next_action statement after the
keyword NEXT.
ACTION
2892 ACPL ERROR: The 'RECORD' or 'FORM' keyword was expected.
Explanation
This error occurs when the Compiler is expecting the keyword FORM or
RECORD and it is not found.
Correction
One of these keywords is required in the following instances:
•
in an ON_NEXT_FORM language section after the keywords ON NEXT.
•
in an ON_PREVIOUS_FORM language section after the keywords ON
PREVIOUS.
•
in a next_action statement where the action_keyword is PREVIOUS.
505
2893 ACPL ERROR: The 'ADD' or 'FIND' keyword was expected.
Explanation
This error occurs when the Compiler is processing a next_action
statement and it is expecting the next keyword to be either ADD or
FIND, and it is not.
Correction
One of these keywords must be specified if the action_spec begins
with the keyword CLEAR .
2894 ACPL ERROR: A relation identifier does not match.
Explanation
When a compiler is processing a DML statement (delete_record,
record_insert, record_update, set_select_expression, lock_statement)
in a form file it does a check to make sure that the relation to which any
specified data base fields belong is the same as the relation specified
by the table_name. If the relations are different, then this error will be
set.
2895 ACPL ERROR: The variable list doesn't match # of scalar_db_exp's.
Explanation
set_select_expression and the number of variables in the variable_list
does not match the number of expressions in the db_expression_list.
2896 ACPL ERROR: There is a bad data base field ID.
Explanation
506
This error occurs when the Compiler accesses the data base to get
information on data base fields specified (directly or indirectly) in a
statement and the information can not be found. This can occur in the
following instances:
•
when processing a TARGET_TABLE clause in a Standard Form declaration
the data base is accessed to get information on all the field ids in the
specified TABLE_NAME.
•
when processing a db_field_name_list in a statement (for example, in a
record_insert statement), the data base is accessed to get information on
each field id for each db_field_name in the list.
2897 ACPL ERROR: There is a bad data base field name: %s
Explanation
After the Compiler parses a db_field_name_list it accesses the data
base to get information on the specified data base fields. This error will
be set if one of the following occurred when the Compiler was
accessing the data base:
•
if the Compiler was unable to obtain the field id for a specified data base
field name.
•
if the data base field type (retrieved from the data base) is variable length
text or variable length binary, since these types are currently not supported
by ACCELL.
Explanation
This error may also be set when a db_field_sort_spec_list is being
processed for the ORDER BY clause in a set_select_expression. As
each db_field_name of the list is processed, the data base will be
accessed to obtain the field id for the field name. If this access fails,
this error will be set.
2898 ACPL ERROR: The 'FIRST' keyword was expected.
Explanation
The CHOOSE NEXT FORM language section can only be used in
Standard forms. The CHOOSE FIRST FORM language section can only
be used in a Master Application Form (MAF). When the Compiler is
processing a MAF and it comes across the keyword CHOOSE as the
beginning of a language section, it expects the keyword FIRST to
follow. If it does not, then this error is set.
2899 ACPL ERROR: Language section not valid in a Standard Form.
Explanation
The before_application and after_application language sections can
only appear in a Master Application Form (MAF). If the Compiler is
processing a Standard Form and one of these sections is encountered,
this error will be set.
2900 ACPL ERROR: The CONSTANT expression was expected.
Explanation
This error occurs when the compiler is expecting a token to be a
constant identifier, and it is not. A constant is expected in a
switch_statement after each occurrence of the keyword CASE.
507
2901 ACPL ERROR: More than one default expression in switch statement.
Explanation
Only one DEFAULT keyword is allowed in a switch_statement.
2902 ACPL ERROR: There is a UNDEFINED function.
Explanation
The Compiler builds a table containing information on all user defined
functions that were declared at the beginning of a form. It also has a
table containing information on all system functions. When the
Compiler encounters a function call in an expression in a statement,
the appropriate table is searched for a match on the function name (the
user function table is searched for user functions, the system function
table for system functions). If no match is found, this error is set.
Correction
User functions must be declared before they are used. Otherwise, they
are undefined to the Compiler.
2903 ACPL ERROR: The number of parameters do not match.
Explanation
functions that were declared at the beginning of a form. The Compiler
also has a table containing information on all system functions. When
the Compiler encounters a function call in an expression within a
statement, the number of parameters specified in the function call are
compared with the number of parameters expected for the function.
This error will be set if either:
•
too many parameters were specified in the function call
•
not enough parameters were specified in the function call
2904 ACPL ERROR: A reference parameter was expected.
Explanation
508
functions that were declared at the beginning of a form. This
information includes whether or not a parameter was declared as a
RESULT parameter. When the Compiler encounters a user function call
in an expression in a statement, the type of parameters specified in the
function call are compared against the parameter types expected for
the function. This error will be set if the Compiler is expecting a
parameter to be a result parameter (e.g., some variable that can be
referenced), and instead, a constant expression is found.
2905 ACPL ERROR: A function was redeclared.
Explanation
If the beginning of a form file contains user function declarations, the
Compiler builds a table containing an entry with information for each
function declared. If more than one declaration is found for a user
function (e.g., the function already has an entry in the table), then this
error is set.
2906 ACPL ERROR: Data base ID list/scalar expression mismatch.
Explanation
This error occurs when the number of expressions in the
expression_list for a record_insert or a record_update statement does
not match the number of db_field_names in the db_field_name_list.
2907 ACPL ERROR: A 'On Clear To Add' statement was expected.
Explanation
This error occurs when the Compiler thinks it is processing an ON
CLEAR TO ADD or ON CLEAR TO FIND language section, and then
determines it is not because the TO keyword does not follow the
keywords ON CLEAR.
2908 Not applicable
2909 Not applicable
2910 Not applicable
2911 Not applicable
2912 Not applicable
2913 ACPL ERROR: 'SET_CONSISTENCY' or 'RECORD_CONSISTENCY' keyword
expected.
Explanation
This error occurs when the Compiler is expecting the next keyword to
be either SET_CONSISTENCY or RECORD_CONSISTENCY and it is not.
This can happen when a transaction_level_spec specifier is being
processed for a next_form_statement.
509
Correction
If the specifier begins with either CONTINUE TX or START TX, then the
next keyword must be either SET_CONSISTENCY or
RECORD_CONSISTENCY.
2914 ACPL ERROR: A 'FIND', 'NEXT' or 'PREVIOUS' keyword was expected.
Explanation
This error occurs when the Compiler is processing the start of a new
form code section that begins with the keyword ON. It expects the next
keyword to be either CLEAR, EXIT, FIND, NEXT, or PREVIOUS, signaling
respectively an ON CLEAR TO ADD or ON CLEAR TO FIND, ON EXIT, ON
FIND, ON NEXT FORM, or ON PREVIOUS FORM language section. If it
does not find one of these keywords, then this error is set.
2915 ACPL ERROR: A PIPELINE was expected.
Explanation
This error occurs when the Compiler is expecting the keyword PIPELINE
Correction
The keyword PIPELINE is required in the following instances:
•
in a create_pipeline statement after the keyword CREATE
•
in a write_pipeline statement after the keyword WRITE
•
in a close_pipeline statement after the keyword CLOSE
2916 ACPL ERROR: Statement can only occur in an ON FIELD code section.
Explanation
This error occurs when the Compiler is processing a code section that
is not an ON FIELD code section, and encounters a statement that can
only occur in an ON FIELD code section.
Correction
The following statements may only appear in an
•
the input_statement
•
the restart_field statement
ON FIELD
code section:
2917 ACPL ERROR: There is a bad function type.
Explanation
510
user_function_declaration at the beginning of a form file. If anything
other than 'C' is specified, this error is set.
Correction
Only C functions are allowed. Thus the declaration must begin with the
keywords EXTERN C.
2918 ACPL ERROR: A target attribute is not allowed.
Explanation
This error occurs when the Compiler finds a target variable attribute,
included in a variable specification for a variable that is not a target
variable.
2919 ACPL ERROR: Statement can only occur in an ON FIND code section.
Explanation
This error occurs when the Compiler is processing a code section that
is not an ON FIND code section, and it comes across a statement that
can only occur in an ON FIND code section.
Correction
The reject_record statement is the only statement that can appear only
in an ON FIND code section.
2920 ACPL ERROR: A OPERATION was expected.
Explanation
This error occurs when the Compiler is expecting the next keyword to
be either RECORD or OPERATION and it is not. This occurs when a
reject_record or reject_operation statement is being processed.
Correction
The keyword REJECT must be followed by either RECORD or
OPERATION. If it is not, then this error will be set.
NOTE:
The same code is used to process both reject_record and
reject_operation statements
NOTE:
Error 2841 will accompany Error 2920.
2921 Not applicable
2922 Not applicable
2923 Not applicable
2924 ACPL ERROR: Statement may not occur in an ON FIND code section.
Explanation
This error occurs when the Compiler is processing an ON FIND code
section, and it comes across a statement that is not allowed in an ON
511
FIND code section. Currently, this error is only set if the next_action
statement appears in an ON FIND code section.
2925 ACPL ERROR: Statement may not occur in an INIT FIELD code section.
Explanation
This error occurs when the Compiler is processing an INIT FIELD code
section, and it comes across a statement that is not allowed in an INIT
FIELD code section. Currently, this error is only set if the next_action
statement appears in an INIT FIELD code section.
2926 ACPL ERROR: Statement may not occur in an AFTER APPLICATION code section.
Explanation
This error occurs when the Compiler is processing an AFTER
APPLICATION code section, and it comes across a statement that is
not allowed in an AFTER APPLICATION code section. Currently, this
error is only set if the next_action statement appears in an AFTER
APPLICATION code section.
2927 ACPL ERROR: Statement may not occur in a BEFORE APPLICATION code
section.
Explanation
This error occurs when the Compiler is processing an BEFORE
APPLICATION code section, and it comes across a statement that is
not allowed in an BEFORE APPLICATION code section. Currently, this
error is only set if the next_action statement appears in an BEFORE
APPLICATION code section.
2928 ACPL ERROR: Statement may not occur in a WHEN FIELD CHANGES code
section.
Explanation
This error occurs when the Compiler is processing an WHEN FIELD
CHANGES code section, and it comes across a statement that is not
allowed in an WHEN FIELD CHANGES code section. Currently, this
error is only set if the next_action statement appears in an c code
section.
2929 ACPL ERROR: Statement may not occur in a BEFORE FORM code section.
Explanation
512
This error occurs when the Compiler is processing an BEFORE FORM
code section, and it comes across a statement that is not allowed in an
BEFORE FORM code section. Currently, this error is only set if the
next_action statement appears in an BEFORE FORM code section.
2930 ACPL ERROR: There is a bad master application variable.
Explanation
This error occurs when the Compiler thinks it is processing a master
application variable. It expects the application_name:: to be followed by
an identifier specifying the variable_name. If it is not, then this error is
set.
2931 ACPL ERROR: There are Too many program names (pipes) in the program list.
Explanation
This error occurs when the number of programs specified in the
program_name_list of a create_pipeline statement is greater than the
maximum number (8) allowed.
2932 ACPL ERROR: The statement may not occur in current code section.
Explanation
This error occurs when the Compiler is processing a code section and
it comes across a statement that is not allowed in the current type of
code section. Currently, this error is set in the following instances:
•
if the ENABLE ZOOM form of the zoom_statement is found in a form code
section (since it is only allowed in a screen field code section)
•
if the reject_operation statement is found in a form code section in which it
is not allowed or in a screen field code section
2933 ACPL ERROR: The 'SCREEN' keyword was expected.
Explanation
Correction
The keyword SCREEN is required in the following instances:
•
in a refresh_screen statement after the keyword REFRESH
•
in a repaint_screen statement after the keyword REPAINT
SCREEN
2934 ACPL ERROR: Must use START TX in an application.
Explanation
When the Compiler is processing a transaction_level_spec for a
CHOOSE FIRST FORM ... statement in a Master Application form, the
513
START TX clause must be used. If it is not (instead, the CONTINUE TX
or RESTART TX clause is), then this error will be set.
Correction
The CONTINUE TX and RESTART TX clauses are only allowed in
Standard forms.
2935 ACPL ERROR: There was a duplication of a code section.
Explanation
The Compiler keeps track of the language sections it has processed.
This error will be set if it finds it has already processed the current form
code or screen field section.
2936 Not applicable
2937 ACPL ERROR: The 'BY' keyword was expected.
Explanation
This error occurs when the Compiler is expecting the keyword BY and
it is not found.
Correction
The keyword BY is required in a set_select_expression statement after
the keyword ORDER (if it is present).
2938 ACPL ERROR: UNLOCK not allowed.
Explanation
This error occurs when a statement has a locking option specified and
the specified lock type is not allowed for the statement. Currently, this
only occurs if a set_select_expression statement has the UNLOCK
locking option specified.
2939 ACPL ERROR: Strings constants exceeded the maximum number for a form.
Explanation
The Compiler keeps a count of the number of strings (not their length)
found in a form file. If the Compiler finds the count exceeds the
maximum number allowed (1024) for a form, this error will be set.
2940 ACPL ERROR: Exceeded maximum allowed nesting level.
Explanation
514
As the Compiler processes statements in which nesting can occur
(for_statement, if_statement, repeat_statement, switch_statement,
while_statement), it keeps track of the nesting level. If the maximum
nesting level allowed (8) has been exceeded, then this error will be set.
2941 ACPL ERROR: The 'RETURN' keyword was expected.
Explanation
This error occurs when the Compiler expects the next token to be the
keyword RETURN and it is not.
Correction
The keyword RETURN is required after the keywords AFTER FORM
which introduce the AFTER FORM RETURN form code section.
2942 ACPL ERROR: The Statement was not expected.
Explanation
This error occurs when the Compiler thinks it has processed a
complete form and there are still more statements in the form file. Only
one form can be in a form file.
NOTE:
This error can sometimes occur when an invalid statement is
encountered. The statement causes the Compiler to think it has
finished processing a code section which really has not yet been
finished.
2943 ACPL ERROR: The 'ON' keyword was expected.
Explanation
This error occurs when the Compiler expects the next token to be the
keyword ON, and it is not. The keyword ON is required after the
keyword RESTART in the restart_field statement.
515
516
Glossary
ACCELL/Environment
The part of ACCELL/IDS that provides easy access to all of ACCELL's development tools.
It contains a series of forms that let you enter the Generator, and compile and run
applications.
ACCELL/Generator
An applications generator used to draw forms, to establish field attributes, and to define the
order of execution for fields and forms.
ACCELL/Language
A full-featured fourth-generation language used to combine painted forms with additional
flow of control logic and other application language features.
ACCELL/Manager
The run-time module for the completed ACCELL/Generator forms and ACCELL/Language
files. It takes care of calling up the appropriate forms and user displays in the right order
and interacting with the end user and the data base.
ACCELL/DBMS
The UNIFY Relational Data Base Management system, the industry's leading DBMS
package, providing proven power and flexibility.
active form
All the forms that have appeared on the screen since the start of the last transaction are
considered active forms.
active form chain
The sequence of forms that are currently active. Also see active form.
One of two user modes available to an application end user. In Add/Update/Delete mode
the user may add records to the data base, modify existing records, or remove records.
See also user modes.
517
aggregate field
A field whose contents are calculated from multiple values or fields, such as a field
containing an average or a record count.
allowable operations
The data base operations allowed for an application, form, or field. There are four allowable
operations (sometimes rendered as the acronym fuda): find, update, delete, add.
application
A set of forms designed to accomplish an integrated task, such as prospect tracking or
order entry.
application area
See screen.
application generator
A fill-in-the-form design tool used to build applications visually on the screen. The ACCELL/
Generator is an application generator.
assignment compatible
Variables of different type for which automatic type conversion is provided in an assignment
statement. For example, when a numeric is assigned to a float variable, ACCELL/IDS first
converts the numeric to a float and then assigns the value to the float variable. A float and a
string are not assignment compatible.
assignment statement
An ACCELL/IDS statement that assigns a value to a variable or attribute. The value may be
an attribute, the value of another variable, or the result of a calculation.
associativity
The way in which operators and operands are grouped during processing–either left to right
or right to left, depending on the operator.
attribute
Characteristics of variables, or trim that the application may use or change. Typical
attributes include format, length, and initial value during Add or Find.
518
bitwise operator
One of the ACCELL/IDS operators such as ^ or | that works on individual bits (binary digits)
in integer values.
boolean
Having only two possible values: TRUE or FALSE. Many ACCELL/IDS form and screen
attributes are boolean attributes.
border
The frame surrounding a displayed form.
branching
When a form has more than one next form. Using a branching structure prevents too many
forms from becoming stacked in the active form chain.
C-hook
The facility for linking C language functions written by a developer with the ACCELL/
Manager.
clause
A discrete part of an ACCELL/IDS statement, such as the WHERE expression in the SET/
SELECT statement.
clear to add value
A target variable attribute used to set a target field's default value during a Clear to Add.
The Clear to Add value is placed in the corresponding target field when a Clear to Add is
performed.
clear to find value
A target variable attribute used to establish search ranges for data base searches. Clear to
Find values are not the search ranges themselves. Rather, ACCELL/IDS evaluates the
Clear to Find expressions to produce the search ranges. Clear to Find values are set in
Language sections.
Glossary
519
coordinates
Row and column numbers used to specify the screen locations of forms and fields. Form
location can be given in actual row and column numbers (screen coordinates) or in
coordinates relative to the origin of the current form (form coordinates).
current form
The form currently being processed by ACCELL. If more than one form appears on the
screen at one time, the current form is the one on which the cursor rests.
current record
The record of the current set displayed on a form. On multi- occurrence forms, the record
on which the cursor rests. The current record changes when the user issues commands
such as NEXT RECORD or PREV RECORD.
current set
The part of the selected set appearing on the screen. The current set can be thought of as
a window through which to view the selected set.
data base
The Unify data base used by ACCELL. Unify data bases are divided into tables, records,
and fields. Also see relational data base.
data base statement
ACCELL/Language statements that find and modify records in a data base table.
data type
The formats in which ACCELL/IDS stores data. There are three sets of data types in
ACCELL:
• ACCELL/IDS data type
• UNIFY data type
• Internal storage type
When ACCELL/IDS processes a form, the information is kept in the ACCELL/IDS format.
Information transferred from ACCELL/IDS to the UNIFY data base is converted to the
corresponding UNIFY data type. Each UNIFY data type has a specific internal storage
format.
520
display-only
A screen field that can only be displayed, not modified.
error level
A classification for types of errors. Errors are divided into four different levels (mild,
medium, severe, and fatal) depending on how serious they are.
error message
An informative message explaining an error that has just occurred. The type of error
message displayed depends on the severity of the error and the information level setting.
error forms
Forms that contain detailed information about particular error conditions. These forms are
called up when the end user enters the EXPLAIN ERROR command after an error
condition occurs.
expression
A series of ACCELL/Language elements from which a value can be derived. Expressions
include various combinations of operators, variables, constants, and other expressions.
field
The smallest unit of meaningful information in ACCELL. ACCELL/IDS uses two kinds of
fields: screen fields and target fields.
Screen fields are the areas on the terminal screen used to display information
Target fields are the divisions of the data base records
field order chain
A list maintained by the Manager that determines the previous or next field when the user
enters a PREV FIELD or NEXT FIELD command. The list keeps track of the fields where
the user has attempted to enter or change information.
field window
The area on the screen reserved for displaying screen field information. The field window
area may be smaller than the area required for the screen field information. In this case, the
user can scroll the window to see the rest of the field's contents. Also see horizontal
scrolling.
Glossary
521
find
A user-requested data base search
initiated with a FIND command. Optional search criteria may be specified by the end user
or in a Language script.
flow of control
A general term for the order in which forms and statements in an application are executed.
In ACCELL, flow of control involves both the sequence of execution for fields and forms and
the sequence of execution for ACCELL/Language statements.
form
An area on the terminal's screen that displays related headings and data base information.
Forms are created with the Generator and may optionally have Language scripts
associated with them.
Forms are surrounded by a border, which outlines the form window area. The different
types of forms are:
• Standard
• Zoom
• Help
• Error
• Master Application
See the definitions of the different form types for more information.
form coordinates
See coordinates.
form menu
A menu that appears automatically after the NEXT FORM user command when there is
more than one next form to choose from.
form window
The screen area occupied by a form and its screen fields and trim. A form window always
includes the border surrounding the displayed information. The terminal's screen size
determines a form's maximum size.
522
for your information (FYI) message
A message displayed in the lower left corner of the screen when the cursor is positioned on
a screen field. FYI messages can be defined for each screen field on each form in an
application.
fuda
Find, update, delete, and add. Fuda is the acronym for the four possible database
operations that an end user can perform while running an application.
function key
A programmable key that can be assigned to any user command or the Generator editing
command. Function keys are labeled with the letter F followed by a number. Function keys
are available on most terminal types.
general variable
An ACCELL/Language variable with a name distinct from any screen field or target field
name. These are frequently used to hold the values of intermediate calculations,
expressions, and other variables, or to act as state indicators.
help form
A display-only form that contains explanatory text. These forms are called up with the
FIELD HELP user command.
horizontal scrolling
ACCELL's means of displaying a screen field entry that is longer than the field window. If
there is more information than will fit in the window, the end user can keep moving the
cursor to the right until the rest of the information shows in the window. The characters of
the screen field will move, or scroll, to the left.
information level
A setting that determines the type of response ACCELL/IDS will have to different kinds of
errors. There are two information level settings available in ACCELL: novice and
intermediate.
Glossary
523
justification
How information is positioned in a screen field.
• Left justification places the information in the field beginning at the left margin.
• Centered justification places the information in the middle of the field.
• Right justification displays the information so the end of the data coincides with the right
margin.
key
An identifier for a record. See primary key and secondary key.
keyword
An individual word in an ACCELL/IDS statement or Language section such as SET, IF, and
SWITCH or BEFORE, ON, and AFTER.
language script
The files containing ACCELL/Language that manipulates forms. Each form may have only
one Language script. Language scripts are created and modified using the system editor
and are made up of Language sections.
language section
The divisions of the Language scripts referring to applications, forms, and fields. Each form
may have a Language script file divided into a series of Language sections such as
BEFORE FORM and INIT FIELD.
locking
Protecting selected records or tables from being modified or read. Different levels of locking
are set for each transaction depending on the amount of protection necessary for your
transaction and the amount of interference you can tolerate from other transactions.
margin
The absolute left or right edge of information in a screen field. For entries that are longer
than the field window, the right margin extends beyond the right edge of the window. Also,
after scrolling horizontally to the right, the left edge of the information may no longer
coincide with the left edge of the window.
524
master application form
A special form that serves as an entry point into an application. There can only be one
Master Application form per application. This form is automatically generated by ACCELL/
Environment.
menu
A list of choices displayed to an end user or developer. If there is more than one next form
available in a running application, the end user can choose which form to execute next by
selecting from a form menu.
menu label
A message that appears on a form menu when there is more than one next form to choose
from. It is normally a one-line message describing the form's function.
meta character
A special character used to build patterns for checking input statements and for user
searches involving string fields. Meta characters can be thought of as wild card characters
that match one or more characters. The valid ACCELL/IDS meta characters are ?, *, [ and ].
? Matches a single character
* Matches a string of characters
[ ] Specify a character class
For example, if trying to find all sales representatives that have last names beginning with A
through C, the user could specify [A-C]* as a meta character sequence in the last name
field before requesting a FIND.
mode
One of the three ways in which an application operates. See user modes.
multi-occurrence form
A standard form that can display more than one record at a time.
name class
One of six classifications for ACCELL/IDS name groups. Each group of names has specific
characteristics that enable ACCELL/IDS to distinguish among names in applications.
next field
The field to be executed after the field on which the cursor rests. The next field can be
reached with the NEXT FIELD user command or by pressing the RETURN key.
Glossary
525
next form
The form to be executed after the currently displayed form. The next form can be reached
with the NEXT FORM user command, or in Language with the NEXT ACTION IS NEXT
FORM statement. Not all forms have a next form.
next record
The record following the currently displayed record. For multi- occurrence forms, the
current record is the one the cursor is positioned on. The next record can be displayed or
made current with the NEXT RECORD user command, or in Language with the NEXT
ACTION IS NEXT RECORD statement.
operator
Any of the ACCELL/Language arithmetic, relational, or bitwise operators suc a modulus
(%), logical or (OR), and exclusive bit or ("). Operators are used in expressions.
order-by field
A field, specified in the Generator, that determines the order in which to display the current
set. For example, if the order-by field is name, ACCELL/IDS sorts the selected set in
alphabetical order by name. Up to six order-by fields can be specified for each form and
you can specify ascending or descending order for each one.
precedence
The order in which operators are applied to operands. In most programming languages,
multiplication (*) has a higher precedence than addition (+), so the expression A+B*C is
equivalent to A+(B*C).
previous field
The field executed just prior to the field on which the cursor rests. The previous field can be
reached with the PREV FIELD user command.
previous form
The form preceding the currently displayed form. The previous form can be reached with
the PREV FORM user command, or in Language with the NEXT ACTION IS PREVIOUS
FORM statement.
526
previous record
The record preceding the current record. For multi-occurrence forms, the current record is
the one the cursor is positioned on. The previous record can be displayed or made current
with the PREV RECORD user command, or in Language with the NEXT ACTION IS
PREVIOUS RECORD statement.
primary key
A field or fields used to uniquely identify records in a table. Fields may be specified as
primary keys when the data base is defined. See the DBMS Developer's Reference Manual
for more information.
record
A unique group or row of related items in a data base table, such as first name, last name,
sales office, and phone number. A record includes an entry for each field in the data base
table.
relational data base
A data base containing information organized in a flexible, tabular format. The table rows
are records and the columns are fields.
required field
A field on a form that must be filled in before the end user can proceed to the next field on
the form.
reserved word
Identifiers such as SET, INPUT, BEFORE, and AFTER that are part of the ACCELL/
Language and normally cannot be used as names for fields, variables, or other elements of
the Language.
reverse video
Displaying field contents as dark characters on a bright background. Reverse video is a
screen field attribute that can be set in the Generator or in Language scripts.
row or column order
An attribute specified in the Generator that indicates whether the cursor will move down a
form by column or across a form by row when the application runs.
Glossary
527
scope of variables
The range of forms on which a Language variable can be used. The scope of a variable
includes the form it is declared on and any successor forms.
screen
The computer terminal screen. The screen is divided into two areas: the system areas and
the application area. ACCELL/IDS uses the system area to display system messages and
valid function key assignments. The processing ACCELL/IDS application uses and controls
the application area.
screen coordinates
See coordinates.
screen field
A form area used for displaying and accepting data base information or information from
other sources. There are two types of screen fields:
• Data base screen fields are linked directly to fields in the data base
• Non-data base screen fields can be manipulated in Language to display calculated
values or information from other tables.
Screen fields may be associated with different types of ACCELL/IDS variables to display
different types of information. Screen field information is displayed in field windows.
screen/target variable
An ACCELL/Language variable that has the same name as a screen field and a target field.
screen variable An ACCELL/Language variable that has the same name as a screen field.
search criteria
The user-entered information that determines the scope of a data base search. ACCELL/
IDS also allows search criteria to be established in Language. The search does not actually
take place until the FIND command is issued.
searching
The act of looking for information in a data base as the result of a user-requested FIND.
search range
The result of evaluating the Clear to Find expressions of a field. The search ranges are the
actual limits imposed on a data base search.
528
secondary key
A field or fields that identify records in a table. Used in addition to the primary key.
Secondary keys are maintained using a B-Tree mechanism and may be created or dropped
as desired. They are commonly used for name lookups, etc. See the DBMS Developer's
Reference Manual for more information.
selected set
A group of records selected from the data base as the result of a search or add/update. The
selected set consists of the target records that met the search criteria, plus any new
records the user may have added.
shell
The operating system interface that accepts, interprets, and executes commands.
sorting
The act of ordering or reordering records according to criteria specified with the order-by
field in the Generator.
stacking forms
The active form chain is a stack of forms. It would be unwise to create an application with a
deliberately long sequence of next forms, resulting in a deep stack. This can adversely
affect the speed of application execution.
statement
One of the ACCELL/Language statements. There are three types of ACCELL/Language
statements:
• Data base statements
• Screen statements
• Control statements
statement block
A group of ACCELL/Language statements starting with the keyword BEGIN and ending
with the keyword END. A statement block may be used anywhere in ACCELL/IDS that a
statement may appear.
statement list
A series of ACCELL/Language statements, optionally separated by semicolons (;).
Glossary
529
standard form
Any form created with the Generator besides the Master Application and Help forms.
status message
Information that appears in the system area of the screen to relay the current status of
application execution to the end user.
system area
See screen.
system function
Part of a set of ACCELL/IDS functions that performs conversions from one data type to
another, and performs various useful functions such as giving the date, time, user name,
etc.
table
The largest division of a relational data base that contains a set of related records. The
rows in a table are the individual records; the columns are the fields of the records. The
design of the data base determines the structure and number of tables it contains.
target table
A table in the data base that is the target table of a particular form.
target variable
An ACCELL/IDS variable having the same name as a target table (data base) field.
termcap
The terminal capabilities file. A standard operating system file that contains information
about the capabilities of the terminals in the system. This file requires several additional
entries for ACCELL.
transaction
A logical unit of work done by an end user on a form or group of forms. During a
transaction, certain records in the data base are protected from other users working with
the same data base.
Transactions are used to guarantee that the actions of one user do not interfere with those
of another, and to make the process of updating the data base automatic.
530
transaction level
One of two levels at which an application transaction can run. Each level provides a
different degree of protection for the data base.
trim
Any part of a form that is not part of a screen field, such as a heading or field label.
type conversion
The process of converting data from one data type to another. Type conversion can be
accomplished using the ACCELL/IDS type conversion functions. Type conversion is also
performed automatically in assignment statements for some data type combinations.
UNDEFINED
An internal ACCELL/IDS value temporarily given to variables not yet assigned values.
Variables with values of UNDEFINED are displayed as blanks on forms and are ignored in
data base searches. Such variables can be assigned to other variables but cannot be used
with any of the ACCELL/IDS operators.
unicap
The ACCELL/IDS file that links actual keyboard commands to ACCELL/Generator
commands, editing commands, and user commands.
updatable
A field value that may be modified. Changing a field may modify the corresponding target
field. The Updatable attribute determines whether or not the field can be changed.
user commands
Any of the commands such as NEXT FORM, CLEAR TO FIND, ADD/UPDATEand so forth,
that a user may issue while running an application.
user modes
The two modes available to an application end user are Add/Update/Delete and Find. In
Add/Update/Delete mod the user may add records to the data base, modify existing
records, or remove records. In Find mode, the user may select data base records that meet
specified criteria.
Glossary
531
variable
An ACCELL/IDS variable may be an identifier for a target field, a screen field, both, or a
value internal to an ACCELL/IDS application. See screen variable, target variable, screen/
target variable, and general variable.
variable attribute
One of a set of attributes that control variable characteristics like format, length, and initial
value during Find and Add. Target variables and screen variables each have a unique set of
attributes.
variable symbol
A special variable symbol that is used as a prefix to the variable names. For example, the
dollar sign ($) is a variable symbol. Such symbols help ACCELL/IDS distinguish between
variables and keywords.
video attribute
One of the four screen variable attributes–REVERSE, BLINK, LOW INTENSITY, or
UNDERLINE–that control the display of information in a field.
when expression
An expression in a CHOOSE NEXT FORM or CHOOSE FIRST FORM statement that
evaluates to TRUE or FALSE and determines the next form executed.
where expression
An expression in a SET/SELECT statement that determines which data base records the
assignments will be made from. A where expression evaluates to either TRUE or FALSE.
window
A single area displaying information on the screen. Both forms and fields are contained
inside of windows in ACCELL. See field window and form window.
zoom
A user command or special form. The ZOOM command takes the user from a field on the
current form to a Zoom form if one exists. Zoom forms can be used to maintain the data
base or to provide additional information about possible field values.
Zoom forms are created just like regular forms with the Generator. Zooms must be enabled
in Language scripts.
532
zoom form
Forms that are referenced by ENABLE ZOOM and are invoked by the end user with the
ZOOM command. Zoom forms offer a view into other parts of the data base without leaving
the context of a transaction.
Zoom forms are often used for displaying information or performing tasks that are not done
as frequently as other application tasks. The process of calling up a Zoom form with the
ZOOM user command is called zooming.
Glossary
533
534

Unify ACCELL/IDS Reference

Transcription

Similar documents

Cybersecurity Monitoring

1.800.ROTUNDA www.OneRotunda.com

Spring 2012 - College of Humanities and Sciences

Heads` Letter for December 18, 2008

Fake ID - Pennsylvania Liquor Control Board

Intrusion Detection Systems What To Observe? What To Observe?

Official Show Preview

HEADS` LETTER AUGUST 28, 2008

Alumni Newsletter

ACTIVATING YOUR PRE-PAID IN-STORE