Dec 242017
| Documentation for Oadpro*. | |||
|---|---|---|---|
| File Name | File Size | Zip Size | Zip Type |
| OASDOC1.TXT | 520900 | 111951 | deflated |
| READ41.TXT | 25861 | 6969 | deflated |
Download File OASDOC.ZIP Here
Contents of the OASDOC1.TXT file
Open Architecture
Open Architecture
Screen Interface System
Screen Interface System
( O A S I S )
( O A S I S )
Version 4.1 - Evaluation
Version 4.1 - Evaluation
EUREKA SOFTWARE ASSOCIATES
EUREKA SOFTWARE ASSOCIATES
REFERENCE MANUAL
REFERENCE MANUAL
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
O A S I S
NOTICE
NOTICE
______
This document and the information contained herein as well as the
described software 'OASIS' (Open Architecture Screen Interface
System) are protected by international copyright law and treaty
provisions.
They are provided to you under a shareware scheme whose conditions
and terms are explained in Appendix B of this manual and may only be
used in accordance with these conditions.
Both this documentation and the program are provided strictly on an
Both this documentation and the program are provided strictly on an
'As Is' Basis.
'As Is' Basis.
There is no warranty, expressed or implied, with respect to the
program or the documentation, including but not limited to
merchantability and fitness for a particular purpose with respect to
defects in the program or the documentation. In no event shall Martin
Hossfeld be liable for any loss of profit or any other damage,
including but not limited to special, incidental, consequential or
other damages.
Copyright (C) 1987, 1988
EUREKA SOFTWARE ASSOCIATES
Martin Hossfeld Remy Fesnoux
12, Pinewood Green 2344 Yorkshire
Iver Heath, Bucks. SL0 0QP Ann Arbor, MI 48104
United Kingdom USA
All Rights Reserved.
All Rights Reserved.
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
Acknowledgements
Acknowledgements
________________
IBM, IBM PC, XT, AT and PC DOS are trademarks of International
Business Machines Corporation.
Burroughs and TD830 are trademarks of Unisys Corporation.
Turbo Pascal is a registered trademark of Borland International Inc.
MS DOS is a registered trademark of Microsoft Corporation.
Hercules Craphics Card is a trademark of Hercules Computer
Technology.
OASIS, SFD, SCL, Screen Format Designer, Screen Control Language and
Open Architecture Screen Interface System are trademarks of EUREKA
SOFTWARE ASSOCIATES.
'Lightning' is a trademark of PCSG Inc.
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
Introduction
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . 12
What is OASIS? . . . . . . . . . . . . . . . . . . . . . . 12
About this manual
. . . . . . . . . . . . . . . . . . . . . 13
What this manual assumes
. . . . . . . . . . . . . . . . . 14
What you will learn
. . . . . . . . . . . . . . . . . . . . 14
Chapter I
Chapter I . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
Overview
. . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
The Screen Format Designer (SFD)
. . . . . . . . . . . . . 20
The Screen Control Language (SCL) . . . . . . . . . . . . . 21
Application programs written with OASIS . . . . . . . . . . 22
Some Feature Explanations . . . . . . . . . . . . . . . . . 23
Screen Related Program Parameters . . . . . . . . . . 23
Colors and Display Attributes . . . . . . . . . . . . 23
Non Standard Keyboard Layouts . . . . . . . . . . . . 23
Program development with OASIS . . . . . . . . . . . . . . . . . 24
A. Declarative Phase . . . . . . . . . . . . . . . . . . . 24
B. Procedural Phase . . . . . . . . . . . . . . . . . . . . 25
Differences to traditional program development . . . . . . . . . 26
What instead of how . . . . . . . . . . . . . . . . . . . . 26
Early Tests . . . . . . . . . . . . . . . . . . . . . . . . 26
Less Programming . . . . . . . . . . . . . . . . . . . . . 26
Easier changes . . . . . . . . . . . . . . . . . . . . . . 26
Nationalization, customization made simple . . . . . . . . 26
System Installation and Setup . . . . . . . . . . . . . . . . . 27
The Distribution Disks . . . . . . . . . . . . . . . . . . 27
System Requirements . . . . . . . . . . . . . . . . . . . . 28
Installation Instructions
. . . . . . . . . . . . . . . . . 29
Chapter II
Chapter II . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
Explanation of keyboard functions . . . . . . . . . . . . . . . 33
Variables and Constants . . . . . . . . . . . . . . . . . . 33
Variable field specials . . . . . . . . . . . . . . . . . . 34
Editing keys . . . . . . . . . . . . . . . . . . . . . . . 34
Return . . . . . . . . . . . . . . . . . . . . . . . . . . 35
Escape . . . . . . . . . . . . . . . . . . . . . . . . . . 35
Function keys . . . . . . . . . . . . . . . . . . . . . . . 36
Errors & Automatic Help System . . . . . . . . . . . . . . . . . 37
Invalid data entry . . . . . . . . . . . . . . . . . . . . 37
Missing mandatory data . . . . . . . . . . . . . . . . . . 37
Autohelp feature . . . . . . . . . . . . . . . . . . . . . 37
Design Cycle . . . . . . . . . . . . . . . . . . . . . . . . . . 38
Designing a format layout . . . . . . . . . . . . . . . . . 40
Layout editor - Meaning of keys . . . . . . . . . . 41
Changing the Format Size . . . . . . . . . . . . . . . 42
Introduction page 4
Introduction page 4
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
Drawing fields . . . . . . . . . . . . . . . . . . . . 43
Drawing boxes . . . . . . . . . . . . . . . . . . . . 44
Selecting Linestyles . . . . . . . . . . . . . . . . . 45
Field specifications . . . . . . . . . . . . . . . . . 46
Format Control Specifications . . . . . . . . . . . . 49
User Function Key Specifications . . . . . . . . . . . 49
Testing a Format
. . . . . . . . . . . . . . . . . . . . . 51
Change field specs/Active field . . . . . . . . . . . 51
Change field specs/Other field . . . . . . . . . . . . 51
Global Colors/Attributes . . . . . . . . . . . . . . . 51
Format/Control Specs . . . . . . . . . . . . . . . . . 51
Colors/Attributes . . . . . . . . . . . . . . . . . . . . . 52
Field Attributes . . . . . . . . . . . . . . . . . . . 52
Color Screen Attributes . . . . . . . . . . . . . . . 53
Monochrome Attributes . . . . . . . . . . . . . . . . 54
Conclusion . . . . . . . . . . . . . . . . . . . . . . . . 55
Functional Description - Introduction . . . . . . . . . . . . . 57
SFD Basic Program Layout . . . . . . . . . . . . . . . . . 58
Files used by SFD . . . . . . . . . . . . . . . . . . . . . 59
SFD.FOR . . . . . . . . . . . . . . . . . . . . . . . 59
SFD.FIN . . . . . . . . . . . . . . . . . . . . . . . 59
SFD.MSG . . . . . . . . . . . . . . . . . . . . . . . 59
SFD.ERR . . . . . . . . . . . . . . . . . . . . . . . 59
SFD.DEF . . . . . . . . . . . . . . . . . . . . . . . 59
Files generated by SFD . . . . . . . . . . . . . . . . . . 60
Basic Keyboard Functions . . . . . . . . . . . . . . . . . 61
Online Help Facility . . . . . . . . . . . . . . . . . . . 62
Explanatory field input informations . . . . . . . . . 62
AutoHelp . . . . . . . . . . . . . . . . . . . . . . . 62
Format Help . . . . . . . . . . . . . . . . . . . . . 62
Field Help . . . . . . . . . . . . . . . . . . . . . . 62
Input Error Handling . . . . . . . . . . . . . . . . . . . 63
Invalid Key . . . . . . . . . . . . . . . . . . . . . 63
Wrong data . . . . . . . . . . . . . . . . . . . . . . 63
Missing mandatory data . . . . . . . . . . . . . . . . 63
The Main Menu . . . . . . . . . . . . . . . . . . . . . . . . . 64
The Menu Header . . . . . . . . . . . . . . . . . . . . . . 64
Act DIR . . . . . . . . . . . . . . . . . . . . . . . 64
Workfile . . . . . . . . . . . . . . . . . . . . . . . 64
Formats . . . . . . . . . . . . . . . . . . . . . . . 64
The Main body . . . . . . . . . . . . . . . . . . . . . . . 64
The Message Line . . . . . . . . . . . . . . . . . . . . . 64
DESIGN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
FILE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
Load File . . . . . . . . . . . . . . . . . . . . . . . . . 66
CHDir . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
Crunch . . . . . . . . . . . . . . . . . . . . . . . . . . 67
Introduction page 5
Introduction page 5
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
FORMAT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
Copy . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
Delete . . . . . . . . . . . . . . . . . . . . . . . . . . 68
Undelete . . . . . . . . . . . . . . . . . . . . . . . . . 68
Transfer . . . . . . . . . . . . . . . . . . . . . . . . . 68
DISPLAY . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
Formats . . . . . . . . . . . . . . . . . . . . . . . . . . 69
Files . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
Directory . . . . . . . . . . . . . . . . . . . . . . . . . 69
PRINT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
Single format . . . . . . . . . . . . . . . . . . . . . . . 70
All formats . . . . . . . . . . . . . . . . . . . . . . . . 70
Format list . . . . . . . . . . . . . . . . . . . . . . . . 70
DEFAULTS . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
Design . . . . . . . . . . . . . . . . . . . . . . . . . . 71
Left Field Limit . . . . . . . . . . . . . . . . . . . 71
Right Field Limit . . . . . . . . . . . . . . . . . . 71
Background Color . . . . . . . . . . . . . . . . . . . 71
Foreground Color . . . . . . . . . . . . . . . . . . . 71
Surrounding Area . . . . . . . . . . . . . . . . . . . 72
System defaults . . . . . . . . . . . . . . . . . . . . . . 73
Auto Help . . . . . . . . . . . . . . . . . . . . . . 73
After n Errors . . . . . . . . . . . . . . . . . . . . 73
Beep yes/no . . . . . . . . . . . . . . . . . . . . . 73
Length (ms) . . . . . . . . . . . . . . . . . . . . . 73
Pitch (Hz) . . . . . . . . . . . . . . . . . . . . . . 73
Field Blink Frequency . . . . . . . . . . . . . . . . 73
Char YES . . . . . . . . . . . . . . . . . . . . . . . 74
Char NO . . . . . . . . . . . . . . . . . . . . . . . 74
Cursor Wraparound Disabled . . . . . . . . . . . . . . 74
EXIT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
Terminate Program . . . . . . . . . . . . . . . . . . . . . 75
Format Design . . . . . . . . . . . . . . . . . . . . . . . . . 76
Basic Work Flow . . . . . . . . . . . . . . . . . . . . . . . . 76
The Layout Editor . . . . . . . . . . . . . . . . . . . . . 77
Layout editor Meaning of keys . . . . . . . . . . . . 78
Drawing Fields . . . . . . . . . . . . . . . . . . . . 79
Special Functions . . . . . . . . . . . . . . . . . . 80
Menu Functions . . . . . . . . . . . . . . . . . . . . 83
Format Specifications . . . . . . . . . . . . . . . . 85
The Test Feature . . . . . . . . . . . . . . . . . . . . . 94
Introduction . . . . . . . . . . . . . . . . . . . . . 94
The local Menu . . . . . . . . . . . . . . . . . . . . 94
System Limitations . . . . . . . . . . . . . . . . . . 95
Chapter III
Chapter III . . . . . . . . . . . . . . . . . . . . . . . . . . 97
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . 100
SCL Files . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
Introduction page 6
Introduction page 6
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
SCL.TPU . . . . . . . . . . . . . . . . . . . . . . . . . . 101
SCL.ERR . . . . . . . . . . . . . . . . . . . . . . . . . . 101
SCL - Global Declarations . . . . . . . . . . . . . . . . . . . 102
General . . . . . . . . . . . . . . . . . . . . . . . . . . 102
SCL Control Parameters . . . . . . . . . . . . . . . . . . 103
Max_Error_Messages . . . . . . . . . . . . . . . . . . 103
Max_Input_Messages . . . . . . . . . . . . . . . . . . 103
Max_Heap_Screens . . . . . . . . . . . . . . . . . . . 103
File Names . . . . . . . . . . . . . . . . . . . . . . . . 104
Screenfile_Ext . . . . . . . . . . . . . . . . . . . . 104
Indexfile_Ext . . . . . . . . . . . . . . . . . . . . 104
Errorfile_Ext . . . . . . . . . . . . . . . . . . . . 104
Messagefile_Ext . . . . . . . . . . . . . . . . . . . 104
Help System Parameters . . . . . . . . . . . . . . . . . . 105
Autohelp_Screen . . . . . . . . . . . . . . . . . . . 105
Maxerrors . . . . . . . . . . . . . . . . . . . . . . 105
Auto_Help_Set . . . . . . . . . . . . . . . . . . . . 105
Code_Help_Field . . . . . . . . . . . . . . . . . . . 105
Code_Help_Format . . . . . . . . . . . . . . . . . . . 105
Beep Parameters . . . . . . . . . . . . . . . . . . . . . . 106
Beep_Off . . . . . . . . . . . . . . . . . . . . . . . 106
Beep_Time . . . . . . . . . . . . . . . . . . . . . . 106
Beep_Frequency_1 . . . . . . . . . . . . . . . . . . . 106
Beep_Frequency_2 . . . . . . . . . . . . . . . . . . . 106
Message Display . . . . . . . . . . . . . . . . . . . . . . 107
Input_Msg_Set . . . . . . . . . . . . . . . . . . . . 107
Error_Msg_Set . . . . . . . . . . . . . . . . . . . . 107
Field Attributes . . . . . . . . . . . . . . . . . . . . . 108
Blink_Count . . . . . . . . . . . . . . . . . . . . . 108
Timer_Intervall . . . . . . . . . . . . . . . . . . . 108
Mark_Field_Left . . . . . . . . . . . . . . . . . . . 108
Mark_Field_Right . . . . . . . . . . . . . . . . . . . 108
Key Specifications . . . . . . . . . . . . . . . . . . . . 109
Code_Cancel_Act . . . . . . . . . . . . . . . . . . . 109
Code_Abort . . . . . . . . . . . . . . . . . . . . . . 109
Code_Escape . . . . . . . . . . . . . . . . . . . . . 109
Performing 'Edit' functions . . . . . . . . . . . . . . . . 110
Function Keys . . . . . . . . . . . . . . . . . . . . . . . 110
Nationalisation Parameters . . . . . . . . . . . . . . . . 111
Code_Yes . . . . . . . . . . . . . . . . . . . . . . . 111
Code_No . . . . . . . . . . . . . . . . . . . . . . . 111
Character sets for Variables . . . . . . . . . . . . . . . 111
Country Information Parameters . . . . . . . . . . . . . . 112
SCL_Country . . . . . . . . . . . . . . . . . . . . . 112
Country . . . . . . . . . . . . . . . . . . . . . . . 112
Date_Format . . . . . . . . . . . . . . . . . . . . . 112
Date_Separator . . . . . . . . . . . . . . . . . . . . 112
Time_Separator . . . . . . . . . . . . . . . . . . . . 113
Currency . . . . . . . . . . . . . . . . . . . . . . . 113
SCL Control Parameters . . . . . . . . . . . . . . . . . . 114
Introduction page 7
Introduction page 7
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
Progpath . . . . . . . . . . . . . . . . . . . . . . . 114
No_Wrap . . . . . . . . . . . . . . . . . . . . . . . 114
Format Pointers . . . . . . . . . . . . . . . . . . . . . . 115
S_Ptr . . . . . . . . . . . . . . . . . . . . . . . . 115
R_Ptr . . . . . . . . . . . . . . . . . . . . . . . . 115
W_Ptr . . . . . . . . . . . . . . . . . . . . . . . . 116
Format Handling Parameters . . . . . . . . . . . . . . . . 117
Active_Field . . . . . . . . . . . . . . . . . . . . . 117
Char_Code . . . . . . . . . . . . . . . . . . . . . . 117
Glb_Error . . . . . . . . . . . . . . . . . . . . . . 117
Format Handling Parameters . . . . . . . . . . . . . . . . 118
User_Function . . . . . . . . . . . . . . . . . . . . 118
Begin_Of_Field . . . . . . . . . . . . . . . . . . . . 118
End_Of_Field . . . . . . . . . . . . . . . . . . . . . 118
End_Of_Format . . . . . . . . . . . . . . . . . . . . 119
Checkrequired . . . . . . . . . . . . . . . . . . . . 119
Screen related Parameters . . . . . . . . . . . . . . . . . 120
Screen_Mode . . . . . . . . . . . . . . . . . . . . . 120
Mono_Adapter . . . . . . . . . . . . . . . . . . . . . 120
Color_True . . . . . . . . . . . . . . . . . . . . . . 120
Format related Parameters . . . . . . . . . . . . . . . . . 121
Xoff . . . . . . . . . . . . . . . . . . . . . . . . . 121
Yoff . . . . . . . . . . . . . . . . . . . . . . . . . 121
Background Processing Parameters . . . . . . . . . . . . . 122
LP_Background_Pointer . . . . . . . . . . . . . . . . 122
HP_Background_Pointer . . . . . . . . . . . . . . . . 122
Miscellaneous Parameters . . . . . . . . . . . . . . . . . 123
Glb_Status . . . . . . . . . . . . . . . . . . . . . . 123
Glb_Ok . . . . . . . . . . . . . . . . . . . . . . . . 123
Format_Aborted . . . . . . . . . . . . . . . . . . . . 123
Global Type Declarations . . . . . . . . . . . . . . . . . 124
Procedures and Functions . . . . . . . . . . . . . . . . . . . . 125
Introduction . . . . . . . . . . . . . . . . . . . . . . . 125
Entering and leaving SCL . . . . . . . . . . . . . . . . . 126
Structure of a SCL Program . . . . . . . . . . . . . . . . 127
Loading and displaying formats . . . . . . . . . . . . . . 128
X_Max and Y_Max . . . . . . . . . . . . . . . . . . . . . . 130
Handling format input . . . . . . . . . . . . . . . . . . . 131
Format Handling Control . . . . . . . . . . . . . . . . . . 133
Reading/Writting Format Fields . . . . . . . . . . . . . . 134
Introduction . . . . . . . . . . . . . . . . . . . . . 134
Reading Field Content . . . . . . . . . . . . . . . . 135
Writing Field Content . . . . . . . . . . . . . . . . 137
Deleting Field Content . . . . . . . . . . . . . . . . 138
Reading the 'Selected' Attribute . . . . . . . . . . . 139
Writing the 'Selected' Attribute . . . . . . . . . . . 140
String Handling routines . . . . . . . . . . . . . . . . . 141
System Functions . . . . . . . . . . . . . . . . . . . . . 145
Date related routines . . . . . . . . . . . . . . . . . . . 147
Time related Routines . . . . . . . . . . . . . . . . . . . 149
Introduction page 8
Introduction page 8
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
Background Processing Tasks . . . . . . . . . . . . . . . . 150
Other Routines . . . . . . . . . . . . . . . . . . . . . . 151
Chapter IV
Chapter IV . . . . . . . . . . . . . . . . . . . . . . . . . . . 153
Data Communications Subsystem . . . . . . . . . . . . . . . . . 155
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . 156
Global Communications Parameters . . . . . . . . . . . . . 157
Timers and Delays . . . . . . . . . . . . . . . . . . . . . 158
Data Communications Control Characters . . . . . . . . . . 159
Other Declarations . . . . . . . . . . . . . . . . . . . . 160
Procedures and Functions
. . . . . . . . . . . . . . . . . . . . 162
Initializing and Terminating DC . . . . . . . . . . . . . . 163
Sending Data . . . . . . . . . . . . . . . . . . . . . . . 164
Receiving Data . . . . . . . . . . . . . . . . . . . . . . 166
Other Functions . . . . . . . . . . . . . . . . . . . . . . 167
Low Level Routines . . . . . . . . . . . . . . . . . . . . 168
Example Programs
. . . . . . . . . . . . . . . . . . . . . . . . 170
A Simple Line Monitor (SAMPLE7.PAS) . . . . . . . . . . . . 171
Listing of SAMPLE7.PAS . . . . . . . . . . . . . . . . 172
Description of SAMPLE7.PAS . . . . . . . . . . . . . . 177
A Terminal Emulator Program (SAMPLE 8) . . . . . . . . . . 179
Listing of Example Program 8 . . . . . . . . . . . . . 180
Description of SAMPLE8.PAS . . . . . . . . . . . . . . 187
Program Discussion . . . . . . . . . . . . . . . . . . . . . . . 190
Introduction . . . . . . . . . . . . . . . . . . . . . . . 191
Example 1 (OASIS Easy Fields) . . . . . . . . . . . . . . 192
Explanations of SAMPLE1.PAS . . . . . . . . . . . . . 193
Example 2 (OASIS Print Labels) . . . . . . . . . . . . . . 195
Explanations of SAMPLE2.PAS . . . . . . . . . . . . . 196
Example 3 (OASIS Formats Stack) . . . . . . . . . . . . 200
Listing of SAMPLE3.PAS . . . . . . . . . . . . . . . . 201
Explanations of SAMPLE3.PAS . . . . . . . . . . . . . 202
Example 4 (OASIS Automatic Disk Menu) . . . . . . . . . . 204
Example 5 (OASIS SCL Demo) . . . . . . . . . . . . . . . . 208
Menu . . . . . . . . . . . . . . . . . . . . . . . . . 208
Country Demo . . . . . . . . . . . . . . . . . . . . . 209
Date Demo . . . . . . . . . . . . . . . . . . . . . . 211
Special Fields Demo . . . . . . . . . . . . . . . . . 213
SCL System Details . . . . . . . . . . . . . . . . . . . . . . . 216
Service Routines . . . . . . . . . . . . . . . . . . . . . 217
Background Processing Tasks . . . . . . . . . . . . . . . . 219
READING AND WRITING FIELDS
. . . . . . . . . . . . . . . . 222
SCL Input Character Processing
. . . . . . . . . . . . . . 224
The Error Message File . . . . . . . . . . . . . . . . . . 225
SCL - System Resource Considerations . . . . . . . . . . . 226
Disk Access . . . . . . . . . . . . . . . . . . . . . 226
Processor Requirements . . . . . . . . . . . . . . . . 226
Format File -Disk Space Requirements . . . . . . . . . 226
Introduction page 9
Introduction page 9
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
SCL Code Space Requirements . . . . . . . . . . . . . 226
SCL Data Space Requirements . . . . . . . . . . . . . 226
Total Memory Requirements . . . . . . . . . . . . . . 227
Tips & Tricks . . . . . . . . . . . . . . . . . . . . . . . . . 228
Entry of Characters not normally accessible via the
Keyboard . . . . . . . . . . . . . . . . . . . . . . . 228
Blinking Fields . . . . . . . . . . . . . . . . . . . . . . 228
Use of the 'Intensity' field attribute on Color systems . . 228
The 'Selected' Attribute in Menus . . . . . . . . . . . . . 228
Preventing automatic termination of a format . . . . . . . 229
Highlighting text on screen formats . . . . . . . . . . . . 229
Special Fields . . . . . . . . . . . . . . . . . . . . . . 229
Storing strings in
Using Field Input Messages for Help Screens . . . . . . . . 230
Using 'Goto_Field' . . . . . . . . . . . . . . . . . . . . 231
Alphabethic List of all User accessible SCL Procedures &
Functions . . . . . . . . . . . . . . . . . . . . . . . . . 234
Datacom Control Characters . . . . . . . . . . . . . . . . . . . 237
Field Attributes and Colors . . . . . . . . . . . . . . . . . . 238
Possible Field Attributes . . . . . . . . . . . . . . . . . 238
Colors . . . . . . . . . . . . . . . . . . . . . . . . . . 238
Functions in SCL Programs . . . . . . . . . . . . . . . . . . . 239
Standard SCL Error Messages . . . . . . . . . . . . . . . . . . 240
The Shareware Idea . . . . . . . . . . . . . . . . . . . . 241
OASIS Products & Licencing Terms . . . . . . . . . . . . . . . . 242
OASIS Demo package . . . . . . . . . . . . . . . . . . . . 242
OASIS Evaluation . . . . . . . . . . . . . . . . . . . . . 243
OASIS . . . . . . . . . . . . . . . . . . . . . . . . . . . 246
Invoice & Order Form . . . . . . . . . . . . . . . . . . . . . . 247
Order Form . . . . . . . . . . . . . . . . . . . . . . . . 247
Invoice . . . . . . . . . . . . . . . . . . . . . . . . . . 248
Introduction page 10
Introduction page 10
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
Introduction page 11
Introduction page 11
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
Introduction
Introduction
____________
What is OASIS?
What is OASIS?
OASIS stands for Open Architecture Screen Interface System.
OASIS is a fourth generation programming tool to develop screen based
application programs and User Interfaces on Micro Computers. No one
can deny that computers still primarily rely on visual and tactile
means of communication to interact with its users. With the
proliferation of microcomputers in recent years, as more and more
people became users they consequently behaved as consumers who
implicitly stressed the emphasis on human interfacing, as a result
products offered more and more ergonomic features. Among the top
features speed is definitely high on the list. Obviously the first
and most tangible advantage of fast applications is an overall gain
of time to complete a given project, however this is certainly not
the most important one. What matters more is the response time, in
other words the time it takes for the application to process
elementary tasks which if not carefully timed induce unnecessary and
undesirable delays. Neglecting this factor, no matter how small or
hardly perceptible delays can be, invariably results in operator's
irritations that may in some cases lead to reject the product.
Otherwise what the user wants is in essence a tool easy to use, quick
to learn with sufficient help information readily available on line,
flexible but logical and powerful, in other word something
comfortable and easy on the eyes that meet his expectations.
On the other side of the fence we have the programer who is tasked to
satisfy all these requirements while focussing on performance thus
making the product attractive and marketable within a tight schedule
in order to be one of the first in this competitive marketplace.
This is precisely where OASIS come into play to serve the interests
of all parties. OASIS is an immensely powerful tool for the
programmer because it allows him to cut down development time while
ensuring outstanding human interface features and still focus on the
intrinsic part of the application thus optimizing its resources and
performances. How OASIS achieves this is described in the product
overview. To illustrate what has just been is said here you ought to
know that OASIS and more specifically SFD (Screen File Designer)
itself has been designed using the semantics that governs SCL (Screen
Control Language) itself and for that reason is indeed an application
of itself, in other words SFD was designed using SFD, a sort of CATCH
22 scenario.
To sum up this brief introduction one could say that OASIS is to the
DESIGN AND MANAGEMENT OF USER INTERFACE what the advent of
wordprocessors in the mid 1970's has done to TEXT WRITING AND
EDITING.
Introduction page 12
Introduction page 12
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
About this manual
About this manual
_________________
This manual describes OASIS and its various components and how to use
them. This book articulates itself around three chapters followed by
one appendix.
CHAPTER I System Overview
CHAPTER I System Overview
The purpose of this chapter is to arouse the interest of the
reader by describing OASIS main components and listing their
features.
CHAPTER II Screen File Designer (SFD)
CHAPTER II Screen File Designer (SFD)
After a short introduction to SFD you will be paced through a
comprehensive tutorial followed by a chapter providing a
functional description of SFD.
CHAPTER III Screen Control Language (SCL)
CHAPTER III Screen Control Language (SCL)
This chapter discusses in details the major procedures and
functions that constitute the heart of the system.
CHAPTER IV SCL Data Communication subsystem
CHAPTER IV SCL Data Communication subsystem
Since OASIS can be used in a micro to mainframe environment
this chapter is entirely dedicated to the DataCommunication
extensions of SCL.
APPENDIX A
APPENDIX A
This chapter covers several advanced OASIS features and also
contains descriptions and discussions of 5 sample programs.
APPENDIX B
APPENDIX B
Lists and Tables.
OASIS products & Licencing Terms.
Introduction page 13
Introduction page 13
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
What this manual assumes
What this manual assumes
________________________
In order to fully exploit the Secret of SCL the reader is expected to
have some experience with programming languages and especially TURBO
PASCAL. We assume that the reader can refer to BORLAND manuals and
references in order to write SCL programs, compile, debug and run
them.
What you will learn
What you will learn
___________________
The best method to learn something new is to practice, make mistakes
and learn from them. From the very beginning, you will have at the
tip of your fingers all the power and the flexibility of the Screen
Format Designer SFD, you will soon realize how intuitive it can be
and it won't take long before you become familiarized with all the
keyboard functions and the system features.
The tutorial in chapter II will pace you step by step in the design
of a trivial screen letting you exercise almost every function of
SFD. Within a couple of hours you will be able to design and test
fully fledged screens.
Chapter III provides you with the basic architecture to elaborate
complex programs including multiple stacked screens (windows) and
background processing tasks.
Chapter IV will let you include data communication routines to deal
with the outside world. Finally a set of programming tips is
available in Appendix A to the expert to fine tune complex
applications to a breathtaking level.
We hope that you will very shortly be able to unleash the full power
of OASIS to your benefit, your limits being your own imagination.
Good luck and have a good time.
Introduction page 14
Introduction page 14
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
This Page is intentionally left blank
Introduction page 15
Introduction page 15
Chapter I
Chapter I
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
Open Architecture
Open Architecture
Screen Interface System
Screen Interface System
( OASIS )
( OASIS )
System Overview and Features
System Overview and Features
Chapter I, System Overview and Features page 17
Chapter I, System Overview and Features page 17
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
Overview
Overview
________
OASIS allows you to create and handle state-of-the-art screen
OASIS
interfaces with many outstanding features in a most comfortable and
efficient way. Due to its background processing capabilities the
handling of datacom and so on can also be easily achieved. OASIS is
OASIS
not an application generator. Typically, application generators
require some kind of a macro language which is usually rather limited
in terms of flexibility. This often results in slow running, clumsy
applications a too high price to be paid for added programming
convenience.
Instead, OASIS is built on top of Turbo Pascal, leaving all features
OASIS
of this powerful development system available to you for special
requirements OASIS may not be capable to fulfill.
OASIS
With OASIS you can
OASIS
* Add Micro based front ends to existing mainframe programs,
taking over anything from Screen Management up to local data
storage etc.
* Build the Micro part of distributed processing applications.
* Write completely Micro based Applications utilizing virtually
any number of screen formats.
* Develop sophisticated Terminal Emulators.
OASIS is a sophisticated and powerful user interface design and
OASIS
management system that both simplifies the task of the application
writer and provides a very attractive interface to the end user.
Using OASIS not only results in tremendeous time savings (depending
OASIS
on the kind of application between 50 and 90 percent) but also
achieves perfect results.
Chapter I, System Overview and Features page 18
Chapter I, System Overview and Features page 18
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
OASIS has two main components:
OASIS has two main components:
The Screen Format Designer (SFD)
The Screen Format Designer (SFD)
The Screen Control Language (SCL)
The Screen Control Language (SCL)
Screen Format Designer (SFD)
Screen Format Designer (SFD)
SFD is an integrated application program, itself written with OASIS,
SFD OASIS
introducing a new concept in the elaboration of screen formats. It
allows the user to interactively design any screen format layouts on
the principle of what you paint is what you get. Away from the host
application SFD lets you define all field parameters of the format
plus a large suite of other refinements such as related error
messages and help screens. Futhermore SFD enable you to dynamically
___________
test new formats before you even wrote a single line of code.
____
Screen Control Language (SCL)
Screen Control Language (SCL)
SCL is a extensive collection of Turbo Pascal Source Routines built
SCL
to cater for all aspects of format access, display, window
management, data capture, input check, display of error messages,
help system. By simply including these routines in any Turbo Pascal
Program, all of its features can be used just like a very high level,
straightforward and easy to learn language extension to Turbo Pascal.
This not only leaves all flexibility to the programmer, but enables
him to create highly professional applications with many outstanding
features in a fraction of the time usually required, which
contributes to reducing development costs considerably.
Chapter I, System Overview and Features page 19
Chapter I, System Overview and Features page 19
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
The Screen Format Designer (SFD)
The Screen Format Designer (SFD)
________________________________
The purpose of this program is to assist you to design, specify and
test all screen formats to be incorporated in an application program.
These formats are 'built' in a straightforward but comprehensive
approach using a full screen editor for the format layout and a
series of pop-up menus to define field and global parameters. Finally
under each single format name are stored not only the form
description layout and its field definitions but any information
related to that format such as reference to help screens.
Key features of SFD include :
Key features of SFD include :
- Easy to understand, Menu Driven Program with Windows.
- Online accessible, context sensitive Help facility.
- Layout design with comfortable Full Screen editor.
- Full characterset access.
- Drawing of Boxes with the opportunity to choose any linestyles
and automatic interconnections to other boxes.
- Powerful Block Copy and Delete functions.
- Outstanding selection of display attributes and
highlightfunctions, seperate for color and monochrome displays.
- A large range of pre-defined fieldtypes.
- Input validation selectable for any field.
- Up to 50 fields per format.
- Option to define and link 'Help' formats and assistance
messages to any single field.
- Unrestricted formats size up to 80 x 25.
- Number of formats per program only limited by disk space.
- Transfer of formats between different format files.
- Printing of format lists and hard copies.
- Complete inbuilt test facility for new formats.
- Dynamic alteration of format specs. and attributes during test
with results immediately being visible.
- Full support of MSDOS 2+ Subdirectory structure.
Chapter I, System Overview and Features page 20
Chapter I, System Overview and Features page 20
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
The Screen Control Language (SCL)
The Screen Control Language (SCL)
_________________________________
SCL is an extensive set of routines to access SFD generated format
SCL SFD
files and to perform all screen related functions within a Turbo
Pascal program.
The main features of SCL are:
The main features of SCL are:
- Powerful command syntax (Processing of a complete format
including input check and error handling with only three
statements).
- Automatic control of display and overlay of formats.
- Easy and comfortable access to fields.
- Support of windows including stacking to any desired depth, only
limited by the amount of memory available.
- Handling of menus, even multiple menus and/or together with data
input fields on one format.
- Full control of display attributes and formatting of fields.
- Automatic input validity checks and display of error messages.
- No requirement to declare field variables etc. in your program.
- User programmed checks or other interferences possible anytime
made simple and safe.
- Capability to monitor and flag user selectable keyboard keys and
other events.
- Changes to Formats, Messages and Input check parameters are
possible without recompiling the program.
- Highly improved conciseness and ease of understanding of
finished programs.
- Comprehensive library of procedures and functions to facilitate
date/time processing, access to DOS functions, string handling,
(data communication with full reease) and much more.
- Support of execution of other programs and even DOS commands
from within an application.
- Support of background processing tasks (datacom, printing etc).
Chapter I, System Overview and Features page 21
Chapter I, System Overview and Features page 21
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
Application programs written with OASIS.
Application programs written with OASIS.
________________________________________
The use of OASIS results in very ergonomic application programs with
The use of OASIS
outstanding handling capabilities and many userfriendly features
like:
- Automatic display of assisting messages for each single field.
- Extensive Online Help System with four different, user
selectable levels.
- Automatic Input error handling and display of error messages.
- Adaptability to different systems/keyboard layouts.
- Simple and straightforward Nationalisation and Customisation.
- Full Support for both Color and Monochrome displays.
- Undo function.
- Abort function.
- Mouse support very simple to accomplish.
- Interrupt driven Data Communications Handling
Chapter I, System Overview and Features page 22
Chapter I, System Overview and Features page 22
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
Some Feature Explanations.
Some Feature Explanations.
__________________________
Screen Related Program Parameters
Screen Related Program Parameters
In OASIS written application programs most screen related parameters
OASIS
are stored in data files. This includes the format layouts
themselves, the field details, error messages, help and explanatory
information, field input check/validation parameters, colors,
attributes and much more.
All these parameters can be altered anytime using SFD.
SFD
This presents several advantages:
1. Program changes are often possible without recompiling.
2. Nationalisation and customisation of programs, otherwise often
very tedious and time consuming tasks become effortless and easy
to accomplish.
3. The program sources are more compact, easier to understand and
do compile faster.
Colors and Display Attributes
Colors and Display Attributes
OASIS written applications automatically recognize the type of
OASIS
display adapter and therefore utilize the suitable screen attributes.
For optimum result, two totally independent sets of attributes are
provided for each format/field, one for color graphic and one for
monochrome display adapters.
Note: OASIS works in 80 column modes only.
Note:
Non Standard Keyboard Layouts
Non Standard Keyboard Layouts
SCL written applications can easily be adapted to non standard
SCL
Keyboards. The Codes of all relevant keys are stored as constants and
can be adapted as required.
Chapter I, System Overview and Features page 23
Chapter I, System Overview and Features page 23
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
Program development with OASIS
Program development with OASIS
______________________________
It is made up of two distinct phases.
A. Declarative Phase
A. Declarative Phase
This Phase is completely performed using SFD. It consists of the
SFD
following steps:
1. Define all screen formats and fields required.
For each Format do the following:
2. Using the screen editor, design its layout including location
and size of all required fields.
3. Using pop-up menus then specify the appearance of the format,
define whether special checks are required or not for this
format and establish if and when other external actions are to
be performed.
4. Always using pop-up menus determine if and in which fields
error and explanatory messages are to be displayed.
5. Again using pop-up menus specify for each field, the type
(Variable, Constant, Output) and define its parameters like
special appearance, attributes, formatting, necessary checks,
explanatory message,inter field dependencies and so on.
6. Finally test the format using the SFD test facilities. The
SFD
format behaves just as if it was already integrated in your
program. You can therefore safely test input checks,
formatting, help system and many other things. You may find
that you are not satisfied with one or another detail. No
problem, you can do most changes right away, without even
leaving the test. The results will be immediately visible to
you. Only for some major changes like basic layout or field
types you would have to go back to the Design facility.
7. Once you are pleased with your format, you can assign help
screens to it (this can be done anytime later on). There are
many different possibilities for the help system, please look
under "The OASIS Help System" for details.
"The OASIS Help System"
Chapter I, System Overview and Features page 24
Chapter I, System Overview and Features page 24
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
B. Procedural Phase
B. Procedural Phase
1. Now the time has come to actually begin programming using SCL
SCL
constructs.
The first approach is to build some sort of skeleton program,
containing all switching logic between different formats and so
forth.
2. You then compile this skeleton and experiment with the basic
logic to assess its functionality and see if it is what you
wanted initially. By now, you will have an exact idea how the
final program will look like and you already have spared
yourself precious time since you will require a lot less testing
and changes later on.
3. You complete your program by adding all the missing logic into
the skeleton.
4. You perform the final testing and fine tuning as required.
Chapter I, System Overview and Features page 25
Chapter I, System Overview and Features page 25
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
Differences to traditional program development
Differences to traditional program development
______________________________________________
What instead of how
What instead of how
Obviously the first difference with conventional user interface
approach is that you do not have to specify how your formats are to
be built. As a matter of fact this is the essence of the OASIS
concept. All you have to do is draw them and tell SFD what they
should look like. It is no longer neccessary to write procedures to
check or to format the fields content.
As a general rule, just declare what should be done, not how to do
____ ___
it.
Early Tests
Early Tests
Most of the necessary test work can be performed at quite an early
stage of the program development, ensuring that conceptual errors are
detected early enough to take corrective actions before things get
out of control.
Less Programming
Less Programming
Another strength resides in the fact that much of the programming is
already done before you even start to generate a program source. Once
you really start programming, you will realize that SCL constructs
SCL
allow you to remain in the declarative mode. Since you don't have to
declarative
develop procedures, you can concentrate on more global aspects of
your program and, as a side effect, you'll save a considerable amount
of time.
Easier changes
Easier changes
During program development a lot of changes have to be made to the
program. Even once a program is finished, you usually never really
stop changing it. For programs written with OASIS this becomes a lot
OASIS
easier. If the changes are in the screen interface, you can usually
perform them via SFD without even recompiling the program. Even if
SFD
this is not the case, it becomes a lot easier to do since your
program source is much more concise and thus more intelligible.
Nationalization, customization made simple
Nationalization, customization made simple
All screen formats and all program messages are stored in data files,
easily accessible with SFD. Customisation of screens and/or messages
SFD
or even translation of a whole program into other languages become
mondaine tasks, without even recompiling the program.
Chapter I, System Overview and Features page 26
Chapter I, System Overview and Features page 26
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
System Installation and Setup
System Installation and Setup
_____________________________
The Distribution Disks
The Distribution Disks
On the OASIS Distribution disks you'll find the following files:
On the OASIS Distribution disks you'll find the following files:
READ.ME Textfile containing last minute information.
SCL.TPU Turbo Pascal 4.0 Unit file containing all Screen
Screen
Control Language (SCL) Routines and definitions.
Control Language
In order to access SCL you must include 'SCL' in
your 'USES' statement.
SCL.DOC Source of the 'Interface' Part of SCL.TPU.
SFD.EXE Screen Format Designer Program.
SFD.ERR Text file containing error messages for SFD.EXE.
SFD.MSG Data file containing explanatory program messages
for SFD.EXE.
SFD.FOR Screenfile for SFD.EXE.
SFD.FIN Screen index file.
SCL.ERR Optional (Error-) Message file to be used for your
programs. You can add your own messages as required.
SAMPLExS Turbo Pascal program examples to demonstrate SCL.
SAMPLEx.EXE Compiled versions of the above.
SAMPLEx.SCS Screenfiles to above.
SAMPLEx.SCI Indexfiles to above.
SAMPLEx.MSG Message files to above.
SAMPLEx.ERR Error messages to above.
Chapter I, System Overview and Features page 27
Chapter I, System Overview and Features page 27
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
System Requirements
System Requirements
IBM PC or compatible
256 KB Memory minimum
Hard disk *)
PC DOS/MS-DOS 2.0 or later
Turbo Pascal 4.0 or later
*) Note:
Note
The Screen Format Designer program requires a hard disk in order to
Screen Format Designer
run.
Other typical Application Programs build with OASIS normally run
OASIS
happily on a floppy system.
See Appendix A for Details on System Resource Considerations.
See Appendix A for Details on System Resource Considerations.
Chapter I, System Overview and Features page 28
Chapter I, System Overview and Features page 28
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
Installation Instructions
Installation Instructions
_________________________
There is no special Installation procedure necessary since OASIS is
not copy protected.
Just create a subdirectory on your hard disk and copy the content of
both distribution disks to it.
Now add to your CONFIG.SYS file the following two statements:
FILES=16
FILES=16
BUFFERS=32
BUFFERS=32
If your configuration file should already contain a "FILES=nn"
statement, then you just increase the number to at least 16; if it is
already bigger, leave it as it is.
The same applies to the "BUFFER=nn" Statement.
This completes the installation.
To start the Screen Design Program just go to the subdirectory you've
loaded the distribution disks to (using the DOS Command "CD") and
enter SFD
SFD
Chapter I, System Overview and Features page 29
Chapter I, System Overview and Features page 29
Chapter II
Chapter II
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
Chapter II, SFD getting started page 31
Chapter II, SFD getting started page 31
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
The Screen Format Designer
The Screen Format Designer
( S F D )
( S F D )
Getting Started
Getting Started
(A Short Tutorial)
(A Short Tutorial)
Chapter II, SFD getting started page 32
Chapter II, SFD getting started page 32
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
Explanation of keyboard functions
Explanation of keyboard functions
At first you will probably find the following explanations rather
complicated and confusing, but upon trying you will soon find that
everything does function in a very intuitive way and you will very
quickly get familiar with it. Much care has been taken regarding the
way the different functions are layed out to achieve ease of
operation and a maximum of ergonomy.
Variables and Constants
Variables and Constants
Variables and Constants are the two main categories of format fields.
Whenever you happen to see the cusor, either as a blinking underline
character or as a big block (which may or may not blink) you are in a
Variable field and you are expected to enter some data.
Variable
If the cursor is not visible you are in a Constant field. You can't
Constant
enter any data into Constants, all you can do is to select or
deselect them by pressing Return or Enter. A typical example for
Return Enter.
Constant fields is a Menu. You just select one (in some cases more
Constant
than one) possibility out of a choice being presented to you.
The keys to travel between fields and their functions are as follows:
The keys to travel between fields and their functions are as follows:
Right : Next Field.
Left : Previous Field.
Down : First field on next line.
Up : Last field on previous line.
Home : First field in line.
End : Last field in line.
PgDn : Last field on format.
PgUp : First field on format.
Tab : Next field.*)
ShiftTab : Previous field.*)
Note:
Note:
*) Tab and Right respectively ShiftTab and Left are not identical.
See next paragraph.
Chapter II, SFD getting started page 33
Chapter II, SFD getting started page 33
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
Variable field specials
Variable field specials
Upon approaching a Variable field you will realize several things
happening.
1. The present content of the field (if there is any) is being
shifted to the left, no matter how it was formatted before. this
is done in order to facilitate the entry or change of data.
2. In some cases, the part of the field not yet containing data is
flushed with Fill characters (usually dots) or the whole field
Fill
is being underlined. Whichever the case, the intention is to
give you an indication of the length of the field, i.e. how much
space is left for data input.
3. The Cursor is visible in form of a blinking Underline character.
Once you start entering data, the shape of the cursor changes to a
big block which may or may not blink. This indicates that you are now
in Entry mode and that the left and right arrows have changed their
Entry
meaning. Now Right advances you one character position and Left moves
Right Left
you to the previous character. Note that Tab and ShiftTab keep their
Tab ShiftTab
original functions. If you press Right while already being in the
Right
rightmost position of the field or if you press Left while being at
Left
the first character of the field you will be notified by a Beep.
Beep.
Besides just entering data, there is an alternate method to change
from Travel to Entry mode : Pressing Return. This is especially handy
Travel Entry Return
in cases where you want to change already existing data in a field
and you need to advance to the appropriate character position(s)
using the arrows.
arrows
Editing keys
Editing keys
Backspace : Deletes character left of cursor.
Insert : Inserts a space at cursor position.
Delete : Deletes character under cursor.
Note: Entering data into the rightmost position of a Variable
Note: Variable
automatically advances you to the next field.
Chapter II, SFD getting started page 34
Chapter II, SFD getting started page 34
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
Return
Return
As previously mentioned, pressing Return while in a Variable field
Return Variable
puts you into Entry Mode. Once you are in Entry mode pressing Return
Entry Entry Return
finishes this field an advances you to to the next one or, if this
field was the last one, terminates the format.
The resulting effect on the field content varies depending on your
position within the field.
If you were in the first position, the entire current field content
is captured. For all other positions only the portion of the field
left of the cursor is recognized.
While in a Constant field, pressing Return toggles the status of the
Constant Return
field from not selected to selected and vice versa. The cursor will
not selected selected
automatically be advanced to the next field. In case you are already
in the last field the format will be terminatedn
In some cases, Constant fields can form a group, typically some kind
Constant
of a menu. In these cases only one field out of that group may be
selected at any given time. So, if you select a field other than the
one presently already selected, the latter one will automatically be
deselected. If a field of such a group has been selected, the cursor
automatically advances to the field immediately following the group
(in case there is none left, the format will be automatically
terminated).
Selecting an item out of a group of Constant fields may or may not be
Constant
mandatory. In case it is, you are not allowed to deselect a field
deselect
(i.e. pressing Return in a field being presently selected results in
Return selected
a Beep or an error message to be displayed).
Beep
In such cases, deselecting a field is automatically done as soon as
deselecting
you select another field. This is very much the same as on a TV-Set
select
where you deselect a channel by just choosing another one.
Escape
Escape
Escape can be used to tell the program independently of the cursor
position that you are finished with the present format and you want
to exit it.
Chapter II, SFD getting started page 35
Chapter II, SFD getting started page 35
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
Function keys
Function keys
F1
F1
Pressing F1 displays General Help Informations including key
F1
functions etc.
F2
F2
F2 displays specific Informations relative to what you are presently
doing. Please note that F2 help is not available for every format. In
F2 help
such cases, if you press F2 you will just hear a beep.
F2 beep.
F3
F3
The UNDO key. Pressing F3 will restore the content of your present
F3
field to whatever it was before you changed it; i.e. will UNDO your
changes. Note that UNDO only applies to Variable fields.
Variable
F10
F10
The ABORT key. Pressing F10 tells the program that you want to
F10
unconditionally abort your present operation. Any data you may have
entered on your present format will be lost. For this reason, Abort
Abort
is only available with a few formats.
Formats where Abort is not available can typically only be exited by
Abort
hitting the Escape key while the data fields are empty.
Escape
Other (local) functions
Other (local) functions
On some formats there may be further functions available. Pressing F1
F1
(Help) will always give you the appropriate details.
Chapter II, SFD getting started page 36
Chapter II, SFD getting started page 36
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
Errors & Automatic Help System
Errors & Automatic Help System
______________________________
Invalid data entry
Invalid data entry
Whenever you try to enter invalid data you will be notified by a Beep
Beep
and, in some cases, a system generated error message may be
displayedn
Missing mandatory data
Missing mandatory data
If you attempt to exit a format before having entered all mandatory
fields, the program will notify you in the same way as in the case of
invalid data. In addition, the cursor will automatically be
positioned into the field where data is missing.
Autohelp feature
Autohelp feature
If you make a certain number of consecutive input errors (Default =
3) the program will automatically come up with information where and
how to obtain help.
Note: You can change nearly all Help system Parameters according to
Note:
your requirements.
See under 'System Defaults' for details.
Chapter II, SFD getting started page 37
Chapter II, SFD getting started page 37
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
Design Cycle
Design Cycle
____________
To make you familiar with the operation of SFD we will now go
together through the complete cycle of design and specification of a
format.
During this exercise we will also look at some of the features the
program offers. Once we are done with the design of your format we
will test it using SFD's own test facility.
Those already familiar with the basic operation of SFD can skip this
Those already familiar with the basic operation of SFD can skip this
part of the manual.
part of the manual.
Start the program by entering SFD
SFD
right directory).
After a short moment you will be presented with the programs main
menu.
It is divided into three parts.
The header shows the program name, version etc as well as some
informations about the directory you have selected, the workfile and
the number of formats in it.
Since you have just started up the program the following information
should be displayed.
Act dir :
Workfile :
Nr of Formats: 0.
The middle part of the menu is occupied by a number of menu items,
subdivided into seven groups.
Presently, the first item (Layout) of the first group (Design) should
be highlighted.
The last line of the menu is called Message Line and gives you a
Message Line
brief explanation of the highlighted item.
If you press F1 (just do it !) a screen informing you about the
F1
meaning of keys etc will appear.
To leave the Help format press either Return or Escape.
Return Escape.
F2 will give you a bit more detailed Information about the presently
F2
highlighted group of items on the menu. Again, to leave the help
format you must press Return or Escape.
Return Escape.
You can use F1 on any format, F2 may not be available in some cases.
F1 F2
Chapter II, SFD getting started page 38
Chapter II, SFD getting started page 38
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
You can travel around on the menu using the appropriate keys. If you
don't know which ones either look in this manual under 'Meaning of
keys' or press F5. While you are traveling around on the menu, watch
F5
the message line changing.
| You may also want to press F2 while being in different fields and
read the appropriate explanations.
Once you are familiar with how to travel on a format, we can proceed
to some 'real' work.
| Before we start I want to remind you of the two 'Help' keys F1 and F2
During this exercise it is probably a good idea to use them very
frequently (Especially F2) and read the information they containn
| Don't forget that the help provided by F2 is context sensitive (i.e.
the kind of information provided may change depending where you
presently are on the format.
Should you require further detailed informations, then read the
appropriate chapter later on in this manual.
Chapter II, SFD getting started page 39
Chapter II, SFD getting started page 39
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
Designing a format layout
Designing a format layout
_________________________
1. Travel to the appropriate item (Layout).
2.
| Hit Return. This selects the item.
Since you have not yet loaded a work filel SFD will come up with a
SFD
tiny window asking you for a name.
Enter a name (without extension since SFD uses its own extensions),
SFD
| say 'Myfile', and press Return.
The window disappears again and a new one will come up informing you
that SFD will ask you whether you want to create a new format. You
SFD
say yes.
Now you will be presented with the layout editor's worksheet (a fancy
name for an empty screen, isn't it ?).
It's size defaults to 25 lines with 80 characters each (a full
screen).
In order to familiarize you with the different features, you should
| now read both the F1 and F2 help formats.
| You probably have already noticed some additional functions on F4 to
| F9 During our little exercise we will try out most of them.
However we should first talk about the other keys. Some have a
slightly different meaning as on a normal format.
Chapter II, SFD getting started page 40
Chapter II, SFD getting started page 40
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
Layout editor - Meaning of keys
Layout editor - Meaning of keys
| Backspace, Insert and Delete have the same meaning as under normal
operation.
| Home moves the cursor to the upper left corner of your
worksheet.
| End moves the cursor to the first position on the last
line.
| PgUp deletes the line under the cursor.
| PgDn inserts a line.
| Return moves the cursor to the first character of the next
line.
| The Arrow keys allow you to move freely on the format. Note that the
| Arrows are working in wrap-around mode. This means that:
| If you press Right while being in the rightmost position you will be
moved to the first position of the next line.
| If you press Left while being in the first position of a line you
will be moved to the last position of the previous line.
Right while being in the lower right corner moves you to the upper
| left corner; the opposite happens if you then press Left.
| Pressing Up while being in the first line moves you to the last line
| and the opposite happens with Down while in the last line.
Before starting to draw a format we will learn how to specify its
size. (The size can actually be changed anytime during the layout
design).
Chapter II, SFD getting started page 41
Chapter II, SFD getting started page 41
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
Changing the Format Size
Changing the Format Size
| Press F9. This will display the editors local menu. Select the first
item (Change format size). A new window comes up with the present
settings. Just enter new values, let's assume 15 lines with 40
characters each. That's it.
You'll now see that the unused portion of the screen is filled with
tiny dots. This is done to give you an idea of your drawing area.
You will also realize that cursor movement is now confined to this
area.
Now we will start drawing a screen format.
Chapter II, SFD getting started page 42
Chapter II, SFD getting started page 42
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
Drawing fields
Drawing fields
In our exercise we will build a format for a rather trivial program
to print address labels.
While drawing it make sure that you don't put any text into the first
character position on any line because we will need this space later
on.
First go to the second line and give the format a header of your own
| choice. Once you have written it go to column 1 and press Insert
until it is approximately in the center. (If you have moved it too
| far, use Delete)
Now go to line 4 and enter the following: [Mr][Mrs][Miss]
The open square bracket means 'Begin of field', the closed means 'End
of field'. In your example, the first character position of the first
field is the 'M', the last is the 'r'. the field has a length of two
characters.
Now complete your format according to the drawing below. Move
everything that it looks nice. The exact length and position of the
fields does not matter at the moment, just check that you have left
line 1, line 3, the line below 'City' and line 15 (the last) as well
as the first and last column empty. We will need them in a moment...
-Header-
[Mr][Mrs][Miss]
Name.......[ ]
Street.....[ ]
City.......[ ]
Number of Labels[ ]
Msg[ ]
Chapter II, SFD getting started page 43
Chapter II, SFD getting started page 43
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
Drawing boxes
Drawing boxes
Presently our format doesn't look too appealing, does it ? We will
correct this now by drawing boxes around the different parts.
First we want to draw a frame around the complete format. We need to
| Mark two diagonal corners of the box we want to draw. Therefore we go
| to line 1, Column 1 (Home) and press F5 (Mark). The mark is shown as
| a small rhombus. (By the way, an accidentally set Mark can easily be
| removed by positioning the cursor over it and pressing F5 again).
| To get to the other (lower right) corner we can now press Left twice.
| Again F5 to mark it.
| Now press F8 (Draw Box). Observe !.
Observe !
| Incidently, key F7 does exactly the opposite of F8, i.e you can
| undraw (delete) a box with it.
The box drawing feature can also be used to draw vertical or
horizontal lines. Just place the two marks in either the same line or
the same column.
Apart from double lines as you have already seen, boxes can be drawn
in all kind of line styles which ca be seperately defined for
horizontal and vertical lines. To do this, go by the following
instructions.
Chapter II, SFD getting started page 44
Chapter II, SFD getting started page 44
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
Selecting Linestyles
Selecting Linestyles
We now want to seperate the different parts of the format. However we
would rather like to use single lines instead of double lines. In
order to achieve this you go to the local menu (F9) again and select
the second option (Box Linestyles) by highlighting it and pressing
| Return.
The small triangles you see on the format being presented to you
specify the currently selected linestyles (Double lines). Since we
want single lines for horizontal, highlight the second field and
| press Return. The vertical lines we leave as they are. Once back on
| your worksheet, go to Line 3, first column. Place a Mark.
| Go to the last position of the line below 'City'. Mark it as well.
(Actually you could also have marked the other two diagonal corners,
i.e. line 3, last column and the first column of the line below
'City').
| Press F8 to draw the box. As you can see, all necessary Junctions are
done automatically.
(For your information: This applies not only for 'T', but also for
(For your information: This applies not only for 'T', but also for
'X' junctions, whenever you use single or double lines).
'X' junctions, whenever you use single or double lines).
By now, you should be reasonably satisfied with your format (don't be
too fancy after all, it is not that terribly sophisticated anyway)
and we will proceed to specify its parameters.
| To leave the editor, press Escape.
SFD will verify whether you really want to leave the editor, select
SFD
'Yes'.
Note: The program is now checking your format. If for some reason
Note:
you did not properly use the brackets (Field delimiters) a window
will be displayed informing you of the kind of error you made. In
| this case, hit Escape or Return to go back to the editor and correct
your piece of art before attempting to leave it again as described
above.
Chapter II, SFD getting started page 45
Chapter II, SFD getting started page 45
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
Field specifications
Field specifications
Now you should see your format (the field delimiters have been
removed) and a small menu offering four different choices.
We want to specify the fields of your format, so take the first one.
The menu vanishes and you are back in your address label format. It
now behaves like any other format you've seen so far. The first field
is highlighted and you can travel around using the familiar keys.
Before going further we should think a moment about your format and
what it should look like.
The first three fields (Mr,Mrs and Miss) should be a group of
options. There is no data to be entered into these fields , we just
want the user to select one (and only one) of the given options. Such
| fields are called Constants in SFD. To make the selection exclusive
SFD
(only one may be selected) we must declare them as a group. And we
also want the selection to be mandatory.
To conclude.
1. We want fields 1 to 3 to be a group of selectable items
(Constants).
2. We want to declare them as mandatory.
Now let's do it.
Go to the first field (the 'Mr') and select it by pressing Return.
A window will come up giving you several options to preset the field
specifications. At present, your field is set to the default values,
meaning it is assumed to be a variable, any input is allowed, there
are no checks to be made and some more.
We don't want to preset it to anything else (all other fields are
currently declared in the same way), so we choose 'None'.
But we do want to change some of the specification details, so choose
'Yes'.
Chapter II, SFD getting started page 46
Chapter II, SFD getting started page 46
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
Now the Field specification format comes up. The 'Type' still says
| Variable. We want to change it to Constant. Since the cursor is
| already in the 'Type' field just press Return. A small menu will come
| up. Choose 'Constant' and press Return again. That's it.
The next two fields show 'Group from 1 to 1'. Change the second '1'
| to '3' and press Return.
| Now you go to 'Mandatory' and hit Return to change it to 'Yes'.
Note: If you want to know the meaning of the other specifications,
Note:
| just make use of your mighty F2 Help key.
At this point in time we could also specify the colors and
attributes, but for the time being we will leave them unaltered at
their default values and come back to them later on in this exercise.
| You can now press Escape to finish the format.
Since we have specified that field 1 is the first of a group ranging
from field 1 to field 3, SFD automatically copies it's specifications
SFD
to the remaining fields of the group. There are however some
specifications which are not copied: The 'message', the delimiters
| and whether the field is Selected or not.
The next three fields (4 to 6) on your address label format are to be
| used to enter data, in other words, they are Variables. We want to
make input to them mandatory.
Call up the field specifications for the first one (Field Nr 4, the
'Name' field).
Go to the 'Fill' field. Enter a 'dot'. Into the 'Delimiter left'
field put a colon. (The colon will be displayed at the Position were
you put your open square bracket when you designed the layout). Set
'Mandatory' to 'Yes'. Now leave the format.
The next two fields on your format (street and city) should look the
same as the 'name' field. Consequently you can use the 'Preset'
function to copy the previous fields specs. As mentioned earlier, the
'Delimiters' are not copied, so, if you want to have a colon in front
of these fields as well, you must specify it (otherwise you can
choose the 'Details No' Option).
Chapter II, SFD getting started page 47
Chapter II, SFD getting started page 47
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
There are two fields left on your format, 'Nr of Copies' and 'Msg'.
'Nr of copies': Here again you can copy the specs from the previous
field. But go into the details as well since we want to specify some
input check parameters.
First of all, we only want Integer numbers (there is nothing like 2.4
labels). Hence go to the 'Inp.Check' field and press Return. Now make
your choice. We also want to limit the Number of address labels one
can obtain. We will assume a minimum of 1 and a maximum of 25 labels.
Enter the appropriate values and finish the format.
The 'Msg' field we want to use for error messages (If we don't
| specify a field for them we would just hear a Beep in case of
erroneous data input).
| Specify the type as Output only and also set 'Justify' to 'Center'
(just to make the messages look nice).
Leave the format.
| Since we now have specified all fields in your format, press Escape.
You are now back in the 'Change Format Specs' menu.
Chapter II, SFD getting started page 48
Chapter II, SFD getting started page 48
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
Format Control Specifications
Format Control Specifications
Select 'Format Control Specs'.
| Once the format is diplayed you probably best press F2 first and read
the infomations to get an idea.
Now let's begin. The first field we want to change is 'Error Message
Field'. Enter the number of your 'Msg' field, 8.
Actually, we are already finished with our specifications, but let's
| take the opportunity to talk about the User Function Key
specifications on the lower half of this format.
User Function Key Specifications
User Function Key Specifications
The purpose of these specifications is to tell SCL later on in your
SCL
program when to invoke special user written routines like additional
checks, prefilling of fields and many other things. By default, i.e.
without the need to be specified, facilities are provided by SCL to
SCL
optionally invoke user written routines whenever a format field is
entered, left or if the format is exited.
In addition to this, SCL can be instructed to allow user written
SCL
routines to take over control whenever certain keys are pressed. In
order to allow this to happen, the appropriate keys must be specified
| as User Functions.
SFD lets you specify any of the ten function keys and, in addition,
SFD
| up to ten other keys to serve as User Functions. ('Key' in this
context can be any valid CNTRL or ALT key combination as well).
In addition to the here mentioned Interrupt specifications which are
valid throughout the whole format there is one more which can be
specified for each single field. You may have seen it already when
you did the field specifications. It is called 'CharCheck' and, if
set, can invoke a user written procedure at each single keystroke if
the cursor is in the appropriate field.
As you probably can imagine, the possibilities offered by the User
Interrupt System are enormous. Advice and examples on how to use them
are provided in A[[endix A.
Further informations can also be found in the SCL part of this
SCL
manual.
Chapter II, SFD getting started page 49
Chapter II, SFD getting started page 49
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
We have now completed the format specification (colors and attributes
| will be discussed during the format test). Press Escape to go back to
the little 'Specifications' Menu and select 'End'.
Your format is now written to the format file on disk and you are
back in the Main Program Menu.
If you look at 'Nr of formats' in the header of the menu, you'll see
'1', indicating that you have created your first format.
If you want, you can print a hardcopy of it on your printer before we
continue to test it and try out the Color/Attribute specifications.
By now you should have a better understanding of some of SFD's
SFD's
features and I hope that you have enjoyed our exercise so far.
When you are ready to continue, we will take a look at SFD's Format
SFD
Test feature.
Chapter II, SFD getting started page 50
Chapter II, SFD getting started page 50
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
Testing a Format
Testing a Format
________________
| Select Design Test/Modify on the main menu. When asked for the name
of the format you want to test, enter 'Myformat' or whatever name you
called it. If you entered the wrong name, you will be notified by a
| Beep.
In this case, either correct it or, if you don't know the name
| anymore, press F10 to get back to the main menu and use the Display
| Formats option to find out the right one.
Anyway, as soon as you have entered the name of your format, press
| Return and it will be displayed.
It now behaves exactly according to your specifications. All input
checks are being performed and if you enter something wrong or forget
to enter mandatory data you will be notified. Take yourself a couple
of minutes to try out all kind of things like leave off mandatory
data, try to enter invalid data etc and watch the results.
Note: Handling of a format under 'Test' is a lot slower than later
Note:
on in the program. This limitation is imposed by the fact that all
messages must be read from a disk file as opposed to later on in the
program where they are stored in memory.
Now let us modify the way it looks.
| To do this, you have to select the local menu (you know how, don't
you ?).
This menu offers the following choices:
Change field specs/Active field
Change field specs/Active field
Allows you to change the specifications of the field in which you
currently are.
Change field specs/Other field
Change field specs/Other field
This option enables you to change any other field on your format. It
is particularly useful to change fields you can't get at (Output only
fields).
Global Colors/Attributes
Global Colors/Attributes
This option allows you to change the colors/attributes of all fields
of a kind (all variables, all constants or all output only fields) on
your format.
Format/Control Specs
Format/Control Specs
The same as you have seen already during layout design.
Chapter II, SFD getting started page 51
Chapter II, SFD getting started page 51
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
Colors/Attributes
Colors/Attributes
_________________
You now select 'Global Colors/Attributes'.
When asked for a field type, select 'Constant'. This means that you
want to change the appearance of all Constants in your format. In
your case these are the first three fields.
Before starting to do any modification, it is important to describe
| the meaning of Normal, Active and Selected fields.
| What determines if a field is displayed in Normal or Active status is
related to your position to this field, in other words, whether you
are 'in it' or not; i.e. it becomes active if you go there.
| Selected is mainly utilized for Constants (nevertheless it can be
useful with other fieldtypes as well for certain effects, see
| Appendix A under 'Advanced Programming Technics'). Selected is a
boolean status proprietary to a field. In the case of a Constant
field it can be toggled by pressing Return while being in the field.
To express the above states, field attributes, seperate for
monochrome and color screens, can be choose as required.
Field Attributes
Field Attributes
On monochrome displays, some of the field attributes like 'underline'
| and 'Inverted' are exclusive. Since Selected can come together with
| both Normal and Active field status, it is your responsibility to
make sure that the attributes don't exclude each other. As an
| example, if you would specify 'Selected' as being inverted and Active
as being underlined the appearance of the appropriate field wouldn't
change whether you were in the field or not, it would just being
inverted in both cases. This could be very irritatating since you
might not be able to recognize what field you were in.
In the case of 'Color' attributes the same is true for example if you
| choose an 'intensified' color for selected and the 'Intens' attribute
| for Active.
If you have a monochrome adapter, you can't see the results of any
changes made to the 'Color' attributes and vice versa. Nevertheless,
you should at least read the appropriate chapters. Then try out some
combinations of attributes matching the display adapter you are
using.
Chapter II, SFD getting started page 52
Chapter II, SFD getting started page 52
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
Color Screen Attributes
Color Screen Attributes
| The Normal and Selected Choices are pretty straightforward. You can
select any one out of 16 foreground colors and any one out of 8
background colors for each one of the two.
Keep in mind, that if you use 'intensive' forground colors you may
| get in conflict with the 'Intens' attribute for Active.
| The choices you have for Active are:
Invert : The foreground color becomes the background color and vice
versa. Intensified background colors are not possible.
Therefore the non intensified equivalent is being used if
necessary.
Blink : Self explanatory. The blink frequency can be adjusted. See
under 'System Defaults'.
Intens : The foreground color is displayed intensified.
Multiple choices of the above attributes are possible.
Multiple choices of the above attributes are possible.
| Now let us specify a 'new look' for the Constants in our format.
The foreground and background colors you see are modified as follows:
Select the appropriate field.
Choose your favourite from the selection you are presented with.
Simple, isn't it?
| The Active attributes can be set or reset by pressing the Return key.
Once you have made your selection, go back to your format. If you
have a Color Monitor you will instantly see the results of your
modifications.
Chapter II, SFD getting started page 53
Chapter II, SFD getting started page 53
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
Monochrome Attributes
Monochrome Attributes
Norm : 'White' text on black where 'White' means the color of
the screen you are using (usually green or amber).
Intens : Same as 'Norm' but brighter Text. Obviously, 'Norm'
and 'Intens' exclude each other.
If 'Intens' is used together with 'Invert' text just
appears to be 'thinner'.
Invert : Black text on 'White' background.
Underline : Field will be underlined. 'Underline' and
'Invert'exclude each other. In this case, 'Invert'
takes precedence.
Marked : Directly before and after the field a triangle
pointing towards the field will be displayed. If
| 'Marked' is used as an Active attribute the triangles
| will blink, if it is used as a Selected attribute they
are static.
Blink : The field content will blink. The blink frequency can
be adjusted. See under 'System Defaults' for details.
Multiple choices of above attributes are possible with the exceptions
Multiple choices of above attributes are possible with the exceptions
mentioned.
mentioned.
To set/reset monochrome attributes just travel to the appropriate
| fields and press Return.
Now make your choices. Once you have finished go back to your format
you will instantly see the Results of your modifications (at least if
you are working on a monochrome monitor).
To get some exercise, feel free to venture using other options as
well. Maybe you even want to change some other specifications. Just
do it and watch the results.
Once you are done with the exercises two ways are offered to exit
your format.
1.
| Fill it out completely and press Return
or
2. Hit the ABORT key.
Chapter II, SFD getting started page 54
Chapter II, SFD getting started page 54
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
Conclusion
Conclusion
__________
The purpose of this exercise was to give you a brief overview on the
Screen Format Designer. Only a small part of the features was
Screen Format Designer
touched, but you should now have enough knowledge to continue your
exploration on your own, using the descriptions later on in this
manual.
If you should have encountered any difficulties during our exercise
or did not get along with the instructions given, I encourage you to
just try it again and I am sure you will succeed this time.
Anyway, as long as you are not completely familiar with the system
| you are urged to make frequent use of the Help feature.
Note: If for some reason you accidentally 'scrambled' your address
Note:
label format during our exercise, don't worry you will find one among
the sample programs which came on your distribution disk. Some of
them, (including the address label format) will be used later on to
give you an idea about SCL and others will be discussed in the
SCL
Appendix A of this manual to demonstrate some advanced SCL
programming technics.
Chapter II, SFD getting started page 55
Chapter II, SFD getting started page 55
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
The Screen Format Designer
The Screen Format Designer
( S F D )
( S F D )
Functional Description
Functional Description
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
Functional Description - Introduction
Functional Description - Introduction
| This chapter of the manual provides a functional description of The
The
| Screen Format Designer Program.
Screen Format Designer
The first chapter describes the basic program layout.
It includes an overview on all files being used or created by SFD as
SFD
well as the keyboard functions and a description of the Online Help
System.
The next chapter covers the main menu and all functions accessible
from it.
The third chapter then talks about Format Design and all related
functions.
Chapter II, SFD functional description page 57
Chapter II, SFD functional description page 57
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
SFD Basic Program Layout
SFD Basic Program Layout
SFD has been designed around a Main Menu which automatically comes up
SFD
as soon as the program has been started.
All basic functions are shown and accessible from here. They are
logically grouped in seven lines. Within each group the most
important item is listed first.
| The Up and Down keys can be used to jump between the groups and items
| in a group are selected with the Right and Left keys.
There are two functions on the main menu which are considerably more
complex than all others Format layout design and Test. They are
virtually subsystems on their own.
| Format layout design for example leads through a whole series of
screens and functions.
It first starts with the actual layout editor. Within the layout
editor, many keys have a different meaning compared to normal
operation and there are also a lot of special functions available
including it's own little menu offering additional features. Once the
| Layout editor is left, the Format Specification Mode is entered
presenting another local menu with all selections necessary to
specify a format and it's fields.
| Leaving the Format Specification Mode then finally leads back to the
| Main Menu.
| The Format Test function is not that complex but it also allows to
| enter the Format Specification Mode, in this case via another local
menu.
This allows a very interactive method of testing a new format. If
initial requirements are not met or require to be redefined, the
appropriate changes can be performed and verified instantly in a
simple iteration.
Chapter II, SFD functional description page 58
Chapter II, SFD functional description page 58
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
Files used by SFD
Files used by SFD
In order to run, SFD requires the following files to be present in
SFD
the same subdirectory as SFD.EXE itself:
SFD.FOR:
SFD.FOR:
SFD's own format file, containing nearly sixty formats. This file is
SFD's
not exactly compatible with the '
SFD and no attempt should be made to modify this file using SFD. This
SFD SFD
could lead to unpredictable results.
SFD.FIN:
SFD.FIN:
Sorted Index file for SFD.FOR. This file is similar to the
files being generated by SFD and contains informations to access the
SFD
formats in SFD.FOR.
SFD.MSG:
SFD.MSG:
| Contains all field messages proprietary to SFD. It has the same
SFD
format as the
SFD
SFD.ERR:
SFD.ERR:
| A Text file containing all necessary system messages, i.e all
messages required by SCL (as contained in "SCL.ERR") as well
SCL
additional ones having been especially defined for SFD.
SFD
SFD.DEF:
SFD.DEF:
| This file is automatically created if any of the SFD Defaults (Design
or System Defaults) are changed and saved. If it is not present, SFD
SFD
will use its own built in defaults. If for any reason it is desired
to go back to default parameters, just remove this file.
Chapter II, SFD functional description page 59
Chapter II, SFD functional description page 59
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
Files generated by SFD
Files generated by SFD
Whenever a new work file is opened with SFD, the following files will
SFD
be created:
Format file. This file will contain all formats including their
specifications with every format occupying about 4.5 KB.
The Layout of this file is described in file SCL.DOC as type
'Screen'.
For a discussion of it's content refer to "Format Specifications"
later in this manual.
Index (Key) file for
This file contains indexing information to the format file such as
all the format names and the relative positions of these formats
within
In addition, it also contains informations whether a format is
deleted. The layout of this file can be found in SCL.DOC under
'Sckeyrec'.
It has to be sorted in order to access formats in a user program via
SCL.
| This is automatically done whenever you Exit the SFD program. Since
SFD
the keyfile is very small, sorting it usually takes only a few
seconds.
| Contains all explanatory messages specified for fields on any of the
formats in
pointer to these messages.
The file consists of records with a length of 71 bytes each
(described in SCL.DOC as 'Msgrec').
This leads to a maximum message length of 70 bytes since the first
byte of each record is used to store the length of the message.
Note: All of the above mentioned files are required by SCL to handle
Note: SCL
the formats in your
found later in this manual under "The Screen Control Language".
Chapter II, SFD functional description page 60
Chapter II, SFD functional description page 60
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
Basic Keyboard Functions
Basic Keyboard Functions
The following keyboard functions apply for all formats in SFD. In the
SFD
layout editor some keys have different functions. For details see
under "The Layout Editor".
| Right : 1. In Travel Mode : Next Field.
Right
| 2. In Entry Mode : Next Character.
| Left : 1. In Travel Mode : Previous Field.
Left
| 2. In Entry Mode : Previous Character.
Down : First field on next line.
Down
Up : Last field on previous line.
Up
Home : First field in line.
Home
End : Last field in line.
End
PgDn : Last field on format.
PgDn
PgUp : First field on format.
PgUp
Tab : Next field.
Tab
ShiftTab : Previous field.
ShiftTab
Backspace : Delete character left of cursor.
Backspace
Insert : Insert a space at the cursor position.
Insert
Delete : Delete character under cursor.
Delete
Return : 1. Entry mode.
Return
2. Finish field and advance to next field (if
already in the last field, finish the format).
| 3. Toggle Selected Status of a Constant.
Escape : Finish Format.
Escape
F1 : Format related Help information.
F1
F2 : Field related Help information.
F2
F3 : UNDO. Restores field to previous content.
F3
F10 : Abort current activity (not valid with everyformat).
F10
Note: A detailed explanation of all key functions can be found
Note:
earlier in this manual under "Getting started".
Keys only being valid in certain contexts are mentioned where they
apply.
Chapter II, SFD functional description page 61
Chapter II, SFD functional description page 61
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
Online Help Facility
Online Help Facility
SFD provides an extensive Online Help Facility in up to four levels
SFD
as follows:
Explanatory field input informations:
Explanatory field input informations:
This feature is only available with some formats, one being the main
menu. SFD automatically displays some informations regarding the
SFD
currently active field (in the case of the main menu, on the bottom
line).
AutoHelp:
AutoHelp:
| Optional feature, selectable via System Defaults which causes some
basic Help information to be displayed if a specified number of
consecutive input errors have been made.
Format Help:
Format Help:
Context sensitive Help relative to the current format. Can be
| accessed anytime by pressing F1.
Field Help:
Field Help:
Context sensitive Help informations relative to the currently active
| field. This feature can be accessed anytime by pressing F2. Field
Help may not be available in all cases.
Chapter II, SFD functional description page 62
Chapter II, SFD functional description page 62
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
Input Error Handling
Input Error Handling
If an Input error is detected, the system reacts with a 'Beep' and,
depending on the format, an error message may be displayed. If the
| Autohelp feature is enabled and a specified number of consecutive
errors has occurred, a format containing some basic help informations
is displayed in addition.
There are basically three different types of errors which can occur:
1. An invalid key has been pressed.
2. Wrong data has been entered into a field.
3. A field where data entry is mandatory has not been filled
in.
They are described in the following.
Invalid Key
Invalid Key
Whenever a key is pressed it is checked for validity in the given
context.
Some examples:
| * Entering a displayable character while being in a Constant
| field.
* Pressing an 'Alpha' key where numeric data is anticipated.
* Entering a decimal point if an integer number is required.
* Pressing a function key not valid on this format.
Wrong data
Wrong data
Whenever an attempt is made to leave a field (i.e pressing RETURN,
TAB or a similar key) the data having been entered into it is checked
for validity. Should it be found to be invalid, the user is forced to
correct it before he is allowed to leave the field.
Missing mandatory data
Missing mandatory data
Any attempt to leave a format missing mandatory data will be refused.
The cursor will automatically be placed into the first field where
data was found to be missing.
Chapter II, SFD functional description page 63
Chapter II, SFD functional description page 63
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
The Main Menu
The Main Menu
The main menu is subdivided into an header, the main body finally,
below it, the message line.
The Menu Header
The Menu Header
In it's upper part the program name, the release number and a
copyright note are displayed.
Below this, there are three lines of information:
Act DIR
Act DIR
Displays the currently active disk and subdirectory.
Workfile
Workfile
Displays name and path of the currently loaded workfile (or
'
Formats
Formats
The number of valid formats in the current workfile.
The Main body
The Main body
It shows seven groups (lines) of items. On the lefthand side of each
line the name of a group of functions is mentioned and the entries to
the right of it represent the functions available within the
appropriate group.
All functions are described in the following paragraphs under their
group description in the order they appear on the menu.
The Message Line
The Message Line
A short explanation of the currently highlighted function.
Chapter II, SFD functional description page 64
Chapter II, SFD functional description page 64
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
DESIGN
DESIGN
This Group provides all functions necessary to design a format
layout, specify it's parameters and finally to test it. Since this
group is amongst the most comprehensive parts of SFD it's functions
SFD
are covered under an own header ("Format Design") later on in this
manual.
Chapter II, SFD functional description page 65
Chapter II, SFD functional description page 65
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
FILE
FILE
There are three functions belonging to this group.
Load File:
Load File:
Load File can not only be selected via the main menu, it also comes
up automatically whenever no workfile is loaded and any other
function requiring a workfile has been selected. Allows to load a
| formatfile as the active workfile and can also be used to change the
active workfile.
If this Function is selected SFD will ask for the name of the
SFD
| workfile to be loaded which will then be searched for in the Active
| Directory.
| Since a format file is always assumed to have an extension of .SCS it
is not required to specify it and any extension entered will be
ignored by SFD.
SFD
| If the format file specified exists in the active directory it is
then loaded.
Otherwise SFD displays a message prompting whether a new file should
SFD
be created or not.
Note that if another format file was loaded before it is
automatically saved to disk.
In case the specified format file (
exceptions loading it are handled as follows:
If no Indexfile (
If no message file (
SFD
to create a new (empty) one.
Please note that in this case all field messages which might have
been specified for any formats in the
have to be reentered.
CHDir:
CHDir
This option provides essentially the same services as the equivalent
DOS command.
| With CHDir you can change the currently active drive and/or
subdirectory.
A file to be loaded or to be copied from will always be assumed to be
| in the Active Directory.
Note: The active directory and even the current disk drive can be
Note:
changed anytime during program execution, even while a workfile is
loaded. Since SFD always stores the full path of any file having been
SFD
loaded, the change of the active subdirectory does not affect it.
Therefore, a file is always stored back to the subdirectory it was
loaded from.
Chapter II, SFD functional description page 66
Chapter II, SFD functional description page 66
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
Crunch:
Crunch:
This function physically removes all previously deleted formats from
the active workfile.
| Once a Crunch has been performed on a workfile it is not any longer
| possible to undelete previously deleted formats. A Crunch reduces the
size of the format file by the space previously allocated to the
deleted formats (about 4.5 KB per format) and also speeds up
subsequent format access.
| For these reasons it is recommended to perform a Crunch prior to use
a format file in a program.
Before SFD attempts to crunch a file, it saves the old version of the
SFD
format file under the name
provide a backup possibility in case of system errors etc during the
actual crunch operation.
The index file is not saved since it can easily be rebuild.
The following procedure should be applied to recover an old format
| file from
| have occurred during Crunch and you are not sure about the integrity
of the format file :
1. Save the files
safely away.
On your work disk, perform the following operations:
2. Delete
| created to match the crunched version of the format file and is
therefore useless at the moment.
3. If present, delete file
crunched format file, which is suspected to be wrong.
4. Rename
5. Start SFD and load
SFD
6.
SFD will automagically create a new index file for it
SFD
(
7. Check the integrity of the format file by looking at the number
of formats and/or printing a format list. Once you are satisfied
create a backup copy of
intermediate backup copy you have made at the beginning of this
procedure.
8. You now have backed up to the point before you attempted to
| perform the Crunch operation.
Chapter II, SFD functional description page 67
Chapter II, SFD functional description page 67
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
FORMAT
FORMAT
This set of functions deal with copying, deleting and undeleting of
formats in the workfile. The meaning of the single items is as
follows:
Copy:
Copy:
Duplicates a format under a different name within the workfile. This
feature is especially handy if several similar formats are required
| for one program. Using Copy to duplicate a master version and change
it later on can save considerable time over building every single
format from scratch.
| If Copy is selected you will be asked for the name of the format to
be copied (Origin) and the name under which you want it to be copied
| (Destination). Destination must be a name not yet existing in your
format file.
| Copy (together with Delete) can also be used to change the name of a
format by first copying it to the new name and afterwards deleting
the old one.
Delete:
Delete:
Deletes a format from the active work file.
Delete does not actually remove this format from the file, it is just
| marked invalid (logically deleted). This has several advantages,
probably the biggest one being that it can still be recovered
(undeleted).
| Please note that undelete is only possible as long as no Crunch has
been performed on the work file.
Undelete:
Undelete:
| Undelete restores a format which had been logically deleted before,
| in other words, it can reverse a Delete operation. Before attempting
| to undelete a format, make sure that no other format exists with the
same name.
| The names of all formats capable of being undeleted can be seen by
| either printing a Format list or via the Display formats command.
Transfer:
Transfer:
To load a format from a different format file.
If this function is selected SFD will ask for both the name of the
SFD
format file and the name of the format to be loaded. In case both can
| be found in your Active directory the format is added under the same
| name to your active work file. Note that like in all cases where you
are asked for a format file, the name of it is expected to have an
| extension of .SCS, any other extension you may specify is masked off.
Chapter II, SFD functional description page 68
Chapter II, SFD functional description page 68
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
DISPLAY
DISPLAY
Formats:
Formats:
The names of all formats in the current work file are displayed. The
| logically deleted formats will be included as well, they are marked
as being deleted.
Files:
Files:
| Initiates a display of the names of all format files in the active
| directory.
Directory:
Directory:
Provides the same functions as the DOS "Dir" command.
A file specification according to DOS rules is expected and all files
matching this specification will be displayed.
Wild card as well as drive/subdirectory specifications follow the
same rules as for the DOS "Dir" command.
Chapter II, SFD functional description page 69
Chapter II, SFD functional description page 69
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
Single format:
Single format:
Prints a hardcopy of the format specified, accompanied by a
description of its fields, on the active printer.
If the printer is not ready or out of paper, such a status will be
reported back to you and you are given the option to either correct
the situation or abort the print.
Note that in order to work correctly the printer must be capable to
print the upper half of the character set according to IBM standard.
All formats:
All formats:
Similar to above, but prints hardcopies of all valid formats in the
active work file.
Format list:
Format list:
Prints a listing of the most important details of all formats in the
active work file.
These are :
Format name, size of the format, total number of fields, cursor home
| position, the related help format and information whether the format
is deleted or not.
A summary is also added. It lists the total number of formats in the
file as well as the number of valid and deleted formats.
Chapter II, SFD functional description page 70
Chapter II, SFD functional description page 70
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
DEFAULTS
DEFAULTS
The two functions in this group allow to inquire or change of SFD's
SFD's
program default specifications.
If changed, the Option is given to save the new defaults in a disk
file (SFD.DEF) to be automatically used again with any subsequent run
of SFD until they become altered again. If the option is choosen not
SFD
to save the new defaults, they will only be valid for the current
program run.
Design:
Design:
Left Field Limit:
Left Field Limit:
The character to be interpreted as the left limit of a field, i.e
whenever this character is found, SFD assumes that a field is about
SFD
to start at the next character position.
The default setting of this parameter is '['.
Right Field Limit:
Right Field Limit:
The character indicating the end of a field. The field ends at the
character position ipreceeding the Right Field Limit Character.
The default is ']'.
Note: For detailed informations on how to use the field limit
Note:
| characters refer to Basic Format Layout Design. later on in this
manual.
Background Color:
Background Color:
One among eight colors to be used as background during format layout
design.
The default is 'Blue'.
Foreground Color:
Foreground Color:
One among sixteen colors to be used as foreground (text) color during
format layout design. The default is 'light grey'.
Note: The above two color options only apply when a color graphics
Note:
| adapter is used. On systems using a Monochrome adapter, the Design
| Background Color is always "Black" and the foregound color is "White"
(i.e the color of your screen).
Chapter II, SFD functional description page 71
Chapter II, SFD functional description page 71
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
Surrounding Area:
Surrounding Area:
| Used by the Layout Editor. If a format layout work area is defined to
be smaller than a full screen, the surrounding (unused) area is
filled with the character specified here. The default setting for
this option is Character Ascii (Hex) 'FA' (a dot).
Note: For more information on how to enter special characters see
Note:
Appendix A, 'Tips and Tricks'.
Chapter II, SFD functional description page 72
Chapter II, SFD functional description page 72
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
System defaults
System defaults
The following parameters can be altered:
The following parameters can be altered:
Auto Help:
Auto Help:
SFD can be configured to automatically come up with Help information
SFD
if a certain number of consecutive input errors have occurred.
'Yes' is the default setting and indicates that this feature is
| enabled. If 'No' is selected, Auto Help is disabled.
After n Errors:
After n Errors:
| Specifies the number of consecutive errors after which the Auto help
screen is to be displayed.
Please note, that if consecutive errors are identical they are
counted double i.e. the second and all following occurrences are
counted twice.
The Default is '3'.
Beep yes/no:
Beep yes/no:
Determines whether SFD 'beeps' in case of errors.
SFD
If 'no' is selected, SFD will stay quiet.
SFD
The default setting is 'Yes'.
Length (ms):
Length (ms):
Duration of the 'beep' tone in milliseconds. The default is 200.
Pitch (Hz):
Pitch (Hz):
Every 'beep' is made up of several short bursts of two alternating
frequencies which can be freely specified.
A Sound using a single frequency can be selected by setting both
frequencies to the same value. The frequencies must be between 100
and 9999 Hz.
The default settings are 200 Hz for the first and 350 Hz for the
second frequency.
Field Blink Frequency:
Field Blink Frequency:
SFD allows to select the frequency a field is blinking. This figure
SFD
is expressed in milliseconds and determines the delay to wait before
inverting the field color again.
Chapter II, SFD functional description page 73
Chapter II, SFD functional description page 73
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
Char YES:
Char YES:
The Ascii code of the upper case letter indicating 'Yes', i.e. in the
case of english '89' ('Y').
Char NO:
Char NO:
Same as above for 'No', i.e in the case of english '78' ('N').
Note: The above two options are used in the case of 'boolean'
Note:
fields. These fields only allow either one of above characters to be
entered. Lower case characters are automatically translated.
Cursor Wraparound Disabled:
Cursor Wraparound Disabled:
If this option is set to 'Yes' then Cursor Wraparound is disabled for
| all formats in SFD. This Option is especially beneficial if a Mouse
SFD
is utilized to operate SFD.
SFD
| Provided Cursor Wraparound is not disabled, pressing Right or Down
while being in the last field of a format moves the cursor to the
| first field. The opposite happens if Left or Up is pressed while
being in the first field of a format. Please note, that even if
cursor wraparound may not be disabled it is not available with all
formats in SFD.
SFD
Chapter II, SFD functional description page 74
Chapter II, SFD functional description page 74
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
EXIT
EXIT
Terminate Program:
erminate Program:
If a workfile was loaded it is automatically sorted before SFD
SFD
terminates.
This is necessary to make the formats within this workfile accessible
for SCL routines.
SCL
Note: SCL cannot be used with unsorted format files. Any attempt to
Note: SCL
do so will result in a fatal error aborting the appropriate program.
Chapter II, SFD functional description page 75
Chapter II, SFD functional description page 75
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
Format Design
Format Design
_____________
Basic Work Flow
Basic Work Flow
The basic flow of developping a new format is as follows:
The basic flow of developping a new format is as follows:
1. Design of the basic format layout.
2. Specification of all fields.
3. Global specifications.
4. Determination of colors & attributes.
5. Test of the format and necessary changes.
Note: This sequence only represents a crude guideline.
Note:
Except for step 1, SFD does not impose restrictions on the sequence
SFD
these actions have to be performed. In practice, you will find that
some steps can sometimes be omitted completely since SFD's default
SFD's
settings are often sufficient.
On the other hand you may find that some activities have to be
performed more than once in order to achieve the desired results.
Initially, steps 1 through 4 should always be performed via the main
| menu item Layout Design.
Beside a few restrictions, steps 2 to 4 can also be carried out using
| the Format test facility with the added advantage that results of
changes become immediately visible.
| However, since changes are much more convenient within the layout
| design system it is advisable to perform all major specification work
there and use the test facility only to carry out minor corrections
found necessary while testing the format.
Chapter II, format design page 76
Chapter II, format design page 76
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
The Layout Editor
The Layout Editor
The Layout editor is activated by selecting the first item on the
| Main Menu, "Layout Design". First, SFD will ask for the name of the
SFD
format to load. In case this format exists, it is loaded and
displayed, otherwise SFD gives you the option to create a new format
SFD
with the specified name.
The Layout editor provides a worksheet to develop or change a format
layout as well as to specify size and location of its fields.
Formats in the layout editor are displayed in a slightly different
| fashion than under Test or if they are used in a SCL application
SCL
program:
* All fields are shown with Left and Right delimiters (Default:
'[' and ']').
* The Cursor has the shape of a big block and can be moved freely
across the whole format.
* If the format is smaller than a full screen (80 X 25) then the
area outside the format is filled with the characters specified
| for this purpose in Design Defaults.
In addition some keys do have other meanings than in normal formats.
Note: If the Layout editor has been instructed to create a new
Note:
format, SFD assumes by default that it's size is 25 lines with 80
SFD
characters each (a full screen). This is the reason why the whole
screen is initially erased in order to serve as a drawing board.
Chapter II, format design page 77
Chapter II, format design page 77
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
Layout editor Meaning of keys
Layout editor Meaning of keys
| Backspace, Insert and Delete have the same meaning as under normal
Backspace Insert Delete
operation, but they do work on a full line instead of in a field.
Home moves the cursor to the upper left corner of your worksheet.
Home
| End moves the cursor to the first character of the last line.
End
| PgUp deletes the line under the cursor.
PgUp
| PgDn inserts a line.
PgDn
| Return moves the cursor to the first character of the next line.
Return
| The Arrow keys allow the cursor to move freely on the format.
| The Arrows are working in wrap-around mode as follows:
The Arrows are working in wrap-around mode as follows:
Right with the cursor being in the rightmost position moves it to the
first position of the next line.
Left with the cursor being in the first position of a line moves it
to the last position of the previous line.
Right while being in the lower right corner of the worksheet moves
the cursor to the upper left corner.
Left while being in the upper left corner moves the cursor to the
lower right corner of the worksheet.
| Pressing Up while being in the first line moves the cursor to the
| last line and the opposite happens with Down while in the last line.
Note: All Special key functions belonging to the layout editor are
Note:
discussed later on in this chapter together with the actions they
perform.
Chapter II, format design page 78
Chapter II, format design page 78
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
Drawing Fields
Drawing Fields
| All desired fields in a format must be determined within the Layout
| Design phase.
To describe their position and length two special characters are
| defined in SFD: The Left Field Delimiter (LD) and the Right Field
| Delimiter (RD).
The default values are '[' for LD and ']' for RD. These values can be
| changed to any other character via Design Defaults.
A LD determines the begin of a field. SFD always assumes that a field
SFD
begins at the character position immediately following an LD.
It also assumes that it ends at the position immediately before a RD.
A field must always end on the same line it begun, i.e it may not
continue on the next line.
In order to allow consecutive fields with only one character position
between them, it is possible to omit the RD character. In this case,
the LD is interpreted as the termination of a field at the position
preceeding it and also as the start of a new field at the position
succeding it.
However you should note that the last field on any line has still to
be terminated with an RD character.
According to this, all the examples below represent valid field
constructions. (The line below the actual delimiters shows the range
of each field as described by the delimiters in form of 'x'
characters).
[ ] [ [ [ ][ ]
xxxxxxxx xxxxxxxxx xxxxxxxx xxxxxxxxx xxxxxxxxx
Chapter II, format design page 79
Chapter II, format design page 79
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
Special Functions
Special Functions
In order to facilitate the process of developing a format layout, the
Layout Editor offers a whole range of special functions. Although
very versalite, they can be activated using very few different keys.
The ones that are most frequently used are directly accessible via
function keys. Some other, less often used functions can be called up
via a small menu which itself is accessible with a function key.
The appropriate Function keys are as follows:
The appropriate Function keys are as follows:
F4 : Delete Block
F5 : Mark Block Corner
F6 : Copy Block
F7 : Undraw Box (or line)
F8 : Draw Box
F9 : Menu Functions
The following paragraphs will discuss all special functions in
logical sequence.
Chapter II, format design page 80
Chapter II, format design page 80
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
Mark Corner (F5)
Mark Corner (F5)
| Many of the layout editors special functions are so called Block
| Functions.
| Before any of these Block Functions can be performed it is necessary
to important to describe the rectangular area (block) they should act
| upon. This is done by simply marking its two diagonal corners.
A block does not necessarily have to be two-dimensionall it can also
| be a line or a column of any desired length. In these cases just mark
both ends of it.
Pressing F5 sets a mark at the cursor position, shown as a small
F5
rhombus.
| Incidentally set Marks can simply be removed again by positioning the
| cursor on them and pressing F5 again.
Notes: Only a maximum of two marks may be set at any time, any
Notes:
additional attempt is refused. Marks are automatically removed as
| soon as the Block Function is performedn
Copy Block (F6)
Copy Block (F6)
| Pressing F6 will duplicate the marked block at the current cursor
F6
position (Building it's upper left corner). Please note that for
obvious reasons it is not possible to copy a block into itself, in
| other words to a cursor position enclosed by the marked Block.
If the block to be copied is bigger than the space available at the
cursor position, the parts which do not fit are automatically
truncated.
Delete Block (F4)
Delete Block (F4)
| F4 erases the marked Block, in other words, moves spaces to it. This
F4
function can also be used to erase the whole worksheet by marking its
two corners.
Chapter II, format design page 81
Chapter II, format design page 81
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
Draw Box (F8)
Draw Box (F8)
| Pressing F8 causes a box to be drawn with the two marks representing
F8
its diagonal corners.
The linestyles used for both horizontal and vertical lines can be
| selected via the local menu (for further details refer to "Local Menu
Functions").
When using single or double lines graphic characters the proper
connections to other boxes will be done automagically.
Beside for drawing boxes, this function can also be used to draw
lines by positioning the two marks in either the same column
(vertical line) or the same row (horizontal line).
Undraw box (F7)
Undraw box (F7)
Erases the marked box, i.e replaces it by space characters. The same
| rules apply as for the Draw Box Function.
Chapter II, format design page 82
Chapter II, format design page 82
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
Menu Functions
Menu Functions
The menu can be accessed by pressing F9. It offers the following
F9
functions:
Change Format size
Change Format size
This function allows to change the size of the currently loaded
format layout.
Valid sizes can be anything from 1 to 25 lines with 1 to 80
characters each.
Boxes Linestyles
Boxes Linestyles
This function facilitates the selection of the linestyles to be used
| with the Box drawing feature.
Possible linestyles are displayed in two groups, one for horizontal
and one for vertical lines. Each of them can be determined
independently.
Each group contains the following:
1. Double Line Block Graphics characters.
2. Single Line Block Graphics characters.
3. White half Blocks.
4 to 6: Full Blocks in different shades.
7. Any other character, see Text below.
For the first two Options (Single and Double line block graphic
characters), SFD is even capable to connect boxes using the
SFD
appropriate 'X' and 'T' elements available in the Character set. The
last Option is used to choose any other displayable character.
If selected, another format comes up showing an extract of 32
characters at a time out of the complete system characterset. The
| Left and Right keys can then be used to point to the desired
character or to select another set of 32 Characters to choose fromn
| Once the desired character is found just press Return to pick it.
Using this feature boxes and/or lines made up for example of smiling
faces or $-signs can easily be created.
Chapter II, format design page 83
Chapter II, format design page 83
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
Key Redefinition
Key Redefinition
This function allows to assign any desired keyboard key to any
displayable character. It becomes very handy if certain Characters
are required in a format which can not normally be accessed with a
keyboard key.
The selection of the appropriate character to be displayed works in a
| similar fashion as the one above described for User selectable
| linestyles.
Up to six keyboard keys can be redefined at the same time.
Note: There exists also another possibility to display characters
Note:
normally not accessible via the keyboard which is described in
Appendix A under 'Tips and Tricks'.
Chapter II, format design page 84
Chapter II, format design page 84
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
Format Specifications
Format Specifications
All format specification parameters are stored in the actual format
file (
| Once a new format has been designed and the Layout Editor is exited,
all these parameters will be set to default values, i.e every field
is assumed to be a variable, there is no input check to be performed,
the color of the format is white on a black background and so on.
These specifications can then be tailored to your own
requirements.
When an existing format is modified, SFD where format specifications
SFD
| can be changed. The main one is directly after the layout Editor has
been exited and the other one, which is slightly limited in some
| aspects is accessible via a local menu during Format Test. Two
main groups of specifications exist:
Field Specifications
Field Specifications
The specifications defining a single field on a format.
Global Specifications
Global Specifications
All specifications proprietary to the whole format.
Not only are the format specifications directly accessible and
alterable but it is also possible to copy field specifications from
another field or to change colors and attributes of a whole group of
fields such as all variables or all constants on a format.
| Note: Some parameters cannot be modified during Format Test, where
Note:
this is the case, it is mentioned in the following.
The discussion of the format specifications is subdivided under three
headings:
* Field Specifications
* Colors and Attributes
* Global Specifications and Control Parameters
Chapter II, format design page 85
Chapter II, format design page 85
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
Field Specifications
Field Specifications
Type
Type
Defines the field type. This parameter cannot be modified during
| Format Test. The possible choices are:
Variable: A normal data entry field.This is the default.
Variable
| Constant: A selectable item (for example in a menu).
Constant
Output :
Output A field not accessible by the cursor (for example a
message line).
Group from/to
Group from/to
| Important for Constants. All Constants within one group are
exclusive, i.e. only one field within a group can be selected at any
one time. Enter the numbers of the first and the last field of the
group. The default is the current field for both values. These
parameters have no meaning for fields other than constants. If the
field specifications for the first field of a group are modified,
they are automatically copied to all other fields of that group. The
only parameters not being copied are: 'Selected' and 'Messages.
| This parameter can not be modified during Test.
Message
Message
A message can be specified for each field on a format. It is stored
| in file
(see under 'Global Specifications'). There are also some other
possibilities to use this message, see Appendix A under 'Advanced
Programming Technics'. The default is no message.
Helpscreen
Helpscreen
| The name of the format to display if the Field help Key, usually 'F2'
is pressed. The default is no helpscreen.
Fill
Fill
Variables only. The character to replace all spaces with if the field
| is active. The default is
Chapter II, format design page 86
Chapter II, format design page 86
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
Delimiter Left
Delimiter Left
| The character to display at the position where the Left field
| delimiter was put during Layout Design, i.e the character position
preceeding the field.
The default is
Delimiter Right
Delimiter Right
| The character to display at the position where the Right field
| delimiter was put during Layout Design, i.e the position immediately
after the field.
The default is
Justify
Justify
Determines how text within the field is to be justified. The possible
choices are 'Left', 'Right' and 'Center'. The default is 'Left'.
Decimals
Decimals
Numeric variables onlyn Determines how many positions are to be
displayed after the decimal point. The default is 0 (zero).
Mandatory
Mandatory
Determines whether input is mandatory to this field. In case of
| constants it determines whether a selection within the Group has to
be made. The default is 'No'.
Selected
Selected
Determines the initial status of the boolean attribute
'Selected'. It usually applies to constants but it can also be used
for some special effects like highlighting etc. See Appendix A under
'Advanced Programming Technics' for details. The default status is
'No'. Note that this attribute cannot be copied to other fields.
Char Check
Char Check
If this parameter is set to 'Yes', each single keystroke can be
externally checked, i.e SCL hands over control to your application
SCL
after each keystroke before actually acting on it. For details on the
use of this parameter see the description of the SCL procedure
SCL
'Handle_Format' later on in this manual. Additional hints can be
found in Appendix A (Sample Programs, especially Sample 4).
The default for this parameter is 'No'.
Chapter II, format design page 87
Chapter II, format design page 87
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
Input Check
Input Check
Variables only. Determines the kind of data to be accepted as valid
input in this field.
The possibilities are as follows:
None: No input check is performed. Any data may be entered in
None
this field. This is the default.
Integer: Only integer numbers may be entered. Any other input is
Integer
refused. The numeric value entered must be within the limits of
'Min' to 'Max' (see below). The maximum possible range is -32768
to +32767. Fields where entries outside this range are required
must be declared as 'Real' (see below).
Real: Any number with or without a decimal point can be entered.
Real
It's value must be in the range of 'Min' to 'Max' (see below).
It is not possible to enter numbers in scientific notation.
Alpha: Only alpha characters are allowed in this field. Other
Alpha
input is refused.
| Y,y,N,n: Only the characters defined as Boolean_Yes and
Y,y,N,n
| Boolean_No (both lower and upper case) may be entered in this
field. For Details see the explanation of these two SCL routine
SCL
upon the initialisation of the program. This feature makes it
possible to define optimum formats without any compromises.
Chapter II, format design page 88
Chapter II, format design page 88
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
Monochrome Attributes
Monochrome Attributes
Normal: The way the field should appear if it is neither 'active' nor
Normal
'selectedg. The possible choices are white characters on a black
background (Norm) or white intensified characters on a black
background (Intens). The default is 'Norm'.
Selected: The way the field should look if it is 'Selected' (see
Selected
above). The possible choices are:
Invert : Black text on white background.
Underl : Text underlined.
Intens : Intensified textn
Marked : Two triangles are displayed to the left and the
right of the field.
Combinations of above attributes are possible with the following
exceptions:
Invert and Underline are exclusive.
Invert and Intensified result in Invert only.
Active: The way the field should be highlighted if the cursor is in
Active
it. Possible choices are:
Invert : The field is inverted.
Underl : Underlined text.
Intens : Intensified text.
Marked : Two blinking triangles are displayed to the left and
the right of the field.
Blink : The field blinks.
Combinations of the above attributes are possible with the same
| exceptions as the ones mentioned for the Selected attributes. Since
| the Active attributes are just 'added' if the field becomes active
(for example, a constant can be both 'selected' and 'activeg at the
same time) careful consideration should be given the question what
combination of attributes should be used. If for example the same
attributes are choosen for both 'active' and 'selected' it may not be
possible to see, in which field the cursor is (in the case of
'marked', there is a differentiation because the triangles blink if
the field is active). In addition, restrictions apply to the combined
use of 'Invert' together with 'Underline' or 'Intens'. The result is
always 'Invert' only.
Chapter II, format design page 89
Chapter II, format design page 89
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
Color Attributes
Color Attributes
The Color Attributes are less complicated to use than the monochrome
ones. For both 'Normal' and 'Selected' there is a choice of one out
of eight background colors and one out of sixteen foreground (text)
colors.
All available colors are listed in Appendix B.
As far as the 'Active' attribute is concerned there are three
different options.
Invert: The field colors are inverted, i.e background becomes
Invert:
foreground and vice versa. Since intensified background is not
possible, these colors are replaced by their non intensified (i.e.
darker) counterpart.
Blink : The field is made blinking.
Blink :
Intens: The text is displayed intensified.
Intens:
The combination of the above options is possible but it should be
considered that the 'Intens' attribute is only meaningful if the
foreground colors choosen for 'Normal' and 'Selected' are non
intensified ones, otherwise it won't be visible.
Chapter II, format design page 90
Chapter II, format design page 90
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
Global Specifications
Global Specifications
& Control Parameters
& Control Parameters
Global Specifications
Global Specifications
Cursor Home:
Cursor Home:
System generated and not changeable. The first cursor accessible (non
Output) field on the format.
Input Message Field:
Input Message Field:
The field where all Input Messages are to be displayed (Input
Messages are the messages specified for single fields, see under
'Field Specifications' for details). If this Parameter is set to 0
(zero) no input messages are displayed. Note that for obvious
reasons, the field specified for input messages should be an 'Output'
field, i.e. not be accessible by the cursor.
The default for this parameter is 0.
Error Message Field:
Error Message Field:
The field where all (system as well as user generated) error messages
| are displayed. Everything said above for the Input Message Field
applies here as well. If this field is set to 0 (zero) no error
messages are displayed. There are no restrictions to use the same
field for both error and input messages.
The default is 0 (zero) i.e no error messages are displayed.
Help Format:
Help Format:
| The name of the format to be displayed if the Format Help Key
(usually 'F1') is pressed. The default is no help format.
Color Foreground:
Color Foreground:
One out of sixteen colors in which the text on the format (except for
the fields) is to be displayed. This option is only meaningful in the
case of Color screens. On monochrome screens, the foreground color is
always white, non intensified.
Color Background:
Color Background:
One out of colors in which the format background (except for the
fields) is to be displayed. For monochrome screens, the format
background is always black.
Chapter II, format design page 91
Chapter II, format design page 91
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
Cursor Wraparound:
Cursor Wraparound:
| If Cursor Wraparound is disabled, pressing Right or Down while the
| cursor is in the last field or Left or Up while the cursor is in the
first field causes a beep. Otherwise, the cursor would be advanced to
the first or last field, respectively.
Note: Alternatively, Cursor Wraparound can also be disabled on a
Note:
global basis, i.e effective for all formats in a program by setting
the SCL Constant 'No_Wrap' to TRUE. Refer to the SCL part of this
SCL SCL
manual for more details.
Format Abort Ok
Format Abort Ok
| If this option is set to 'Yes', pressing the F10 key causes the
| format to be unconditionally terminated, otherwise the Abort function
is disabled for this format.
Chapter II, format design page 92
Chapter II, format design page 92
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
User Function Keys
User Function Keys
The User Function Key specifications control SCL's user interrupt
SCL's
system. This facility allows to invoke user written routines upon
certain occasions while the format is being handled by SCL routines.
SCL
Details and examples on how to use them can be found in both the SCL
SCL
part of this manual and in Appendix A.
In principle they work as follows:
When a specified condition occurs, the SCL procedure
SCL
'Handle_format' notifies an external procedure and gives it the
choice to do whatever it is intended for (like a special input check
for example).
This external procedure can also return a result indicating an error
or a exception to cause 'Handle_format' to proceed in the desired
way.
By default, i.e. without the need to be explicitly specified, SCL
SCL
allows you to invoke external procedures whenever a new field is
entered with the cursor, when it is being left and when the format is
due to be exited.
Beside what is mentioned above it is possible to specify optional
| User Function Keys for any format. User Function keys can be any of
the ten actual Function keys (F1 to F10) and additionally to this up
to ten other keyboard keys.
F1 through F10:
F1 through F10:
If selected, causes 'Handle_format' to transfer control whenever the
corresponding function key has been pressed. There are numerous uses
for these Interrupts like the initiation of program functions or to
temporarily disable SCL functions like 'Help' etc.
SCL
Remaining fields:
Remaining fields:
Up to ten different keyboard keys can be defined per format which,
when pressed, cause 'Handle_format' to transfer control. 'Keyboard
keys' in this context can also be combinations like 'CNTRL-LEFT' etc.
| To define a key as a User Function move the cursor to one of the
| fields containing the text '
| the key or key combination you want to specify. To delete a User
| function Key specification, just position the cursor on it and hit
| Return.
|
Chapter II, format design page 93
Chapter II, format design page 93
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
The Test Feature
The Test Feature
Introduction
Introduction
SFD allows new formats to be tested without having to write a user
SFD
| program. With very few limitations, formats under Test react exactly
as they later on will in a user program. This even includes input
checks etc.
While a format is being tested, it is possible to modify most of it's
specifications and instantly observe the results of these changes,
thus allowing for a very interactive way of developing formats.
The local Menu
The local Menu
| All functions to modify Format Specifications during Test are
available through a local menu which can be called up by pressing key
'F9'.
It offers the following choices:
Change Field Specifications/Active Field
Change Field Specifications/Active Field
Allows to change the specifications of the field the cursor is
currently in.
Change Field Specification/Other Field
Change Field Specification/Other Field
This Option is mainly intended but not limited to allow to change
'Output' fields. If choosen, SFD will ask for the number of the field
SFD
whose specifications are to be changed.
Change Global Colors/Attributes
Change Global Colors/Attributes
Allows to change Colors or attributes of all fields of a type to be
| specified (Variable, Constant or Output) on the format under Test in
one go.
Change Format/Control Specifications
Change Format/Control Specifications
Allows to change the Global Specifications as well as the Interrupt
Parameters.
Chapter II, format design page 94
Chapter II, format design page 94
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
System Limitations
System Limitations
The SFD Format Test Feature has a few limitations. These are:
SFD
Speed
Speed
Since rather than reading from memory as it normally would be done by
SCL much information has to be read from disk, thus slowing down the
SCL
| operation of a format under Test quite considerably.
Help Formats
Help Formats
It is not possible to access the Help formats specified for the
| format under Test via F1 and F2. They have to be tested seperately.
| F1 and F2 display SFD's own help information relative to Test
SFD's
operations.
Format Specifications
Format Specifications
| Some specifications can not be altered during Test. These include:
Field Type, Group from/to and Input and error message fields. In
order to change these specifications the format has to be loaded into
| the Layout Editor and the changes have to be performed there.
Chapter II, format design page 95
Chapter II, format design page 95
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
This Page is intentionally left blank
Chapter II, format design page 96
Chapter II, format design page 96
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
Chapter III
Chapter III
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
This Page is intentionally left blank
Chapter III, Screen Control Language page 98
Chapter III, Screen Control Language page 98
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
Screen Control Language
Screen Control Language
( S C L )
( S C L )
Chapter III, Screen Control Language page 99
Chapter III, Screen Control Language page 99
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
Introduction
Introduction
____________
The Screen Control Language
The Screen Control Language
SCL is accommodated in several TURBO PASCAL Source Library files
SCL
which must be 'included' in your application programs in order to
access the constructs they contain.
The following is a functional description of all relevant constructs
| contained in these Include Files.
For more details on SCL, including explanations and samples available
SCL
in Appendix A.
Chapter III, Screen Control Language page 100
Chapter III, Screen Control Language page 100
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
SCL Files
SCL Files
The following is a brief description of all SCL files.
SCL
SCL.TPU :
SCL.TPU :
Contains all SCL definitions and routines. All elements of SCL can be
SCL
accessed from your Turbo Pascal 4 program by specifying SCL in the
USES statement.
Example:
Example
USES CRT,SCL,PRINTER;
SCL.ERR :
SCL.ERR :
This is a basic Error Message File for your programs and contains all
SCL internal error messages. Its use is explained later in this
manual.
Chapter III, Screen Control Language page 101
Chapter III, Screen Control Language page 101
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
SCL - Global Declarations
SCL - Global Declarations
General
General
| Many of SCL's Global Constants are actually declared as typed
Global Constants
| constants.
This was done to allow their alteration during program runtime.
| Despite all their advantages, Typed Constants in TURBO PASCAL also
have one slight disadvantage:
Since they are are only initialized once, i.e at the time the
program is loaded into memory, irritating effects can occur if an
application program is compiled to memory and afterwards run from
there more than once.
For this reason it is recommended to compile programs using SCL to a
SCL
'.EXE' file on disk in order to test them.
| The following chapters describe most of the Global Declarations
| forming part of SCL, starting with the Global Constants and
| Variables and followed by those Type declarations which could be of
use outside SCL as well.
SCL
Chapter III, Screen Control Language page 102
Chapter III, Screen Control Language page 102
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
SCL Control Parameters
SCL Control Parameters
The following parameters define the maximum size of files etc. Their
default settings are layed out in such a way that they should be
sufficient in most cases.
They can cater for up to:
100 Error Messages.
400 Field (explanatory) Messages.
20 Formats displayed simultaneously.
Looking at these figures you can see that only some special, usually
very large applications may require parameter changes.
Max_Error_Messages
Max_Error_Messages
Declaration:
CONST Max_Error_Messages = 100;
Explanation:
The highest allowed user message number.
This constant must be set to a value equal to or greater than the
number of records in file
for about 60 additional user messages, since approximately 40 records
are already occupied with system error messages.
Max_Input_Messages
Max_Input_Messages
Declaration:
CONST Max_Input_Messages = 400;
Explanation:
| Contains the maximum number of Field Messages.
This constant must be set to a value equal to or greater than the
number of records in file
follows: (Size of file
Remark:
In order to allow for later changes to your formats it is recommended
to increase the minimum number calculated as above by at least 50 %.
Max_Heap_Screens
Max_Heap_Screens
Declaration:
CONST Max_Heap_Screens = 20;
Explanation:
The maximum number of formats which can be 'stacked' one on top of
the other on the display.
Chapter III, Screen Control Language page 103
Chapter III, Screen Control Language page 103
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
File Names
File Names
The following constants define what file name extensions SCL expects.
SCL
While it is recommended to leave them at their default settings (i.e
compatible with SFD), it is still possible to change them if
required. In this case the files created by SFD must be renamed
before they can be used with the appropriate application. In any
case, make sure that you don't use extensions which do have special
meanings in your system like '.BAK' (backup file) or '.PAS' (Pascal
source file).
Screenfile_Ext
Screenfile_Ext
Declaration:
CONST Screenfile_Ext = '.scs';
Explanation:
File name extension used for the format file. Change if a different
extension is desired.
Indexfile_Ext
Indexfile_Ext
Declaration:
CONST Indexfile_Ext = '.sci';
Explanation:
File name extension to be used for the format index file. Change if a
different extension is to be used.
Errorfile_Ext
Errorfile_Ext
Declaration:
CONST Errorfile_Ext = '.err';
Explanation:
File name extension to be used for the file containing the system and
user error messages. Change if a different extension is to be used.
Messagefile_Ext
Messagefile_Ext
Declaration:
CONST Messagefile_Ext = '.msg';
Explanation:
File name extension to be used for the file containing the field
messages. Change if a different extension is to be used.
Chapter III, Screen Control Language page 104
Chapter III, Screen Control Language page 104
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
Help System Parameters
Help System Parameters
Autohelp_Screen
Autohelp_Screen
Declaration:
CONST Autohelp_Screen = 'autohelp';
Explanation:
| The name of the format to be used for the Autohelp feature. Change if
another format is to be used.
Maxerrors
Maxerrors
Declaration:
CONST Maxerrors : INTEGER = 3;
Explanation:
If 'Autohelp_Set' is true, this value determines the number of
| consecutive errors before the Autohelp format is displayed.
Auto_Help_Set
Auto_Help_Set
Declaration:
CONST Auto_Help_Set : BOOLEAN = TRUE;
Explanation:
| If this parameter is TRUE , the Auto_Help feature is enabled, i.e the
| format specified as Autohelp_Screen is displayed automatically
| whenever Maxerror consecutive input errors have been made. If it is
| set to FALSE, the Auto_Help feature is disabled.
Code_Help_Field
Code_Help_Field
Declaration:
CONST Code_Help_Field : INTEGER = 1060;
Explanation:
| The key used to display the Help Format declared for the currently
active field.
Code_Help_Format
Code_Help_Format
Declaration:
CONST Code_Help_Format : INTEGER = 1059;
Explanation:
| The key used to display the Help Format declared for the currently
active format.
Note: For information on how keyboard keys are coded see under
Note:
| Keyboard Key Specifications.
Chapter III, Screen Control Language page 105
Chapter III, Screen Control Language page 105
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
Beep Parameters
Beep Parameters
The following parameters allow to change pitch and duration of the
| Beep, i.e. the sound SCL uses in order to attract the users attention
SCL
because of input errors etc.
Beep_Off
Beep_Off
Declaration:
CONST Beep_Off : BOOLEAN = FALSE;
Explanation:
If set to TRUE SCL will not 'beep' in case of errors.
SCL
Beep_Time
Beep_Time
Declaration:
CONST Beep_Time : INTEGER = 3;
Explanation:
Duration of the 'beep' in clock ticks (55 ms).
Beep_Frequency_1
Beep_Frequency_1
Declaration:
CONST Beep_Frequency_1 : INTEGER = 200;
Explanation:
First frequency used for the 'beep' sound in hertz.
The 'beep' consists out of two alternating frequencies.
Beep_Frequency_2
Beep_Frequency_2
Declaration:
CONST Beep_Frequency_2 : INTEGER = 350;
Explanation:
Second frequency used for the 'beep' sound in hertz.
The 'beep' consists out of two alternating frequencies.
Chapter III, Screen Control Language page 106
Chapter III, Screen Control Language page 106
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
Message Display
Message Display
The following two parameters can be used to allow different, user
selectable 'Help' levels.
Input_Msg_Set
Input_Msg_Set
Declaration:
CONST Input_Msg_Set : BOOLEAN = TRUE;
Explanation:
| If set to FALSE, no Field Messages will be displayed.
Can be used to suppress explanatory messages with experienced users.
Error_Msg_Set
Error_Msg_Set
Declaration:
CONST Error_Msg_Set : BOOLEAN = TRUE;
Explanation:
If set to FALSE, no messages will be displayed in case of input
| errors. SCL will however still 'beep' as long as Beep_Off is FALSE.
SCL
Chapter III, Screen Control Language page 107
Chapter III, Screen Control Language page 107
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
Field Attributes
Field Attributes
The following specifications define the blink frequency for constants
(see 'Blink' field attribute) as well as what characters are used
for the 'Marked' field attribute.
Blink_Count
Blink_Count
Declaration:
CONST Blink_Count : INTEGER = 0;
This count is incremented each clock tick. A clock tick occurs about
18.2 times per second (every 55 ms). Blink_count can be interogated
by user routines.
Timer_Intervall
Timer_Intervall
Declaration:
CONST Timer_Intervall : INTEGER = 4;
Explanation:
Used as a delay for the field blinking procedure. Determines the
delay after which the fieldcolor is inverted again. Decrease for
faster and increase for slower blinking.
Mark_Field_Left
Mark_Field_Left
Declaration:
CONST Mark_Field_Left : Byte = 16;
Explanation:
| The ASCII code of the character used as the Mark on the left side of
the field (see 'Marked' field attribute).
Mark_Field_Right
Mark_Field_Right
Declaration:
CONST Mark_Field_Right : Byte = 17;
Explanation:
| The ASCII code of the character used as the Mark on the right side of
the field (see 'Marked' field attribute).
Chapter III, Screen Control Language page 108
Chapter III, Screen Control Language page 108
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
Key Specifications
Key Specifications
The values of all keyboard keys associated with functions are defined
as constants in order to be able to adapt programs to non standard
keyboards.
Their values are calculated as follows:
1. Use the decimal ASCII code of the key to perform the
appropriate function.
2.
| Add 1000 in case this key creates an extended code,
i.e one preceeded by an 'ESC' character.
Code_Cancel_Act
Code_Cancel_Act
Declaration:
CONST Code_Cancel_Act : INTEGER = 1061;
Explanation:
The key used to cancel a change to a 'variable' and to restore the
original content of it (Default:F3). Modify in case you want some key
to perform this action.
Code_Abort
Code_Abort
Declaration:
CONST Code_Abort : INTEGER = 1068;
Explanation:
The the key to unconditionally terminate the current format in case
the 'Abort Ok' attribute is set to 'Yes' in its Global
specifications.
Code_Escape
Code_Escape
Declaration:
CONST Code_Escape : INTEGER = 27;
Explanation:
The key to terminate a format.
Chapter III, Screen Control Language page 109
Chapter III, Screen Control Language page 109
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
Performing 'Edit' functions
Performing 'Edit' functions
CONST Code_Home : INTEGER = 1071;
CONST Code_Tab : INTEGER = 9;
CONST Code_Ctrltab : INTEGER = 1116;
CONST Code_Rtab : INTEGER = 1015;
CONST Code_Return : INTEGER = 13;
CONST Code_Left : INTEGER = 1075;
CONST Code_Right : INTEGER = 1077;
CONST Code_Down : INTEGER = 1080;
CONST Code_Up : INTEGER = 1072;
CONST Code_End : INTEGER = 1079;
CONST Code_Ins : INTEGER = 1082;
CONST Code_Del : INTEGER = 1083;
CONST Code_Backspace : INTEGER = 8;
CONST Code_Pgup : INTEGER = 1073;
CONST Code_Pgdown : INTEGER = 1081;
Function Keys
Function Keys
| The following are the codes of the keys associated with the Function
| Key Interrupts (see 'Global Format Specifications'). Change as
required for non standard keyboard layouts.
CONST Code_F1 : INTEGER = 1059;
CONST Code_F2 : INTEGER = 1060;
CONST Code_F3 : INTEGER = 1061;
CONST Code_F4 : INTEGER = 1062;
CONST Code_F5 : INTEGER = 1063;
CONST Code_F6 : INTEGER = 1064;
CONST Code_F7 : INTEGER = 1065;
CONST Code_F8 : INTEGER = 1066;
CONST Code_F9 : INTEGER = 1067;
CONST Code_F10 : INTEGER = 1068;
Chapter III, Screen Control Language page 110
Chapter III, Screen Control Language page 110
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
Nationalisation Parameters
Nationalisation Parameters
The following declarations determine the message to be displayed in
case of a fatal program abort initiated by SCL. Change for other
languages as required.
CONST Fatal_Msg_1 = 'FATAL SCL ERROR: ';
CONST Fatal_Msg_2 = 'ERROR NR: ';
CONST Fatal_Msg_3 = 'PROGRAM ABORTED.';
| The following two parameters define the valid input for Boolean
| Variables. Change according to the language used.
Code_Yes
Code_Yes
Declaration:
CONST Code_Yes : INTEGER = 89;
Explanation:
The first letter of the word meaning 'Yes' in upper case (Y). Used
| for Boolean Fields. Change for other languages.
Code_No
Code_No
Declaration:
CONST Code_No : INTEGER = 78;
Explanation:
The first letter of the word meaning 'No' in upper case (N). Used for
| Boolean Fields .Change for other languages.
Character sets for Variables
Character sets for Variables
The following constants define the characters permitted to be entered
into the various types of Variable fields. Change as required for
national character sets.
CONST Anything_Set : SET OF Byte = [1..6,8,14..27,32..255]; CONST
Integer_Set : SET OF Byte = [32,43,45,48..57];
CONST Real_Set : SET OF Byte = [32,43,45,46,48..57];
CONST Alpha_Set : SET OF Byte = [32,65..90,97..122,128..167];
Chapter III, Screen Control Language page 111
Chapter III, Screen Control Language page 111
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
Country Information Parameters
Country Information Parameters
SCL_Country
SCL_Country
Declaration:
CONST Scl_Country : INTEGER = 0;
Explanation:
The country information to be used for SCL. If this parameter is set
to 0 (zero) SCL uses the country specified in the computers
CONFIG.SYS file. If another countries informations are to be used set
this constant to the appropriate value. (Example : 49 for germany).
The country codes available are described in your DOS manual under
the COUNTRY command.
SCL interrogates the Country informations during initialization and
sets up the following variables accordingly:
Country
Country
Declaration:
VAR Country : INTEGER;
Explanation:
Contains the country code of the country currently being used by SCL.
SCL
This is either the Country code specified in CONFIG.SYS or if
'SCL_Country' (see above) is set to a value other than 0 (zero) it is
set equal to this.
Date_Format
Date_Format
Declaration:
VAR Date_Format : INTEGER;
Explanation:
Determines the date format being assumed by SCL's date formatting and
check routines. 0 means MMDD and 1 means DDMM format.
Date_Separator
Date_Separator
Declaration:
VAR Date_Separator : CHAR;
Explanation:
The character to be used as a separator between days, months and year
by SCL's date formatting routines.
Chapter III, Screen Control Language page 112
Chapter III, Screen Control Language page 112
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
Time_Separator
Time_Separator
Declaration:
VAR Time_Separator : CHAR;
Explanation:
The character to be used as a separator between hours and minutes by
SCL's time formatting routines.
Currency
Currency
Declaration:
VAR Currency : String10;
Explanation:
Contains the name or symbol of the currency of the country being
assumed by SCL (see above).
Note: Since SCL's own date and time formatting routines are using
Note:
the above informations, they automatically adapt to different
countries and don't therefore have to be nationalized manually. The
same principle should be applied to user written application programs
wherever possible.
Chapter III, Screen Control Language page 113
Chapter III, Screen Control Language page 113
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
SCL Control Parameters
SCL Control Parameters
Progpath
Progpath
Declaration:
VAR Progpath : String80;
Explanation:
Progpath holds the complete path description (including Drive) of the
subdirectory which was active when SCL was initialized, i.e at the
time, the procedure 'Select_Format_File' was called. SCL remembers
this subdirectory because it expects to find its files there, even if
the active subdirectory was changed during program execution. This
variable is quite useful to find other, non SCL files if they reside
in the same directory as the program itself.
Example:
Example:
Assumed a program using SCL is started from directory '\Appl\Mydir'
on drive C. If SCL has been initialized then 'Progpath' contains the
following information: 'C:\Appl\Mydir\'. The statement
'Assign(myfile,Progpath + Example.Fil)' now will assign the following
file name to 'Myfile':
c:\Appl\Mydir\Example.Fil
Note: The information contained in 'Progpath' must not be changed.
Note:
No_Wrap
No_Wrap
Declaration:
CONST No_Wrap : BOOLEAN = FALSE;
Explanation:
| If No_Wrap is set to false, the cursor wraparound feature is
controlled individually for each format by its global attribute
'Wraparound Ok'.
| In case No_Wrap is set to TRUE, this will override the appropriate
specifications and cursor wraparound will therefore be disabled for
all formats.
This Option has been provided to adapt SCL written applications
SCL
easily to 'Mouse' operation.
| If a program is operated with a keyboard Cursor Wraparound can be
very helpful, especially on large formats. On the other hand , if a
| 'Mouse' is being used, Cursor Wraparound can be very confusing.
| No_Wrap allows to choose the optimum in both cases.
Chapter III, Screen Control Language page 114
Chapter III, Screen Control Language page 114
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
Format Pointers
Format Pointers
S_Ptr
S_Ptr
Declaration:
VAR S_Ptr : INTEGER;
Explanation:
S_Ptr controls the format stack and always points to its top, i.e to
the currently active format. If a format is loaded to the Heap by
| Select_Format, S_Ptr is incremented and once the format is finished
| it is decremented by Format_Done.
| If S_Ptr is 0 (zero) after Format_Done has decremented it this means
that all formats have been finished and the screen is therefore
cleared.
Other values indicate that there are still one or more formats on the
| stack which have not yet been finished. The one S_Ptr is now pointing
to is therefore restored and its handling can continue where it was
interrupted before.
Note: For more details on the above matter refer to 'SCL Procedures
Note:
and functions' later in this manual.
R_Ptr
R_Ptr
Declaration:
VAR R_Ptr : INTEGER;
Explanation:
| R_Ptr is a Variable mainly used by the routines R_Cont, G_Cont, R_Sel
| and G_Sel.
It points to the format to be read from. R_Ptr is adjusted equal to
| S_Ptr by the routine Handle_Format. This means, R_Ptr will still
point to a format, even if this format is not any longer active.
For a detailed description of this mechanism refer to the description
of the above mentioned procedures.
Chapter III, Screen Control Language page 115
Chapter III, Screen Control Language page 115
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
W_Ptr
W_Ptr
Declaration:
VAR W_Ptr : INTEGER;
Explanation:
| W_Ptr is mainly used by the routines W_Cont, C_Cont and W_Sel. It
points to the format currently being written to W_Ptr is normally
| equal to S_Ptr. This means that Format fields can be written into as
| soon as the format has been loaded by Select_Format and as long as it
| has not been finished by Format_Done.
For a detailed description of this mechanism see Appendix A.
Chapter III, Screen Control Language page 116
Chapter III, Screen Control Language page 116
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
Format Handling Parameters
Format Handling Parameters
| Many of the following parameters are intended to be used in User
| Interrupt Procedures during format handling. Detailed descriptions
and examples of user interrupt handling procedures can be found in
Appendix A.
Active_Field
Active_Field
Declaration:
VAR Active_Field : INTEGER;
Explanation:
Active_Field always points to the field being processed by
| Handle_Format. If a format has no fields, 'Active_Field' is equal to
0 (zero).
This Variable can be interrogated by user procedures, typically
| during User Interrupt handling.
Char_Code
Char_Code
Declaration:
VAR Char_Code : INTEGER;
Explanation:
Char_Code contains the input character last fetched from the
keybuffer by Handle_Format.
Handle_Format
User interrupt procedures can interrogate or modify 'Char_Code'. If,
for example in case of a User Function Key Interrupt the statement
User Function Key Interrupt
'Char_Code:=Code_Noop' is executed, Handle_Format then ignores this
key.
Glb_Error
Glb_Error
Declaration:
VAR Glb_Error : INTEGER;
Explanation:
This Variable is used by external procedures normally invoked by User
User
Interrupts to return an error description to 'Handle_Format'.
Interrupts
In case the external procedure returns a value other than 0
'Handle_Format' initiates an error routine using the error message to
which 'Glb_Err' points.
Chapter III, Screen Control Language page 117
Chapter III, Screen Control Language page 117
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
Format Handling Parameters
Format Handling Parameters
The following variables are intended to be interrogated by user
written SCL interrupt handling procedures to determine the type of
interrupt having occurred. They are all controlled by the procedure
Handle_Format.
Handle_Format
Refer to Appendix A for more details on how to use them.
User_Function
User_Function
Declaration:
VAR User_Function : BOOLEAN;
Explanation:
This variable is TRUE whenever either a User Function Key was
User Function Key
depressed or any other key was hit during input to a field with the
'CharInt' parameter set to TRUE.
For details on the above mentioned parameters refer to 'Format
Specifications' in the SFD part of this manual.
SFD
Begin_Of_Field
Begin_Of_Field
Declaration:
VAR Begin_Of_Field : BOOLEAN;
Explanation:
This variable is TRUE whenever a new field is due to be entered.
End_Of_Field
End_Of_Field
Declaration:
VAR End_Of_Field : BOOLEAN;
Explanation:
This variable is TRUE whenever a field is due to be left and after
all SCL internal checks specified for the appropriate field have been
successfully completed.
Chapter III, Screen Control Language page 118
Chapter III, Screen Control Language page 118
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
End_Of_Format
End_Of_Format
Declaration:
VAR End_Of_Format : BOOLEAN;
Explanation:
This variable is TRUE whenever a format is due to be left and after
all SCL internal checks have been successfully completed. Please
notice that the Abort feature bypasses this interrupt.
Abort
Checkrequired
Checkrequired
Declaration:
VAR Checkrequired : Boolean;
Explanation:
At the time of a End_Of_Field interrupt, 'checkrequired' is true if
End_Of_Field
the field has been changed and false if it hasn't. 'Checkrequired'
should be interrogated by an external field input check procedure to
find out whether a check has to be done or not. For further
information see Appendix A under 'User Interrupt Procedures'.
Chapter III, Screen Control Language page 119
Chapter III, Screen Control Language page 119
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
Screen related Parameters
Screen related Parameters
The following variables can be interrogated by user programs but
should always be left unchanged.
Screen_Mode
Screen_Mode
Declaration:
VAR Screen_Mode : Byte;
Explanation:
Screen_Mode holds information about what display adapter the computer
is currently working with and what mode it is in. Since SCL only
works in 80 column text mode, the possible values of Screen_Mode and
Screen_Mode
their meaning are:
2 : CG Adapter; 80 Columns Text ; No Color.
3 : CG Adapter; 80 Columns Text ; With Color.
7 : Monochrome (or Hercules) Adapter; 80 Columns Text.
Mono_Adapter
Mono_Adapter
Declaration:
VAR Mono_Adapter : BOOLEAN;
Explanation:
Mono_Adapter is true whenever the computer is using the Monochrome
Adapter.
The status of 'Mono_Adapter' decides to which display memory address
SCL writes.
Color_True
Color_True
Declaration:
VAR Color_True : BOOLEAN;
Explanation:
Color_True is set if Screen_Mode is equal to 3.
Screen_Mode
The status of Color_True determines which set of field attributes is
to be used.
Chapter III, Screen Control Language page 120
Chapter III, Screen Control Language page 120
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
Format related Parameters
Format related Parameters
Xoff
Xoff
Declaration:
VAR Xoff : INTEGER;
Explanation:
Xoff holds the horizontal offset of the currently active format. If
for example Xoff is equal to 5, then the upper left corner of the
currently active format starts at column 6 on the screen.
Yoff
Yoff
Declaration:
VAR Yoff : INTEGER;
Explanation:
Yoff holds the vertical offset of the currently active format. If for
example Yoff is equal to 3, then the upper left corner of the
currently active format starts at row 4.
Chapter III, Screen Control Language page 121
Chapter III, Screen Control Language page 121
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
Background Processing Parameters
Background Processing Parameters
LP_Background_Pointer
LP_Background_Pointer
Declaration:
VAR LP_Background_Pointer : POINTER;
Explanation:
This Variable is a pointer to the procedure to be invoked by SCL as
the low priority background task.
Example:
Example
The following statement would cause SCL to perform Myproc as
background task:
LP_Background_Pointer:[email protected];
HP_Background_Pointer
HP_Background_Pointer
Declaration:
VAR HP_Background_Pointer : POINTER;
Explanation:
This Variable is a pointer to the procedure to be invoked by SCL as
the high priority background task.
Example:
The following statement would cause SCL to perform Myproc as high
priority background task:
HP_Background_Pointer:[email protected];
Note: SCLs background tasking feature is explained in detail in
Note:
Appendix A.
Chapter III, Screen Control Language page 122
Chapter III, Screen Control Language page 122
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
Miscellaneous Parameters
Miscellaneous Parameters
Glb_Status
Glb_Status
Declaration:
VAR Glb_Status : INTEGER;
Explanation:
This Variable is a status count controlling the procedure
'Handle_Format' and carries Information about the present status of
the format handling process. There is normally no need to interrogate
Glb_Status itself, since SCL provides a comprehensive set of Boolean
Glb_Status SCL
variables for this purpose. Please refer to 'Format Handling
Parameters' for details.
Glb_Status should not be changed by user routines.
Glb_Ok
Glb_Ok
Declaration:
VAR Glb_Ok : BOOLEAN;
Explanation:
Glb_Ok is set to FALSE by some SCL procedures and functions to flag
errors during their execution. It can be interrogated by user
programs to make sure that these procedures did not encounter
problems during their execution. Details of the conditions under
which Glb_Ok is set to FALSE can be found in the descriptions of the
appropriate procedures and functions.
Format_Aborted
Format_Aborted
Declaration:
VAR Format_Aborted : BOOLEAN;
Explanation:
A boolean variable which is set to TRUE by the procedure
Handle_Format to indicate to succeding procedures that a format has
Handle_Format
been terminated via the Abort key and that they should therefore
Abort key
ignore the data having been entered so far into this format (and
which is likely to be incomplete, anyway).
Chapter III, Screen Control Language page 123
Chapter III, Screen Control Language page 123
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
Global Type Declarations
Global Type Declarations
The following SCL TYPE declarations are not limited to SCL, they are
TYPE
of rather universal use in a TURBO PASCAL program and can be used in
other parts of the application program as well. More type
declarations inluding the declarations for the SCL files can be found
SCL
in the file SCL.DOC.
TYPE String128: STRING[128];
TYPE String80 : STRING[80];
TYPE String70 : STRING[70];
TYPE String40 : STRING[40];
TYPE String20 : STRING[20];
TYPE String13 : STRING[13];
TYPE String10 : STRING[10];
Chapter III, Screen Control Language page 124
Chapter III, Screen Control Language page 124
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
Procedures and Functions
Procedures and Functions
Introduction
Introduction
The following chapters describe all SCL procedures and functions
intended to be accessed by user programs in logical sequence. While
the routines described here actually only represent a small fraction
of the total number of the SCL routines being available, they will
enable you to perform all necessary operations.
If you are an experienced SCL programmer, you may come along a
occasion where you want to access a low level routine directly for
some reason.
While nothing is actually preventing you from doing so, you should
take extreme care not to interfere with SCL. In addition, be aware
that most of these low level routines are, usually for performance
reasons, not protected against invalid parameters and may therefore
cause runtime errors if you pass such data to them.
As a general rule, don't use any undocumented SCL routines unless you
As a general rule, don't use any undocumented SCL routines unless you
really know exactly what you are doing.
really know exactly what you are doing.
Note: In Appendix B you can find a complete alphabethic list of all
Note:
SCL routines together with brief comments on their purpose and
restrictions.
Chapter III, Screen Control Language page 125
Chapter III, Screen Control Language page 125
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
Entering and leaving SCL
Entering and leaving SCL
PROCEDURE Select_Format_File(Filename:String10);
PROCEDURE Select_Format_File(Filename:String10);
This procedure should be the first SCL routine performed in a
program.
It first checks the present screen mode to ensure that it is one of
the 80 character text modes.
Then it opens the screenfile indicated by 'Filename' (
as well as the Index file (
The index file is checked in order to ensure that it is sorted. Then
the field message file (
message file (
SCL variables are initialized and the screen is cleared.
If errors are encountered during this process, SCL halts the program
and displays a message indicating the reason for the abort.
Note: The parameter 'Filename' must be specified without extension.
Note:
It is recommended to set the screen mode to the desired value using
the Turbo Pascal Construct 'TextMode' before SCL is initialized since
SCL aborts the program if the mode is wrong.
PROCEDURE Close_Formats;
PROCEDURE Close_Formats;
This procedure is the last SCL routine to be performed in a program.
It frees all space previously occupied by SCL in the Heap, closes the
Heap
screen files, clears the screen and finally restores the cursor to
its normal shape.
On the next page you find an example of the basic skeleton of a
program using SCL routines.
Chapter III, Screen Control Language page 126
Chapter III, Screen Control Language page 126
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
Structure of a SCL Program
Structure of a SCL Program
PROGRAM EXAMPLE;
USES SCL; {make SCL accessible}
{User declarations,
procedures and functions }
BEGIN; {of main body of program example}
Select_Format_File('exforms'); {This is the first SCL statement
in any program. It loads the
necessary files and initializes
SCL.}
{main program}
Close_Formats; {Last SCL statement in any program.
It closes all SCL files and clears the screen}
END; {of main body of program example}
Chapter III, Screen Control Language page 127
Chapter III, Screen Control Language page 127
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
Loading and displaying formats
Loading and displaying formats
PROCEDURE Select_Format(Fname:String10);
PROCEDURE Select_Format(Fname:String10);
Select_Format is the first procedure to be called in order to display
and handle a format.
It reads the description of the format indicated by 'Fname' from the
format file and loads it into memory.
If another format is currently being processed and not yet finished,
its status is saved in the stack for later recovery once 'Fname' has
been finished.
Since 'Select_Format' modifies the 'W_Ptr' to point to the new
format, its fields can now be 'prefilled' if necessary.
PROCEDURE Display_Format(Xoffset,Yoffset:INTEGER);
PROCEDURE Display_Format(Xoffset,Yoffset:INTEGER);
Once a format has been 'selected' using procedure 'Select_Format' it
is displayed on the screen with 'Display_Format'. In addition to
display the format, all its fields are initialized according to their
specifications and the cursor is placed into the first accessible
field (Cursor Home). If there is no field on the format, the cursor
is made invisible.
Display_Format requires two parameters: Xoffset and Yoffset. They
define where on the screen the upper left corner of the new format is
to be positioned. Both values are zero based, since they specify
offsets counted from the upper left corner of the screen rather than
absolute positions. Therefore if for example Xoffset is specified as
Xoffset
'10' and Yoffset as '0' the format will be displayed with it's upper
left corner at Row 1 (the first row), Column 11.
Example:
Example
PROCEDURE Bring_Up_Myformat;
BEGIN;
Select_Format('Myformat'); {Loads 'Myformat' into Memory}
Display_Format(0,0); {displays it starting at the upper left}
END; {corner of the screen}
Chapter III, Screen Control Language page 128
Chapter III, Screen Control Language page 128
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
Note: It is user responsibility to ensure that the space specified
Note:
by Xoffset and Yoffset is large enough to hold the format to be
Xoffset Yoffset
displayed.
If the space specified is found to be to small, a 'Fatal Error'
halting the program will result.
Therefore it is recommended to preferably use the functions 'X_Max'
and 'Y_Max' wherever possible to specify offsets.
For details see overleaf.
Chapter III, Screen Control Language page 129
Chapter III, Screen Control Language page 129
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
X_Max and Y_Max
X_Max and Y_Max
FUNCTION X_Max:INTEGER;
FUNCTION X_Max:INTEGER;
Returns a value equal to 80 the width of the currently selected
format. This function is intended to be used together with the
'Display_Format' Procedure.
FUNCTION Y_Max:INTEGER;
FUNCTION Y_Max:INTEGER;
Returns a value equal to 25 the height of the currently selected
format. This function is intended to be used together with the
'Display_Format' Procedure.
Examples:
Examples
Display_Format(X_Max,1);
Display_Format(X_Max,1);
Displays the format in the upper right corner of the screen.
Display_Format(X_Max div 2,Y_Max);
Display_Format(X_Max div 2,Y_Max);
Displays the format on the bottom of the screen and horizontally
centered.
Display_Format(1,Y_Max);
Display_Format(1,Y_Max);
Displays the format in the lower left corner of the screen.
Display_Format(X_Max div 2,Y_Max div 2);
Display_Format(X_Max div 2,Y_Max div 2);
Displays the format centered on the screen.
Display_Format(X_Max-3,Y_Max -2);
Display_Format(X_Max-3,Y_Max -2);
Displays the format wit it's lower right corner positioned on line
23, column 77.
Chapter III, Screen Control Language page 130
Chapter III, Screen Control Language page 130
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
Handling format input
Handling format input
PROCEDURE Handle_Format;
PROCEDURE Handle_Format;
This routine can be seen as the kernel of the SCL System. It's basic
purpose is to obtain keyboard input and act upon it. Besides this, it
also manages a variety of other important functions such as:
* Cursor control.
* Input checks according to field specifications and display of
error messages.
* Display of Help screens and explanatory messages.
* Formatting and display of field input.
* Control of field attributes according to specifications.
* User interrupt recognition and handling.
* Invoking of background tasks.
Note: 'Handle_Format' is always called in form of a REPEAT....UNTIL
Note: REPEAT....UNTIL
loop. An example is given at the end of the description of
'Format_Done' on the next page.
FUNCTION Format_Done:BOOLEAN;
FUNCTION Format_Done:BOOLEAN;
This Function is used together with the procedure 'Handle_Format'
described above in a REPEAT....UNTIL Loop.
REPEAT....UNTIL
It checks whether the format currently being handled is finished and,
if this is the case, it then terminates it.
This means:
It also sets the color of the first and last line as well as the
first and last column of the format to Backgroundcolor if it was
Backgroundcolor
highlighted before (see 'Display_Format').
It then it checks for the presence of another format waiting on the
stack to be reactivated (one which had not been finished before) and,
if this is the case, restores the parts of the screen which had been
overwritten. Then all pointers are adjusted to this format and its
handling is carried out from where it was
interrupted before. If there was no format waiting on the stack to be
reactivated, the screen is then cleared.
Note: The complete principle of SCL's format stacking is described
Note:
in Appendix A (Sample 3).
Chapter III, Screen Control Language page 131
Chapter III, Screen Control Language page 131
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
Example:
Example
REPEAT
HANDLE_FORMAT;
{Here optional User Interrupt handling
statements could be inserted}
UNTIL FORMAT_DONE;
The above represents the basic construct of any SCL format input
handling procedure.
The REPEAT....UNTIL loop will be left as soon as the (boolean)
REPEAT....UNTIL
function 'Format_Done' detects that the format had been finished (In
this case, 'Format_Done' returns TRUE).
Whenever a User Specified Interrupt (see under 'Format
User Specified Interrupt
Specifications' in the SFD part of this manual) comes up, the
SFD
procedure 'Handle_Format' is exited and the user is given the chance
to take over control via appropriate statements within the
REPEAT....UNTIL loop as indicated in the above example. Since
REPEAT....UNTIL
'Format_Done' always returns FALSE as long as the format is not
finished, 'Handle_Format' will be reentered once the user specified
procedures have been performed.
Note that due to this construction the specification of user
interrupt handling procedures is optional; even if interrupts have
actually been specified for the appropriate format.
Chapter III, Screen Control Language page 132
Chapter III, Screen Control Language page 132
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
Format Handling Control
Format Handling Control
PROCEDURE Blank_Format;
PROCEDURE Blank_Format;
This procedure causes the space the currently handled format occupies
on the screen to be cleared (filled with spaces).
PROCEDURE Goto_Field(Fieldnr:INTEGER):
PROCEDURE Goto_Field(Fieldnr:INTEGER):
This Procedure can be used during in a User Interrupt Procedure
User Interrupt Procedure
(End_of_Field) to jump to another field on the format. It is your
responsibility to make sure that the field number to jump to is valid
and not declared as Output Only.
Output Only
PROCEDURE Finish_Format(Check:BOOLEAN);
PROCEDURE Finish_Format(Check:BOOLEAN);
This procedure is used to terminate the currently displayed format
while it is being processed by 'Handle_Format', usually depending on
a condition being checked within a User Interrupt Procedure. It
User Interrupt Procedure
causes 'Handle_Format' to react in exactly the same way as if an
appropriate keyboard key would have been pressed.
Terminate_Format requires a boolean argument which decides in what
way the format is to be finished.
If 'Check' is FALSE, it will be terminated unconditionally in a
similar way as if the 'ABORT' key would have been pressed. If 'Check'
is true, 'Handle_Format' will react as if 'ESCape' would have been
pressed. This means, before actually terminating the format it is
checked whether all mandatory fields are filled in and the
termination is refused if this should not be the case.
Notes: Terminating a format unconditionally with the above procedure
Notes:
works even in case Abort_OK is set to FALSE for this format. Please
Abort_OK
remark also, that Format_Aborted is not set to TRUE.
Format_Aborted
Detailed examples of how to handle formats including User Interrupt
User Interrupt
Procedures can be found in Appendix A under 'SCL Programming
Procedures
examples'.
Chapter III, Screen Control Language page 133
Chapter III, Screen Control Language page 133
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
Reading/Writting Format Fields
Reading/Writting Format Fields
Introduction
Introduction
In order to read and write both the (boolean) status of the
'selected' attribute as well as the actual content of format fields
several SCL routines are provided.
The following routines serve to access the field content:
The following routines serve to access the field content:
R_Cont:
R_Cont:
'Read field content'. A procedure to read the content of a field into
a string variable.
G_Cont:
G_Cont:
'Get field content'. Similar to above, but in form of a function.
W_Cont:
W_Cont:
'Write field content'. A procedure to write the content of a string
variable to a field.
C_Cont:
C_Cont:
'Clear field content'. A procedure to clear a field i.e to fill it's
content with spaces).
| The following routines serve to access the Selecte attribute of
The following routines serve to access the Selecte attribute of
format fields:
format fields:
R_Sel:
R_Sel:
'Read field selected status'. A procedure to read the status of the
'selected' attribute into a boolean variable.
G_Sel:
G_Sel:
'Get field selected status'.Similar to 'R_Sel' but in form of a
boolean function.
W_Sel:
W_Sel:
'Write field selected status'. Sets the status of the 'selected'
attribute to the desired value.
Note: A detailed description of these routines can be found on the
Note:
following pages.
Chapter III, Screen Control Language page 134
Chapter III, Screen Control Language page 134
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
Reading Field Content
Reading Field Content
PROCEDURE R_Cont(Fieldnr:INTEGER; VAR Contents:String80);
PROCEDURE R_Cont(Fieldnr:INTEGER; VAR Contents:String80);
This procedure acts on the format pointed to by 'R_Ptr'.
It reads out the content of field 'Fieldnr' and puts it left
justified into 'Contents'. Note that the content of the field is
always returned in form of a string, even in the case of numeric
variables.
In case the value in 'Fieldnr' does not represent a valid field or
'R_Ptr' does not point to a valid format an empty string (length = 0)
is returned and 'Glb_Ok' is set to FALSE.
Example: R_Cont(2,Mystring);
Example: R_Cont(2,Mystring);
The content of the second field of the format pointed
to by 'R_Ptr' is returned in 'Mystring'.
Note: R_Ptr normally either points to the format in process or to
Note:
the one that was last processed by 'Handle_Format'.
Therefore, as long as 'Handle_Format' has not been performed on a new
format, the last one is still accessible, even after it is 'finished'
(in this case however only as long as no new format has been loaded
with 'Select_Format').
If no format has been processed yet or if the format last having been
processed was overwritten by a new one (it was finished and
'Select_Format' has been called) 'R_Ptr' contains 0 (Zero) and any
attempt to read a field now would result in in a 'Fatal SCL Error'
halting the program.
For detailed information on the above refer to Appendix A.
FUNCTION G_Cont(Fn:INTEGER):String80;
FUNCTION G_Cont(Fn:INTEGER):String80;
This Function calls the procedure 'R_Cont'.
Therefore the statement Mystring:=G_Cont(2) is equivalent to
R_Cont(2,Mystring).
The use of 'G_Cont' instead of 'R_Cont' often leads to more elegant
constructs and better readable programs. It can also save in many
cases the declaration of local variables.
The two (functionally identical) examples on the next page may
illustrate this.
Chapter III, Screen Control Language page 135
Chapter III, Screen Control Language page 135
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
Examples for R_Cont and G_Cont
Examples for R_Cont and G_Cont
Example 1 (using R_Cont):
Example 1 (using R_Cont):
PROCEDURE Read_Format;
VAR
Wrkstr:String80; {TYPE String80 is defined as STRING[80]}
BEGIN;
R_Cont(1,Surname); {Read the content of field 1 to 'Surname'}
R_Cont(2,Forename); {Field 2 to 'Forename'}
R_Cont(3,Wrkstr); {Field 3 to 'Wrkstr'}
City:=Capital(Wrkstr); {Change 'Wrkstr' to upper case and} END;
{store it in 'City'.}
Example 2 (using G_Cont):
Example 2 (using G_Cont):
PROCEDURE Read_Format;
BEGIN;
Surname :=G_Cont(1); {Read the content of field 1
into 'Surname'}
Forename:=G_Cont(2); {Field 2 to 'Forename'}
City:=Capital(G_Cont(3)); {Field converted to uppercase and END;
{stored in 'City'.}
Chapter III, Screen Control Language page 136
Chapter III, Screen Control Language page 136
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
Writing Field Content
Writing Field Content
PROCEDURE W_Cont(Fieldnr:INTEGER;Cont:String80);
PROCEDURE W_Cont(Fieldnr:INTEGER;Cont:String80);
This procedure works on the format pointed to by 'W_Ptr'.
It writes the string 'Cont' to the field indicated by 'Fieldnr'. If
'Fieldnr' doesn't point to a valid field no action is performed and
'Glb_Ok' is set to FALSE.
If 'Cont' does not completely fit into the field it is cut off at the
appropriate length and 'Glb_Ok' is set to false as well. Note that
since W_Cont expects a string value, numeric information has to be
W_Cont
converted first.
In case the format being written to is currently displayed, the
appropriate field content is changed on the screen as well.
Example:
Example:
PROCEDURE Prefill;
VAR
Wrkstr : String80;
A_String : String80; {Info to be written to field 1}
A_Real_Number : REAL; {Info to be written to field 2}
A_Integer_Number : INTEGER; {Info to be written to field 3}
BEGIN;
A_String :='This is a string'; {Initialize}
A_Real_Number :=1.234; {our silly }
A_Integer_Number:=67; {examples }
W_Cont(1,A_String); {Writes 'A_String' to field 1}
STR(A_Real_Number,Wrkstr); {Converts it to a string...}
W_Cont(2,Wrkstr); {...and writes it to field 2}
W_Cont(3,St(A_Integer_Number); {uses the SCL Function 'St'..} END;
{..to convert it to a string and writes it to field 3.}
{Note:'St' can only be used to convert 'INTEGER values}
Note: W_Ptr is initially set by the procedure 'Select_Format' and
Note:
keeps on pointing to this format until it is finished. Detailed
information on 'W_Ptr' can be found in Appendix A.
Chapter III, Screen Control Language page 137
Chapter III, Screen Control Language page 137
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
Deleting Field Content
Deleting Field Content
PROCEDURE C_Cont(Fieldnr:INTEGER);
PROCEDURE C_Cont(Fieldnr:INTEGER);
This procedure 'clears' the field indicated by 'Fieldnr'. It is
equivalent to: W_Cont(Fieldnr,' '). Everything having been said under
W_Cont(Fieldnr,' ')
'W_Cont' applies to 'C_Cont' as well.
Example:
Example:
C_Cont(1); {Clears field 1, i.e. writes spaces to it.}
Chapter III, Screen Control Language page 138
Chapter III, Screen Control Language page 138
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
Reading the 'Selected' Attribute
Reading the 'Selected' Attribute
PROCEDURE R_Sel(Fieldnr:INTEGER; VAR Sel:BOOLEAN);
PROCEDURE R_Sel(Fieldnr:INTEGER; VAR Sel:BOOLEAN);
This procedure acts on the format pointed to by R_Ptr.
This procedure returns in 'Sel' the status of the Selected attribute
Selected
of the field identified by 'Fieldnr'.
In case the value in 'Fieldnr' does not represent a valid field or
'R_Ptr' is not pointing to a valid format 'Glb_Ok' is set to FALSE.
For further information on 'R_Ptr' refer to the description of
'R_Cont'.
Example:
Example:
R_Sel(2,Status);
R_Sel(2,Status);
After performing this operation, 'Status' will be TRUE if the second
field of the format pointed to by 'R_Ptr'is Selected.
Selected
FUNCTION G_Sel(Fn:INTEGER):BOOLEAN;
FUNCTION G_Sel(Fn:INTEGER):BOOLEAN;
This function calls the procedure R_Sel.
Therefore the construct Status:=G_Sel(2) is equivalent to
R_Sel(2,Status).
In many cases, the use of 'G_Sel' in favour of 'R_Sel' can not only
save the declaration of local variables but also allow more elegant
constructs. The following two (functionally identical) examples
illustrate this.
Example 1 (using R_Sel):
Example 1 (using R_Sel):
R_Sel(1,Mrs);
R_Sel(2,Miss);
Female:= Mrs or Miss;
Example 2 (using G_Sel):
Example 2 (using G_Sel):
Female:=Gsel(1) or gsel(2);
Chapter III, Screen Control Language page 139
Chapter III, Screen Control Language page 139
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
Writing the 'Selected' Attribute
Writing the 'Selected' Attribute
PROCEDURE W_Sel(Fieldnr:INTEGER;Sel:BOOLEAN);
PROCEDURE W_Sel(Fieldnr:INTEGER;Sel:BOOLEAN);
This procedure works on the format pointed to by 'W_Ptr'.
It sets the 'Selected' attribute of the field indicated by 'Fieldnr'
to the boolean value of 'Sel'.
If 'Fieldnr' doesn't point to a valid field no action is performed
and 'Glb_Ok' is set to FALSE.
In case the format being written to is currently displayed, the
appropriate field is changed to reflect the status of the 'selected'
attribute on the screen as well.
Example:
Example:
W_Sel(5,TRUE); {Marks Field 5 to be 'selected'}
Note: W_Ptr is initially set by the procedure 'Select_Format' and
Note:
keeps on pointing to this format until it is finished. For detailed
information on 'W_Ptr' refer to Appendix A.
Chapter III, Screen Control Language page 140
Chapter III, Screen Control Language page 140
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
String Handling routines
String Handling routines
FUNCTION Capital(Wrkstr: String): String;
FUNCTION Capital(Wrkstr: String): String;
This function returns the input string converted to uppercase
letters.
Example:
Example:
Mystring:=Capital(Mystring);
If Mystring was ' aBc' it becomes ' ABC'.
FUNCTION Stripleft(Wrkstr: String): String;
FUNCTION Stripleft(Wrkstr: String): String;
Returns the input string with all leading spaces stripped off.
Example:
Example:
Mystring:=Stripleft(Mystring);
If Mystring was ' ABC ' it becomes 'ABC '.
FUNCTION Stripright(Wrkstr: String): String;
FUNCTION Stripright(Wrkstr: String): String;
Returns the input string with all trailing spaces stripped off.
Example:
Example:
Mystring:=Stripright(Mystring);
If Mystring was ' ABC ' it becomes ' ABC'.
Chapter III, Screen Control Language page 141
Chapter III, Screen Control Language page 141
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
PROCEDURE Strip(VAR Wrkstr:String;VAR Len:INTEGER);
PROCEDURE Strip(VAR Wrkstr:String;VAR Len:INTEGER);
Removes all leading and trailing spaces from Wrkstr and returns it's
resulting length in len.
Example:
Example:
Mystring:=' ABC ';
Strip(Mystring,Stlen);
After performing the above statements, Mystring equals 'ABC' and
Stlen equals 3.
FUNCTION Charstring(Whatchar:CHAR;Len:INTEGER):String;
FUNCTION Charstring(Whatchar:CHAR;Len:INTEGER):String;
Returns a string of length = Len, completely filled with Whatchar.
Example:
Example:
Mystring:=Charstring('A',5);
Mystring now contains 'AAAAA'.
PROCEDURE Frontstring(Str:String; VAR Head,Tail:String);
PROCEDURE Frontstring(Str:String; VAR Head,Tail:String);
Returns the first word of 'Str' in 'Head' and the remainder in
'Tail'. In both cases, leading blanks are stripped off. Word
separators can be one or more blanks. If 'Str' only contains one
word, 'Tail' is returned with a length of 0 (zero).
Example:
Example:
Var
S1,
S2 :String;
Begin;
Frontstring('This_is.a-Frontstring 'This_is the tail ',S1,S2);
End;
S1 now contains 'This_is.a-Frontstring' and S2 contains
'This_is the tail '.
Please notice that trailing spaces in the tail are not removed.
Please notice that trailing spaces in the tail are not removed.
Chapter III, Screen Control Language page 142
Chapter III, Screen Control Language page 142
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
FUNCTION Justify_Left(STR:String;Len:INTEGER):String;
FUNCTION Justify_Left(STR:String;Len:INTEGER):String;
Returns the input string justified left in a field of length Len. The
remaining part of the field is filled up with spaces.
If the input string was, after the leading and trailing spaces were
removed, still longer than len, it is cut off at len. In this case,
Glb_Ok is set to false.
Example 1 :
Example 1 :
Mystring:=' abc ';
Mystring:=Justify_Left(Mystring,5);
After execution, Mystring is equal to 'abc '.
Example 2 :
Example 2 :
Mystring:=' abc ';
Mystring:=Justify_Left(Mystring,2);
In this example, Mystring would be returned as 'ab' and Glb_Ok would
be false.
FUNCTION Justify_Right(STR:String;Len:INTEGER):String;
FUNCTION Justify_Right(STR:String;Len:INTEGER):String;
Returns the input string justified left in a field of length Len.
with the part before the text being filled up with spaces. If the
input string without leading and trailing spaces is longer than len,
it is cut off at len. In this case, Glb_Ok is set to false.
Example 1:
Example 1:
Mystring:=' abc ';
Mystring:=Justify_Right(Mystring,5);
This example returns Mystring = ' abc'.
Example 2:
Example 2:
Mystring:=' abc ';
Mystring:=Justify_Right(Mystring,2);
Mystring would now be equal to 'ab' and Glb_Ok would be false.
Chapter III, Screen Control Language page 143
Chapter III, Screen Control Language page 143
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
FUNCTION Justify_Center(STR:String;Len:INTEGER):String;
FUNCTION Justify_Center(STR:String;Len:INTEGER):String;
Returns the input string centered in a field of length Len. If the
input string without leading and trailing spaces is longer than Len,
it is cut off at Len. In this case, Glb_Ok is set to false.
Examples :
Examples :
Mystring:=' abc ';
1. Mystring:=Justify_Center(Mystring,5);
This example returns Mystring = ' abc '.
2. Mystring:=Justify_Center(Mystring,1);
The value returned is 'a' and Glb_Ok is false.
Chapter III, Screen Control Language page 144
Chapter III, Screen Control Language page 144
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
System Functions
System Functions
FUNCTION Environment(Name:String128):String128;
FUNCTION Environment(Name:String128):String128;
This function returns the content of the specified line out of the
DOS Environment. For Details on the DOS Environment and how it can be
DOS Environment
used refer to the description of the 'Set' command in your DOS
manual.
Example:
Example:
Var Mystr:String;
BEGIN;
Mystr:=Environment('COMSPEC');
END;
Mystring contains now the complete path and name of your systems
primary command processor, for example 'C:/COMMAND.COM'.
PROCEDURE Execute(VAR Progstring:String80); VAR Result:INTEGER);
PROCEDURE Execute(VAR Progstring:String80); VAR Result:INTEGER);
This Procedure executes the program specified by 'Progstring'. Once
this program has finished execution, control is returned to the
calling program (your application).
Since Execute does not read the settings of 'Path' or 'Environment',
Execute
'Progstring' must contain, beside the actual program name, the
complete path description if the program to be executed is not in the
Active directory. In addition, 'Progstring' can optionally contain
Active directory
one or more parameters. The program name extension (i.e '.EXE' or
'.COM' is optional. If no extension is specified, Execute will first
Execute
look for a '.COM' and then, in case it is not found for a '.EXE'
file. The result of the operation are returned in DOSERROR and
DOSEXTCODE (see your Turbo Pascal Manual).
Example:
Example:
Execute('C:\Myprog firstparam secondparam thirdparam');
{Fires up 'Myprog' with three parameters. Once 'Myprog' has finished,
control is passed back to your application. Note that no extension
for 'Myprog' has been specified in the above example. If 'Execute'
does not find an extension, it first tries '.COM' and if such a file
cannot be found, it then tries '.EXE'}
Note: See also the 'ExecuteDos' command.
Note:
Chapter III, Screen Control Language page 145
Chapter III, Screen Control Language page 145
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
PROCEDURE ExecuteDos(Command:String128);
PROCEDURE ExecuteDos(Command:String128);
This procedure fires up the DOS command processor (usually
COMMAND.COM) and passes the string contained in 'Command' to it. The
command processor the acts upon this string in the same way as if it
had been entered on the normal DOS prompt.
Once the command has been executed, the command processor terminates
and control is passed back to your application. The results of the
operation are returned in DOSERROR and DOSEXITCODE (see turbo Pascal
4.0 Manual).
If 'Command' is an empty string (i.e a string with a length of 0) or
if it only contains blanks, the DOS Command processor is fired up and
remains active for input until it is terminated with the DOS Command
Exit (refer to your DOS Manual for details). Then control is passed
Exit
back to your program.
Note: In addition to actual DOS commands there are also some other
Note:
programs which require COMMAND.COM to be running in order to execute
properly. This applies particularly to many external commands (for
example CHKDSK.COM) but also to all kind of batch file processing.
Such tasks must therefore be started up using 'ExecuteDos' rather
than 'Execute'.
An important restriction for both 'Execute' and 'ExecuteDos' is the
fact that they only work if the application program has been compiled
to disk. In addition you must make sure that enough memory has been
left over for the programs to be executed. In order to achieve this
you must limit the Maximum free dynamic memory value (the 'A'
Maximum free dynamic memory
selection on TURBO PASCALS 'Option' menu) to an appropriate value
prior to compiling your program. The value to choose cannot be
exactly determined, it very much depends on your program. Crude
guidelines can be found in Appendix A.
Examples:
Examples:
ExecuteDos('Dir a:*.*')
ExecuteDos('Dir a:*.*')
{Loads the command processor and passes 'Dir a:*.*' to it. Once the
'Dir' command has been performed, the command processor terminates
and control is passed back to your program.}
ExecuteDos('');
ExecuteDos('');
{Invokes DOS including the familiar prompt. You can now enter any
commands you want. 'Exit' returns you to your program.
Note: For further examples of the above constructs refer to Appendix
Note:
A.
Chapter III, Screen Control Language page 146
Chapter III, Screen Control Language page 146
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
Date related routines
Date related routines
Most of the following routines apply the specifications being
contained in the DOS Country Information for date formatting. This
DOS Country Information
offers the tremendous advantage that the appropriate routines in
your program never have to be changed, independant of the country the
program is used in.
For more details on this matter please refer to the Appendix A.
FUNCTION Date:String10;
FUNCTION Date:String10;
Returns the system date in form of a string. Both its format, i.e
MMDDYY or DDMMYY, and the delimiters being used are obtained and
automatically set according to the Country Information SCL has been
Country Information SCL
told to use. By default, SCL assumes the country specified in the
SCL
file 'CONFIG.SYS'. There are several possibilities to influence or
override this selection within SCL, for details refer to Appendix A.
SCL
Assuming the Country is UK (Country = 44) 'Date' returns a string of
the form 'DD-MM-YY', in the case of Germany (Country = 49) it would
be 'DD.MM.YY' and for USA (Country = 1) the format would be 'MM-DD-
YY'.
FUNCTION Date_String(Y,M,D:WORD):String10;
FUNCTION Date_String(Y,M,D:WORD):String10;
This function returns the date passed to it as integers (Y,M and D)
in form of a string. Everything having been said above for the
function 'Date' applies to 'Date_String' as well. Date_String accepts
the year in both 2 and 4 digit format.
Chapter III, Screen Control Language page 147
Chapter III, Screen Control Language page 147
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
PROCEDURE Check_Date(VAR Date_Str:String10; VAR Y,M,D:WORD);
PROCEDURE Check_Date(VAR Date_Str:String10; VAR Y,M,D:WORD);
'Check_Date' converts 'Date_Str' into three integers values Y,M and
D. 'Date_Str' must contain a valid date in the format DD-MM-YY or
MM-DD-YY, depending on the Country Information being used (see
Country Information
above). The separators can be any non numerical characters. Leading
zeroes can be omitted. The year can be entered either in full (as for
example '1987') or as a 2 digit number (as '87').
The date in 'Date_Str' is checked for validity and, if it is found to
be invalid, 'Glb_Ok' is set to false.
FUNCTION Weekday(Y,M,D:WORD):INTEGER;
FUNCTION Weekday(Y,M,D:WORD):INTEGER;
'Weekday' calculates the day of the week for the date passed to it in
Y,M and D. The day of the week is returned in form of an Integer
number. The meanings are: 0=Sunday, 1=Monday and so on. Please notice
that if the year is passed to this function as a 2 digit value 1900
is added to it. Therefore this routine cannot be used for years below
100 A.D.
FUNCTION Julian_Date(VAR Y,M,D:WORD):REAL;
FUNCTION Julian_Date(VAR Y,M,D:WORD):REAL;
This function returns the date passed to it in Y,M,D in form of a
number of days since 1.Jan 00 A.D. The value passed back is in form
of a REAL number. Julian_Date can be ideally used to calculate the
number of days between two dates. If 'Y' contains a value less than
100, 1900 is added to it. Therefore this routine can not be used for
any year below 100 A.D.
PROCEDURE Normal_Date(VAR Julian:REAL;VAR Y,M,D:WORD);
PROCEDURE Normal_Date(VAR Julian:REAL;VAR Y,M,D:WORD);
Normal_Date is the counterpart of 'Julian_Date' above, i.e it
converts a Julian date passed to it into three Integer Values Year,
Month and Day.
Note: For examples on how to use the above routines please refer to
Note:
Appendix A.
Chapter III, Screen Control Language page 148
Chapter III, Screen Control Language page 148
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
Time related Routines
Time related Routines
FUNCTION Time(Seconds:BOOLEAN):String10;
FUNCTION Time(Seconds:BOOLEAN):String10;
'Time' returns the system time (24 hour based) in form of a string.
If 'Seconds' is TRUE, this string has the format HH:MM:SS, otherwise
it is HH:MM. The separators being used (in the above example ':')
depends on the Country Information and can therefore be different
Country Information
depending on the country. Refer to Appendix A for details.
FUNCTION Time_String(H,M,S:WORD):String10;
FUNCTION Time_String(H,M,S:WORD):String10;
'Time_String' converts the time passed to it in H,M and S to a string
of the form 'HH:MM:SS'. Leading blanks are replaced by '0'.
Everything having been said under 'Time' regarding separators
applies to this function as well.
In order to obtain a time string without seconds the following
construct may be used:
Mystring:=COPY(Time_String(H,M,S),1,5);
PROCEDURE Check_Time(VAR Time_Str:String10; VAR H,M,S : WORD);
PROCEDURE Check_Time(VAR Time_Str:String10; VAR H,M,S : WORD);
Converts the value in 'Time_Str' to three Integers and checks it for
validity. If the check does not succeed, 'Glb_Ok' is set to false.
The string passed in 'Time_Str' must have one of the following
formats:
'HH:MM:SS' or 'HH:MM'. Leading zeroes can be omitted. Separators can
be any non numerical characters. Hours are assumed to be based on the
24 hour format.
Chapter III, Screen Control Language page 149
Chapter III, Screen Control Language page 149
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
Background Processing Tasks
Background Processing Tasks
SCL is capable to perform user written routines as Background tasks.
Background tasks
There are two different hooks for Background Tasks provided in SCL,
Background Tasks
one for low priority and the other for high priority work.
The High priority background task is unconditionally performed by SCL
every time it goes through the internal loop of 'Handle_Format'
(Whenever SCL waits for keyboard input it is idling in this loop).
The low priority background task is identical except that it is only
performed when no other tasks are pending, i.e. there is no keyboard
input waiting to be processed and no screen updates are required.
In order to declare a user written routine (Procedure) to be
performed as a background task by SCL all you need is to include one
of the following two statements in the program:
LP_Background_Pointer:[email protected]
{this will cause SCL to execute
Priority background task}
or
HP_Background_Pointer:[email protected]
{SCL will execute
Background Task}
Note: Please notice that background procedures must be compiled with
Note:
the 'Force Far Calls' Compiler Option.
More details on Background tasks can be found in the explanation of
SAMPLE4 distributed in Appendix A.
Chapter III, Screen Control Language page 150
Chapter III, Screen Control Language page 150
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
Other Routines
Other Routines
FUNCTION St(I:INTEGER):String80;
FUNCTION St(I:INTEGER):String80;
Returns an Integer number converted to a string. This function is
especially useful to write numeric values to format fields.
Example: Mystring:=St(15) returns '15' in Mystring.
Example
FUNCTION Rst(R:REAL;Decimals:INTEGER):String80;
FUNCTION Rst(R:REAL;Decimals:INTEGER):String80;
Returns an Real number converted to a string. Decimals must contain
the number of positions to be shown after the decimal point.
Example: Mystring:=Rst(3.55555,2) returns '3.56'.
Example
FUNCTION Nr(St:String80) : INTEGER;
FUNCTION Nr(St:String80) : INTEGER;
Converts a string into an Integer number. 'St' must be a string
expressing an integer value. If 'St' does not epress an Integer value
according to the rules for numeric constants then 'Nr' returns 0
(zero) and Glb_Ok is set to false.
This function is mainly intended to read numeric format fields into
integer variables.
Example: My_Integer_Number :=Nr(G_Var(2));
Example
FUNCTION Rnr(St:String80) : REAL;
FUNCTION Rnr(St:String80) : REAL;
Converts a string into an Real number. 'St' must be a string
expressing a valid real value. If 'St' does not epress a Real value
according to the rules for numeric constants then 'Rnr' returns 0
(zero) and Glb_Ok is set to false.
This function is mainly intended to read the contents of numeric
format fields into 'Real' variables.
Example: My_Real_Number :=Rnr(G_Var(2));
Example
Chapter III, Screen Control Language page 151
Chapter III, Screen Control Language page 151
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
FUNCTION Power(Mantissa, Exponent : REAL):REAL;
FUNCTION Power(Mantissa, Exponent : REAL):REAL;
Returns the value of Mantissa raised to the power of Exponent.
FUNCTION Exist(Fn : String80):BOOLEAN;
FUNCTION Exist(Fn : String80):BOOLEAN;
Returns TRUE if a file with the name of Fn exists. Fn can contain a
complete path description according to DOS rules.
PROCEDURE Beep;
PROCEDURE Beep;
Creates a sound with a length of 'Beep_Time' clock ticks, alternating
every every clock tick between the two frequencies 'Beep_Frequency_1'
and 'Beep_Frequency_2'.
Note: A clock tick occurs approximately 18.2 times per second (about
Note:
every 55 ms).
FUNCTION Sys_Msg(Msgnr : INTEGER):String80;
FUNCTION Sys_Msg(Msgnr : INTEGER):String80;
Returns the text of record
used in user programs to receive strings etc stored in this file (See
also Appendix A; "The error message file").
FUNCTION Format_Name:String10;
FUNCTION Format_Name:String10;
Returns the name of the currently active format.
Chapter III, Screen Control Language page 152
Chapter III, Screen Control Language page 152
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
Chapter IV
Chapter IV
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
This Page is intentionally left blank
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
S C L
S C L
Data Communications Subsystem
Data Communications Subsystem
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
Introduction
Introduction
Due to their background tasking capability, SCL programs are ideally
suited for data communications.
This opens many exciting possibilities especially in the area of
micro-mainframe connections, but also allow you to build terminal
emulators etc.
The datacom routines provided by SCL allow you to easily develop
complex protocols that enable SCL programs to communicate with other
machines via the RS232 serial interface.
All necessary communications parameters can be programatically
changed and easily adapted to any requirements.
The actual handling and monitoring of the RS232 port is interrupt
driven and therefore very powerful without imposing unnecessary
overhead on your program.
The following discusses the complete SCL Data Communications
Subsystem. In order to help you develop your own protocols two
example programs have been provided on your distribution disks, these
will be discussed as well.
Note:
Note:
In order to utilize the SCL Data Communications routines, your
computer must be equipped with a serial asynchronous Interface
(COM1:). This Interface will typically be connected to a Modem.
CHAPTER IV, SCL Data Communication subsystem page 156
CHAPTER IV, SCL Data Communication subsystem page 156
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
Global Communications Parameters
Global Communications Parameters
The following parameters must be set according to your needs.
Since all major parameters are declared using Typed Constants this
Typed Constants
can be done either in the program source or during runtime.
DC_Parity
DC_Parity
Declaration:
CONST Dc_Parity : CHAR = 'E';
This parameter determines which parity is being used, if any. The
possible values are 'E' (Even), 'O' (Odd) and 'N' (None).
DC_Stopbits.
DC_Stopbits.
Declaration:
CONST Dc_Stopbits : Integer = 1;
Set this value to 2 if two stopbits are required.
DC_Speed
DC_Speed
Declaration:
CONST Dc_Speed : Integer = 9600;
This parameter determines the line speed in baud. The possible values
are 110, 150, 300, 600, 1200, 2400, 4800 and 9600 baud.
DC_Charsize
DC_Charsize
Declaration:
CONST Dc_Charsize : Integer = 7;
This value determines the number of bits per character. The possible
values are 7 or 8.
BCC_Set
BCC_Set
Declaration:
CONST BCC_Set : BOOLEAN = FALSE;
If this variable is TRUE, a Block Check Character is sent with all
messages. Refer to the description of 'Send_Buffer' for further
details.
CHAPTER IV, SCL Data Communication subsystem page 157
CHAPTER IV, SCL Data Communication subsystem page 157
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
Timers and Delays
Timers and Delays
Tx_Char_Timeout
Tx_Char_Timeout
Declaration:
CONST Tx_Char_Timeout : INTEGER = 500;
Maximum time to wait until the previous character has been sent in
milliseconds. See also procedure 'DC_Write'.
Rts_Cts_Timeout
Rts_Cts_Timeout
Declaration:
CONST Rts_Cts_Timeout : INTEGER = 500;
Maximum time in milliseconds to wait for 'Clear to Send' after
'Request to send' was raised. See also function 'Tx_Ok'.
Rts_Cts_Delay
Rts_Cts_Delay
Declaration:
CONST Rts_Cts_Delay : INTEGER = 0;
Minimum time in milliseconds between the raising of 'Request to send'
and sending of the first character.
This option is required with some datasets where 'clear to send' may
come up before the modem is actually ready to receive the first
character.
Rts_Holdover
Rts_Holdover
Declaration:
CONST Rts_Holdover : INTEGER = 0;
The time in milliseconds to wait before 'Request to send' is dropped
after the last character has been transmitted.
This option is required with some datasets in order to avoid datacom
line noise.
CHAPTER IV, SCL Data Communication subsystem page 158
CHAPTER IV, SCL Data Communication subsystem page 158
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
Data Communications Control Characters
Data Communications Control Characters
The following definitions have been provided to enhance the
readability and to facilitate the writing of terminal and line
protocols.
CONST
Nul = $0;
Soh = $1;
Stx = $2;
Etx = $3;
Eot = $4;
Enq = $5;
Ack = $6;
Bel = $7;
Con = $7;
Bs = $8;
Ht = $9;
Lf = $a;
Vt = $b;
Ff = $c;
Cr = $d;
S0 = $e;
S1 = $f;
Dle = $10;
Dc1 = $11;
Dc2 = $12;
Dc3 = $13;
Dc4 = $14;
Nak = $15;
Syn = $16;
Etb = $17;
Can = $18;
Em = $19;
Sub = $1a;
Esc = $1b;
Fs = $1c;
Gs = $1d;
Rs = $1e;
Us = $1f;
Pol = $70;
Sel = $71;
Fsl = $73;
Bsl = $74;
Del = $7f;
CHAPTER IV, SCL Data Communication subsystem page 159
CHAPTER IV, SCL Data Communication subsystem page 159
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
Other Declarations
Other Declarations
DC_Buff_Size
DC_Buff_Size
Declaration:
CONST DC_Buff_Size = 2500;
This is the size of the circular buffer in which the received
characters are written by the interrupt service routine.
DC_Rx_Buffer
DC_Rx_Buffer
Declaration:
VAR DC_Rx_Buffer : ARRAY[0..DC_Buff_Size] of BYTE;
The circular buffer used by the interrupt service routine.
DC_Rx_Buff_Bottom
DC_Rx_Buff_Bottom
Declaration:
CONST DC_Rx_Buff_Bottom : INTEGER = 0;
Points to the 'bottom' (= the first character to be read) of
DC_Rx_Buffer. If DC_Rx_Buff_Bottom is equal to DC_Rx_Buff_Top then
the receive buffer is empty.
DC_Rx_Buff_Top
DC_Rx_Buff_Top
Declaration:
CONST DC_Rx_Buff_Top : INTEGER = 0;
Points to the 'Top' (= the position where the ISR will write the next
character received) of DC_Rx_Buffer. If DC_Rx_Buff_Bottom is equal to
DC_Rx_Buff_Top then the receive buffer is empty.
CHAPTER IV, SCL Data Communication subsystem page 160
CHAPTER IV, SCL Data Communication subsystem page 160
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
Bcc
Bcc
Declaration:
VAR Bcc : Byte;
Used to calculate the block check character.
DC_Open
DC_Open
Declaration:
CONST Dc_Open : BOOLEAN = FALSE;
This Typed Constant is set to TRUE if the SCL datacom system is
Typed Constant
initialized.
CHAPTER IV, SCL Data Communication subsystem page 161
CHAPTER IV, SCL Data Communication subsystem page 161
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
SCL Data Communications
SCL Data Communications
Procedures and Functions
Procedures and Functions
CHAPTER IV, SCL Data Communication subsystem page 162
CHAPTER IV, SCL Data Communication subsystem page 162
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
Initializing and Terminating DC
Initializing and Terminating DC
PROCEDURE Open_Dc(VAR Result:INTEGER);
PROCEDURE Open_Dc(VAR Result:INTEGER);
This procedure initializes the datacom subsystem and installs the
Interrupt Service Routine to receive characters. All parameters like
line speed, parity etc must be correctly set before this procedure is
called.
Both Line and Modem status after the initialization are returned in
'Result'. The meaning of 'Result' is as follows:
Bit High order byte (line status) Low order Byte (Modem)
Bit High order byte (line status) Low order Byte (Modem)
7 Time_Out Error Rx line signal detect
6 Transfer Shift Register empty Ring indicator
5 Transfer Holding Register empty Data set ready
4 Break_Detect error Clear to send
3 Framing error Delta RxLSD
2 Parity error Trailing edge RI
1 Overrun error Delta DSR
0 Data Ready Delta CTS
PROCEDURE Close_Dc;
PROCEDURE Close_Dc;
This procedure must be called to terminate the DC subsystem. It
deinstalls the interrupt service routine and reinstates the interrupt
vector to its original content. Failing to call this routine before
the program is finished can lead to strange effects and may make a
system reboot necessary.
CHAPTER IV, SCL Data Communication subsystem page 163
CHAPTER IV, SCL Data Communication subsystem page 163
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
Sending Data
Sending Data
PROCEDURE Send_Char(Code:BYTE ; VAR OK:BOOLEAN);
PROCEDURE Send_Char(Code:BYTE ; VAR OK:BOOLEAN);
This procedure raises RTS, and, once CTS is raised, sends the
character with the ASCII code of 'Code' onto the RS232 interface.
Then RTS is dropped again. If either CTS does not come up within
'RTS_CTS_Timeout' or if the character cannot be sent within
'Tx_Char_Timeout' then the operation is aborted and 'Ok' is returned
FALSE.
Example:
Example:
Send_Char(EOT,Ok); {sends an 'EOT' character (ASCII 4) }
PROCEDURE Send_String(Data:String255;VAR OK:BOOLEAN);
PROCEDURE Send_String(Data:String255;VAR OK:BOOLEAN);
This procedure is similar to 'Send_Char' except that a string (Data)
is sent.
Example:
Example:
Send_String('Hello',Ok);
PROCEDURE Send_Buffer(VAR Tx_Buff;
PROCEDURE Send_Buffer(VAR Tx_Buff;
Buff_Start,Buff_Length,Bcc_Add:INTEGER;
Buff_Start,Buff_Length,Bcc_Add:INTEGER;
Head:String255; var Ok:BOOLEAN);
Head:String255; var Ok:BOOLEAN);
This procedure first sends the string 'Head', then an 'STX' character
(ASCII 2) and thereafter 'Buff_Length' bytes of 'Tx_Buff', starting
at a displacement of 'Buff_Start' bytes. Then an 'ETX' (ASCII 3) is
sent. If 'BCC_Set' is true, a block check character follows. This
block check character is calculated by adding all characters starting
from the 'STX' up to and including the 'ETX' to Bcc_Add without
Carry, i.e using an 'XOR' function. 'Bcc_add' can be used to include
'Head' into the Bcc calculation if required.
Error handling etc are identical to the those described under
'Send_String'. The data contained in Tx_Buff must be bytes
representing the ASCII codes of the characters to be sent. This
procedure is compatible with the most commonly used data
communication protocols.
Note:
Note:
An example for 'Send_Buffer' is shown on the next page.
CHAPTER IV, SCL Data Communication subsystem page 164
CHAPTER IV, SCL Data Communication subsystem page 164
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
Example:
Example:
PROCEDURE Example;
VAR
My_Buffer:ARRAY[0..2000] of bytes;
My_Header:String255;
Write_Ok :BOOLEAN;
CONST
My_String:String255 = 'Hello';
BEGIN;
BCC_Set:=TRUE; {send block check character}
My_Header:=SOH + 'A' + '1'; {a typical header for poll/select}
MOVE(My_String,My_Buffer,LENGTH(My_String)+1); {first byte is
length of the
Send_Buffer(My_Buffer,1,LENGTH(My_String),0,My_Header,Write_Ok); END;
{displacement of 1 to exclude the byte containing length}
The above procedure causes the following string to be sent:
The BCC is calculated without header (starting from 'STX'). If it is
required to include the header into the BCC calculation, its BCC
must be calculated externally and passed to 'Send_Buffer' via
'BCC_Add'.
For this example the BCC for the header could be calculated using
the following statement:
Head_Bcc := SOH XOR ORD('A') XOR ORDd('1');
CHAPTER IV, SCL Data Communication subsystem page 165
CHAPTER IV, SCL Data Communication subsystem page 165
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
Receiving Data
Receiving Data
PROCEDURE Receive_Char(VAR Code:INTEGER; VAR Ok:BOOLEAN);
PROCEDURE Receive_Char(VAR Code:INTEGER; VAR Ok:BOOLEAN);
Returns the ASCII Code of the character in the circular receive
buffer pointed to by the 'Bottom' pointer (This character was
received from datacom and put into the buffer by the Interrupt
Service Routine). The 'Bottom' buffer pointer is then
incremented.
If the circular receive buffer does not contain any characters (Top =
Bottom) then 'Ok' is returned FALSE.
CHAPTER IV, SCL Data Communication subsystem page 166
CHAPTER IV, SCL Data Communication subsystem page 166
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
Other Functions
Other Functions
PROCEDURE Disable_Port;
PROCEDURE Disable_Port;
This Procedure can be called to disable the RS232 port temporarily,
for example to change parameters.
PROCEDURE Enable_Port;
PROCEDURE Enable_Port
This procedure reinstates datacom if it was disabled using
'Disable_Port'.
PROCEDURE Clear_Rx_Buffer;
PROCEDURE Clear_Rx_Buffer;
This Procedure clears the circular receive buffer, i.e it sets Top
equal to Bottom.
PROCEDURE Set_DC_Params;
PROCEDURE Set_DC_Params;
This Procedure must be called if data communication parameters
(speed, parity etc) have been changed.
The following sequence of procedures is recommended to change
communication parameters:
Disable_Port;
DC_Speed:=4800;
Set_DC_Params;
Enable_Port;
Clear_RX_Buffer;
PROCEDURE DC_Diagnose(On:BOOLEAN);
PROCEDURE DC_Diagnose(On:BOOLEAN);
If 'On' is TRUE, the loopback feature for diagnostic testing will be
set. This causes the output of the 'Send' shift register in the RS232
adapter to be directly looped back to the 'Receive' shift register
input, i.e all data transmitted is immediately received again. If 'On
is FALSEl the loopback feature will be reset and normal operation is
resumed.
This feature can be used for test purposes.
PROCEDURE Get_Dc_Status(VAR Status:INTEGER);
PROCEDURE Get_Dc_Status(VAR Status:INTEGER);
This procedure returns the present line and modem status. The meaning
of 'Status' is the same as described under 'Open_Dc'.
CHAPTER IV, SCL Data Communication subsystem page 167
CHAPTER IV, SCL Data Communication subsystem page 167
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
Low Level Routines
Low Level Routines
PROCEDURE Set_Dtr(On:BOOLEAN);
PROCEDURE Set_Dtr(On:BOOLEAN);
Depending on the the status of 'On', this procedure sets or resets
Data terminal Ready. If 'On' is FALSE, Request to send will also be
dropped.
PROCEDURE Set_Rts(On:BOOLEAN);
PROCEDURE Set_Rts(On:BOOLEAN);
This procedure raises or drops Request to send.
PROCEDURE DC_Write(Code:BYTE;VAR Ok:BOOLEAN);
PROCEDURE DC_Write(Code:BYTE;VAR Ok:BOOLEAN);
This procedure sends the character indicated by 'Code' onto the RS232
Interface. It does not manipulate RTS as the appropriate High Level
Routines do (Send_...). The setting and resetting of RTS can be
performed with 'Tx_Ok' and 'Set_Rts'.
If the Character cannot be sent before 'Tx_Char_Timeout' the
operation is aborted and 'Ok' is returned FALSE.
FUNCTION Tx_Ok:BOOLEAN;
FUNCTION Tx_Ok:BOOLEAN;
Tx_Ok raises 'Request to send' and returns TRUE if Clear to Send
comes up before 'Rts_Cts_Timeout'.
FUNCTION Dsr:BOOLEAN;
FUNCTION Dsr:BOOLEAN;
Dsr returns the present status of Data set ready.
FUNCTION Cts:BOOLEAN;
FUNCTION Cts:BOOLEAN;
Cts returns the present status of Clear to send.
PROCEDURE DC_Break;
PROCEDURE DC_Break;
This procedure causes a 'Break' to be sent.
CHAPTER IV, SCL Data Communication subsystem page 168
CHAPTER IV, SCL Data Communication subsystem page 168
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
PROCEDURE DC_Isr;
PROCEDURE DC_Isr;
This is the Interrupt service routine for interrupt Hex 0C. It is
called by the IRQ4 whenever a character has been received via the
RS232 Interface. DC_Isr fetches this character and places it into the
circular Receive buffer where it the can be read using
'Receive_Char'. DC_Isr may not be called directly by a user program.
CHAPTER IV, SCL Data Communication subsystem page 169
CHAPTER IV, SCL Data Communication subsystem page 169
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
SCL Data communications
SCL Data communications
Example Programs
Example Programs
Chapter IV, SCL Data Communication example programs page 170
Chapter IV, SCL Data Communication example programs page 170
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
A Simple Line Monitor (SAMPLE7.PAS)
A Simple Line Monitor (SAMPLE7.PAS)
In this example program the SCL datacom routines are used to build a
simple datacom line monitor which interprets and displays and
interprets the traffic on a datacom line.
The major datacom parameters like baudrate, wordsize, number of
stopbits and parity can be dynamically changed while the
interpretation of the line traffic is instantly visible. This program
is therefore a neat tool to rapidly decipher the parameter settings
of the datacom line you are connected to. In order to verify the
functionality of this program, just connect COM1: to a busy datacom
line and start it.
Below you find the complete source code of the line monitor program,
a detailed description follows afterwards.
Chapter IV, SCL Data Communication example programs page 171
Chapter IV, SCL Data Communication example programs page 171
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
Listing of SAMPLE7.PAS
Listing of SAMPLE7.PAS
PROGRAM dc_monitor; {a simple datacom line monitor}
uses scl; {make SCL accessible}
VAR
Ok : BOOLEAN;
Wrkstr : String80;
Temp : INTEGER;
Freeze : BOOLEAN;
FUNCTION Xlate(Cn:INTEGER):String10; {datacom control character} VAR
Tmp:String10; {interpretation}
BEGIN;
CASE Cn OF
$0 : Tmp:='
$1 : Tmp:='
$2 : Tmp:='
$3 : Tmp:='
$4 : Tmp:='
$5 : Tmp:='
$6 : Tmp:='
$7 : Tmp:='
$8 : Tmp:='
$9 : Tmp:='
$a : Tmp:='
$b : Tmp:='
$c : Tmp:='
$d : Tmp:='
$e : Tmp:='
$f : Tmp:='
$10: Tmp:='
$11: Tmp:='
$12: Tmp:='
$13: Tmp:='
$14: Tmp:='
$15: Tmp:='
$16: Tmp:='
$17: Tmp:='
$18: Tmp:='
$19: Tmp:='';
$1a: Tmp:='';
$1b: Tmp:='
$1c: Tmp:='
$1d: Tmp:='
$1e: Tmp:='
Chapter IV, SCL Data Communication example programs page 172
Chapter IV, SCL Data Communication example programs page 172
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
$1f: Tmp:='
$70: Tmp:='
$71: Tmp:='
$72: Tmp:='
$73: Tmp:='
$7f: Tmp:='
$80..$ff:
Tmp:='<' + St(Cn) + '>'; {return character code} ELSE
Tmp:=CHR(Cn); {return character}
END;
Xlate:=Tmp;
END;
{$F+} {far call option required for SCL background tasks}
PROCEDURE Lp_Background_Task; {updates the line traffic field}
BEGIN;
IF NOT Freeze THEN {F9 toggles Freeze}
BEGIN;
REPEAT
Receive_Char(Temp,Ok); {receive char from datacom}
IF Ok THEN {there was one}
BEGIN;
Wrkstr:=Wrkstr+Xlate(Temp); {interpret it}
WHILE LENGTH(Wrkstr) > 76 DO {cut off oldest}
DELETE(Wrkstr,1,1);
END;
UNTIL NOT Ok; {no more characters}
W_Cont(7,Wrkstr); {update traffic field}
END;
END;
{$F-} {reset far calls again}
Chapter IV, SCL Data Communication example programs page 173
Chapter IV, SCL Data Communication example programs page 173
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
PROCEDURE Update_Params; {spacebar pressed}
VAR Sp:INTEGER;
BEGIN;
CASE Active_Field OF
1: BEGIN; {linespeed}
Sp:=Nr(G_Cont(1)); {get current speed}
IF Sp = 110 THEN Sp:= 150 ELSE
IF Sp = 150 THEN Sp:= 300 ELSE {switch}
IF Sp = 300 THEN Sp:= 600 ELSE {to}
IF Sp = 600 THEN Sp:=1200 ELSE {next}
IF Sp = 1200 THEN Sp:=2400 ELSE {speed}
IF Sp = 2400 THEN Sp:=4800 ELSE
IF Sp = 4800 THEN Sp:=9600 ELSE
Sp:=110;
Dc_Speed:=Sp; {update speed}
W_Cont(1,St(Sp)); {update field}
END;
2: BEGIN; {char size}
Sp:=Nr(G_Cont(2));
Sp:=Sp+1;
IF Sp > 8 THEN
Sp:=5;
Dc_Charsize:=Sp; {update param}
W_Cont(2,St(Sp)); {update field}
END;
3: BEGIN;
Sp:=Nr(G_Cont(3)); {stop bits}
IF Sp = 1 THEN Sp:=2 ELSE Sp:=1;
Dc_Stopbits:=Sp; {update param}
W_Cont(3,St(Sp)); {update field}
END;
4: IF G_Cont(4) = 'Even'THEN {parity}
BEGIN;
W_Cont(4,'None');
Dc_Parity:='N';
END
ELSE
IF G_Cont(4) = 'None'THEN
BEGIN;
W_Cont(4,'Odd');
Dc_Parity:='O';
END
ELSE
BEGIN;
W_Cont(4,'Even');
Dc_Parity:='E';
END;
END;
Chapter IV, SCL Data Communication example programs page 174
Chapter IV, SCL Data Communication example programs page 174
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
Disable_Port; {temporary disable datacom}
Set_Dc_Params; {set new dc params}
Enable_Port; {enable datacom again}
END;
PROCEDURE Handle_Uf;
BEGIN;
IF Char_Code = 32 THEN {Spacebar pressed}
BEGIN;
Update_Params; {update dc params}
Char_Code:=Code_Noop; {no further action}
END
ELSE
IF Char_Code = Code_F9 THEN {F9 Pressed}
BEGIN;
Freeze:= NOT Freeze; {toggle freeze}
Char_Code:=Code_Noop; {no further action}
END
ELSE
IF Char_Code = Code_Return THEN Char_Code:=Code_Tab ELSE
IF Char_Code = Code_Escape THEN Char_Code:=Code_Noop;
END;
PROCEDURE Handle_First; {This Procedure handles format
'first'.}
BEGIN;
Select_Format('main');
W_Cont(1,St(Dc_Speed)); {prefill}
W_Cont(2,St(Dc_Charsize)); {the}
W_Cont(3,St(Dc_Stopbits)); {fields}
IF Dc_Parity = 'E' THEN W_Cont(4,'Even') ELSE
IF Dc_Parity = 'O' THEN W_Cont(4,'Odd') ELSE
W_Cont(4,'None');
Freeze:=FALSE; {display incoming traffic}
Display_Format(0,0);
REPEAT
Handle_Format; {Complete Loop to handle format input}
IF User_Function THEN {user key pressed}
Handle_Uf; {user interrupt procedure}
UNTIL Format_Done; {Either completely filled in or abort
pressed} END;
Chapter IV, SCL Data Communication example programs page 175
Chapter IV, SCL Data Communication example programs page 175
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
VAR Res:INTEGER;
BEGIN; {of main}
Wrkstr:='';
Select_Format_File('Sample7'); {initializes SCL and loads the
format file 'Sample7'}
LP_Background_pointer:[email protected]_Background_task; {invoke our screen
updating routine as low priority
background task}
Auto_Help_Set:=FALSE; {reset autohelp feature}
Open_Dc(Res); {initialize Datacom system}
Handle_First; {load,display and handle the format}
Close_Formats; {terminate SCL}
Close_Dc; {close Datacom system}
END. {of main}
Chapter IV, SCL Data Communication example programs page 176
Chapter IV, SCL Data Communication example programs page 176
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
Description of SAMPLE7.PAS
Description of SAMPLE7.PAS
Main Program
Main Program
The first SCL datacom routine being called is 'Open_DC'. It
initializes the datacom system and installs the Interrupt Service
Interrupt Service
Routine which from this very moment will receive all characters on
Routine
the datacom line and place them into the circular receive buffer.
Then the procedure 'Handle_Main' is called to display and handle the
only screen format in this program. If 'Handle_Main' is finished,
'Close_DC' is called which terminates the datacom system and
deinstalls the ISR.
Finally, 'Close_formats' terminates SCL as usual.
Handle_Main
Handle_Main
As soon as the format is selected, its fields are 'prefilled' with
the current settings of the main datacom parameters.
The format is then displayed.
The datacom line traffic is interpreted and displayed by the
procedure LP_Background_Task.
Handle_Uf
Handle_Uf
'Handle_Uf is a user function procedure acting on several keyboard
keys (Spacebar, F9, Return and Escape).
In this program, the spacebar is used to change datacom parameters.
If it is pressed, the procedure 'Update_Params' is called to process
these changes.
If F9 is pressed, the boolean variable 'Freeze' is toggled. If
'Freeze' is TRUE, the display of datacom line traffic is halted for
better readability. Pressing F9 again will restart it. If Return is
pressed, it is replaced by a 'Tab' to prevent SCL from terminating
the format.
'Escape' is replaced by a NoOp (this program is terminated by
pressing the 'Abort' key (F10).
Update_Params
Update_Params
This procedure is called whenever the spacebar is pressed. For the
currently active field, it substitutes the present SCL datacom
parameter by the next possible choice and displays its new value.
The datacom port is then temporarily disabled ('Disable_Port') before
'Set_DC_Params' is called to activate the new parameter setting.
Finally the datacom port is enabled again using 'Enable_Port'.
Chapter IV, SCL Data Communication example programs page 177
Chapter IV, SCL Data Communication example programs page 177
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
LP_Background_Task
LP_Background_Task
As long as 'Freeze' is FALSE, this 'Background processing' procedure
permanently updates the line traffic display field (field 7).
It reads all characters having been received since the last update
from the circular buffer (using 'Receive_Char').
Each character is interpreted via the function 'Xlate' (see below)
and the resulting string is then displayed in field 7. If the string
to be outputed outgrows the size of the display window, the oldest
characters are trimmed, thereby creating a horizontal scroll effect.
For further informations on background processing please refer to
Appendix A.
Xlate
Xlate
This procedure makes the line traffic more readable by translating
all ASCII codes representing datacom control characters into more
meaningful strings. For example, character ASCII #4 is translated
into the string '
Similarly, all codes above ASCII 125 are translated into strings
showing their ASCII code in '< >' brackets (example: ASCII 130 is
returned as '<130>').
For all other codes their corresponding character images are
returned.
Chapter IV, SCL Data Communication example programs page 178
Chapter IV, SCL Data Communication example programs page 178
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
A Terminal Emulator Program (SAMPLE 8)
A Terminal Emulator Program (SAMPLE 8)
This example program features a terminal emulator program using a
rather complex poll select protocol, which is even capable of
handling multiple receive/transmit buffers.
It has been derived from a 'real world' SCL program which works on a
BURROUGHS mainframe datacom network together with other terminals in
a multipoint environment at 9600 baud and emulates the datacom
protocol of a BURROUGHS TD830 Terminal.
This example program is intended to demonstrate how to write a
datacom protocol, for this reason the screen interface
deliberately is basic and only consists of a single format with two
fields, one where a message to be sent can be entered and another one
were all messages received from the mainframe are displayed.
Since nearly every mainframe type uses a different protocol, details
specific to this protocol are purposely not covered in depth, the
intention is to concentrate on the more common aspects of how to
write terminal protocols with the help of SCL.
Nevertheless this example can probably serve as a good basis for your
own developments.
Note:
Note:
There are many different possibilities to interface SCL programs to
mainframes; typically an SCL program will emulate the datacom
interface of a terminal and do all other internal tasks using its own
resources, thus presenting the user with its own powerful
capabilities. Dialogues with the mainframe are usually performed in
the background, automatically and totally transparent to the user.
Chapter IV, SCL Data Communication example programs page 179
Chapter IV, SCL Data Communication example programs page 179
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
Listing of Example Program 8
Listing of Example Program 8
The following is an extract of SAMPLE8.PAS and shows the poll select
handling routines used by this program.
CONST
Tx_Buffers = 1; {nr of xmit buffers; minimum = 1}
Rx_Buffers = 1; {nr of receive buffers; minimum = 1}
Dc_Addr_1 : Byte = $33; {first byte of terminal address}
Dc_Addr_2 : Byte = $31; {second byte of terminal address}
TYPE
Buffer_Data = ARRAY[1..Dc_Buffer_Size] OF Byte;
Buffer_Type = RECORD {description of rx and tx buffers}
Len :INTEGER; {length of data in buffer}
Data:Buffer_Data;
END;
Rx_Buffer_Type= ARRAY[0..Rx_Buffers] OF Buffer_Type;
Tx_Buffer_Type= ARRAY[0..Tx_Buffers] OF Buffer_Type;
VAR
Rx_Buffer_Overflow:BOOLEAN; {rx data > buffersize}
Rx_Buffer:Rx_Buffer_Type;
Tx_Buffer:Tx_Buffer_Type;
Result_Ok:BOOLEAN;
Ch_Code:INTEGER;
State:INTEGER; {used in poll select state machine}
Rx_Buff_Wptr, {rx buffer to be filled next}
Rx_Buff_Rptr, {rx buffer to be read next}
Tx_Buff_Wptr, {tx buffer to be sent last}
Tx_Buff_Rptr : INTEGER; {tx buffer to be sent first}
This_Char_Done:BOOLEAN; {used in poll select state machine}
Dc_Msg_Header:String255;
Cont_String:String255;
Char_Ind:INTEGER;
Ok : BOOLEAN;
Head_Bcc:INTEGER;
PROCEDURE Ps_Handler; {poll select state machine. run as }
BEGIN; {background task}
IF This_Char_Done THEN {previous character finished}
Receive_Char(Ch_Code,Ok); {get next char from dc rx buffer}
IF Ok THEN {there was a character}
Chapter IV, SCL Data Communication example programs page 180
Chapter IV, SCL Data Communication example programs page 180
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
BEGIN;
This_Char_Done:=TRUE; {preset}
CASE State OF
0:IF Ch_Code = Eot THEN State:=1; {eot received}
1:IF Ch_Code = Dc_Addr_1 THEN {first byte of address}
State:=2 {wait for second byte}
ELSE
State:=0; {reset state machine}
2:IF Ch_Code = Dc_Addr_2 THEN {second byte of address}
State:=3 {wait for cntrl char}
ELSE State:=0; {reset state machine}
3:IF Ch_Code = Pol THEN State:=4 ELSE {poll string}
IF Ch_Code = Sel THEN State:=7 ELSE {select string}
IF Ch_Code = Fsl THEN State:=15 ELSE {fast sel}
State:=0; {otherwise reset state machine}
4:IF Ch_Code = Enq THEN {end of string}
BEGIN;
This_Char_Done:=FALSE; {dont read next char}
State:=5 {next is state = 5}
END
ELSE
State:=0; {reset state machine}
5:IF Tx_Buffer[Tx_Buff_Rptr].Len = 0 THEN
BEGIN; {no data to send}
Send_Char(Eot,Ok); {send eot}
State:=0; {..and reset state machine}
END
ELSE {there is data to be sent}
BEGIN; {send it with header and bcc}
Send_Buffer(Tx_Buffer[Tx_Buff_Rptr].Data,
1,Tx_Buffer[Tx_Buff_Rptr].Len,Head_Bcc,
Dc_Msg_Header,Ok);
IF Ok THEN {successfully sent}
State:=6 {wait for ack}
ELSE
State:=0; {otherwise reset state machine}
END;
6:BEGIN;
IF Ch_Code = Ack THEN {ack received}
BEGIN;
Send_Char(Eot,Ok); {send eot}
IF Ok THEN {successfully sent}
BEGIN; {clear buffer & increase pointer}
Tx_Buffer[Tx_Buff_Rptr].Len:=0;
Tx_Buff_Rptr:=SUCC(Tx_Buff_Rptr) MOD
Tx_Buffers;
END;
State:=0; {reset state machine}
END
Chapter IV, SCL Data Communication example programs page 181
Chapter IV, SCL Data Communication example programs page 181
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
ELSE
IF Ch_Code = Nak THEN {mainframe didnt receive ok}
BEGIN; {resend data}
This_Char_Done:=FALSE;
State:=5;
END
ELSE {mainframe did not respond}
State:=0; {reset state machine}
END;
7: IF Ch_Code = Enq THEN {end of sel string}
BEGIN;
This_Char_Done:=FALSE; {dont receive next char}
State:=8; {answer}
END
ELSE
State:=0; {reset state machine}
8: IF Rx_Buffer[Rx_Buff_Wptr].Len > 0 THEN
BEGIN; {we have no rx buffer available}
Send_Char(Nak,Ok); {send nak}
State:=0; {reset state machine}
END
ELSE {we can receive data}
BEGIN;
Send_Char(Ack,Ok); {send ack}
IF Ok THEN State:=9 ELSE {ack could be sent}
State:=0; {otherwise reset state machine}
END;
9: IF Ch_Code = Soh THEN
State:=10 {SOH received}
ELSE State:=0;
10: IF Ch_Code = Dc_Addr_1 THEN {first byte of address}
State:=11
ELSE State:=0;
11: IF Ch_Code = Dc_Addr_2 THEN
State:=12 {second byte of address received}
ELSE State:=0;
12: BEGIN;
IF Ch_Code = Stx THEN {stx received}
BEGIN;
Bcc:=Stx XOr Head_Bcc; {start bcc calculation}
Char_Ind:=1; {init rx buffer}
State:=13; {rx data}
END
ELSE
State:=0; {reset state machine}
END;
Chapter IV, SCL Data Communication example programs page 182
Chapter IV, SCL Data Communication example programs page 182
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
13: BEGIN; {receive data & write into rx buffer}
IF (Char_Ind < Dc_Buffer_Size) AND (Ch_Code <> Etx) THEN
BEGIN; {buffer not full and not etx received}
Rx_Buffer[Rx_Buff_Wptr].Data[Char_Ind]:=Ch_Code;
Bcc:=Bcc XOr Ch_Code; {bcc calculation}
Char_Ind:=SUCC(Char_Ind); {increase buffer index}
END
ELSE
IF Ch_Code = Etx THEN {etx received}
BEGIN;
Bcc:=Bcc XOr Etx; {get final bcc}
Rx_Buffer[Rx_Buff_Wptr].Len:=Char_Ind - 1;
State:=14;
END
ELSE {rx buffer overflow}
BEGIN;
State:=0; {reset state machine}
Rx_Buffer_Overflow:=TRUE; {set flag}
END;
END;
14: BEGIN;
IF Ch_Code = Bcc THEN {received = calculated bcc}
BEGIN;
Send_Char(Ack,Ok); {send an ACK}
IF Ok THEN {successfully sent, next rx buffer}
Rx_Buff_Wptr:=SUCC(Rx_Buff_Wptr) MOD Rx_Buffers
ELSE
Rx_Buffer[Rx_Buff_Wptr].Len:=0;{forget rx data}
END
ELSE {bcc error}
BEGIN;
Rx_Buffer[Rx_Buff_Wptr].Len:=0;{forget rx data}
Send_Char(Nak,Ok); {send nak}
END;
State:=0; {reset state machine}
END;
15: IF Ch_Code = Soh THEN State:=16 ELSE State:=0; {FSL}
16: IF Ch_Code = Dc_Addr_1 THEN State:=17 ELSE State:=0;
17: IF Ch_Code = Dc_Addr_2 THEN State:=18 ELSE State:=0;
Chapter IV, SCL Data Communication example programs page 183
Chapter IV, SCL Data Communication example programs page 183
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
18: BEGIN;
IF Ch_Code = Stx THEN {stx received}
BEGIN;
IF Rx_Buffer[Rx_Buff_Wptr].Len > 0 THEN
State:=0 {no rx buffer available}
ELSE
BEGIN; {start bcc calculation}
Bcc:=Stx XOr Head_Bcc;
Char_Ind:=1; {init buff index}
State:=13; {wait for rx data}
END;
END
ELSE
State:=0; {reset state machine}
END;
ELSE State:=0; {reset state machine}
END; {end case}
IF Ch_Code = Eot THEN State:=1; {preset state machine}
END;
END;
PROCEDURE Clear_Rx_Buffers; {clear all rx buffers}
VAR X:INTEGER;
BEGIN;
FOR X:=0 TO Rx_Buffers DO
Rx_Buffer[X].Len:=0; {set length to 0}
Rx_Buff_Wptr:=0; {both pointers to 0}
Rx_Buff_Rptr:=0;
END;
PROCEDURE Clear_Tx_Buffers; {clear all xmit buffers}
VAR X:INTEGER;
BEGIN;
FOR X:=0 TO Tx_Buffers DO
Tx_Buffer[X].Len:=0; {set length to 0}
Tx_Buff_Wptr:=0; {set both pointers to 0}
Tx_Buff_Rptr:=0;
END;
Chapter IV, SCL Data Communication example programs page 184
Chapter IV, SCL Data Communication example programs page 184
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
PROCEDURE Init_Ps; {init poll select system}
VAR
Stat:INTEGER;
BEGIN;
Rx_Buffer_Overflow:=FALSE;
Cont_String:=CHR(Dc_Addr_1) + CHR(Dc_Addr_2)
+ CHR(Pol) + CHR(Enq); {set up contention string}
Dc_Msg_Header:=CHR(Soh)+CHR(Dc_Addr_1)+CHR(Dc_Addr_2); {header}
Head_Bcc:=Dc_Addr_1 XOr Dc_Addr_2; {calculate bcc for header}
State:=0; {reset state machine}
Clear_Rx_Buffers; {clear rx buffers}
Clear_Tx_Buffers; {clear tx buffers}
This_Char_Done:=TRUE;
Open_Dc(Stat); {open datacom & install ISR}
Send_String(Cont_String,Result_Ok); {send contention string}
END;
FUNCTION Data_Received:BOOLEAN; {returns true if at least one }
BEGIN; {of the rx buffers contains data}
Data_Received:= Rx_Buffer[Rx_Buff_Rptr].Len > 0;
END;
FUNCTION Dc_Write_Ok:BOOLEAN; {returns true if at least one}
BEGIN; {of the tx buffers is available}
Dc_Write_Ok:=Tx_Buffer[Tx_Buff_Wptr].Len = 0;
END;
PROCEDURE Read_Dc(VAR Data;VAR Len:INTEGER;VAR Ok:BOOLEAN);
BEGIN; {call this routine to obtain data received from Mainframe}
IF Data_Received THEN {one of the rx buffers contains data}
BEGIN; {return it}
Len:=Rx_Buffer[Rx_Buff_Rptr].Len;
Move(Rx_Buffer[Rx_Buff_Rptr].Data,Data,Len);
Rx_Buffer[Rx_Buff_Rptr].Len:=0; {clear this buffer}
Rx_Buff_Rptr:=SUCC(Rx_Buff_Rptr) MOD Rx_Buffers; {incr pointer}
Ok:=TRUE;
END
ELSE
Ok:=FALSE; {no rx data available}
END;
Chapter IV, SCL Data Communication example programs page 185
Chapter IV, SCL Data Communication example programs page 185
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
PROCEDURE Write_Dc(VAR Buff; Len:INTEGER;VAR Ok:BOOLEAN);
BEGIN; {call this routine to send data to mainframe}
IF Dc_Write_Ok THEN {tx buffer available}
BEGIN;
Move(Buff,Tx_Buffer[Tx_Buff_Wptr].Data,SIZEOF(Buff));
Tx_Buffer[Tx_Buff_Wptr].Len:=Len;
Tx_Buff_Wptr:=SUCC(Tx_Buff_Wptr) MOD Tx_Buffers;
Ok:=TRUE;
END
ELSE
Ok:=FALSE; {no tx buffer available}
END;
Chapter IV, SCL Data Communication example programs page 186
Chapter IV, SCL Data Communication example programs page 186
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
Description of SAMPLE8.PAS
Description of SAMPLE8.PAS
The following is a broad discussion of the datacom routines used in
example program 8 including some useful hints on how to implement
such datacom protocols in a SCL program.
Poll-Select Terminal Protocol Handling System
Poll-Select Terminal Protocol Handling System
The main routines in this system are 'Write_DC', 'Read_DC' and
'PS_Handler'.
'Write_DC' does not actually write to the datacom line (this is done
by the underlying SCL Datacom system under the control of
'PS_Handler'). It just places the message to be sent into the first
available transmit buffer. If no empty buffer is available (i.e queue
full) an error code is returned to the calling procedure within the
user program.
'Read_DC' works in a similar fashion, it just returns the message
waiting in the first read buffer. If there are no messages pending,
an error code is returned.
'PS_Handler' forms the interface to the underlying SCL Datacom
system. It runs as a background job (called from within
'HP_Background_Task'). 'PS_Handler' checks all incoming datacom
traffic for messages addressed to this terminal and acts upon them as
required.
It mimics a typical 'State Machine' in form of a big case statement
and is controlled by the variable 'State'.
Whenever the mainframe polls the terminal, 'PS_Handler' checks
whether there is a message in the write buffer. If there is none, it
sends an 'EOT', otherwise it sends the message, preceeded with a
header containing the terminal address and followed by ETX and a
block check character.
If the mainframe prompts this message with an ACK the buffer is
discarded and the pointer increased to the next buffer to be sent.
In case the mainframe sends a message, 'PS_Handler' removes the
header and the control characters and stores it in the first
available receive buffer where it then can be fetched by 'Read_DC'.
This way of implementing a datacom protocol in a SCL program takes
full advantage of SCL's background processing capabilities and allows
a user program to treat complex datacom transactions very much like
writing and reading to an ordinary file, without having to bother
about any protocol conventions and underlying logic etc.
On the following page you find a detailed description of the flow of
data through the different layers of this datacom system.
Chapter IV, SCL Data Communication example programs page 187
Chapter IV, SCL Data Communication example programs page 187
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
Poll Select Handler Datacom read data flow
Poll Select Handler Datacom read data flow
____________________________________________
1 The RS232 adapter hardware receives the datacom message from the
mainframe and, whenever a complete character has been received,
raises a hardware interrupt.
2. This hardware interrupt invokes SCL's Interrupt Service Routine
Interrupt Service Routine
(DC_ISR) which fetches this character and places it into the
circular receive buffer.
3. 'PS_Handler', called from within 'HP_Background_Task' checks
whether one or more characters have been received since the last
time it was executing and, if this is the case, calls
'Receive_Char' to read them, one at a time, from the circular
receive buffer.
It then determines the necessary action depending on the value
of 'State'.
In case the character is not intended for this terminal it is
discarded, otherwise, if it is the last character of a control
string, 'PS_Handler' sends a prompt to the mainframe, and
finally, if it belongs to a message just being received it is
placed into the first available receive buffer. Once all
characters of this message have been received and placed into
the receive buffer, this buffer is marked valid and now
available to be read by 'Read_DC'.
4. 'Read_DC', called from within the user program, moves the
complete message from the receive buffer into the selected user
variable.
Chapter IV, SCL Data Communication example programs page 188
Chapter IV, SCL Data Communication example programs page 188
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
Poll Select Handler Datacom write data flow
Poll Select Handler Datacom write data flow
_____________________________________________
1. Called from within the user program, 'Write_Dc' moves the
message to be sent to the first available write buffer.
2. If 'PS_Handler' receives a Pollstring it checks whether one of
the write buffers contains data to be sent and if this is the
case, passes it, together with a header, on to the procedure
'Send_Buffer'.
3. Send_Buffer then calls 'DC_Write' to send it, character by
character, out to the datacom line.
4. 'PS_Handler' then waits for an 'ACK' from the mainframe and
subsequently discards the content of the write buffer.
Chapter IV, SCL Data Communication example programs page 189
Chapter IV, SCL Data Communication example programs page 189
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
Appendix A
Appendix A
Sample Program Discussion
Sample Program Discussion
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
Introduction
Introduction
In this section you be given some insight of the programming
mechanisms used in the 5 small demo programs made available to you.
Key SCL programming technic are demonstrated and discussed here.
You will be able to make ample use of these programs for training
purposes, we actually recommend that you study them thoroughly.
Having OASIS installed in your system and being already somewhat
familiar with its operation (It's dead easy, very intuitive indeed)
you will then be in a position to examine the specifications of the
formats used in these sample programs.
For each program, under the header 'What you could try:' you will
'What you could try:'
find some ideas and recommendations to familiarize yourself with SCL
and to understand the features & constructs used in the program under
review.
By following these recommendations, you will soon realize how simple
and effective the use of SCL can be. In the mean time you can
appreciate the purity of code, the speed and the flexibility provided
by OASIS SCL designed programs.
Below is a brief overview of all sample programs described herewith.
SAMPLE1
SAMPLE1
A very short program including a single format. This program is of no
practical use and is mainly intended to exhibit the basic
architecture and requirements of any SCL program.
SAMPLE2
SAMPLE2
A simple program to print mailing labels on your printer.
SAMPLE3
SAMPLE3
A program demonstrating how the SCL format stack works. In this
example, up to 10 formats are displayed on the screen
simultaneously, overlapping each other.
SAMPLE4
SAMPLE4
An automatic Disk menu program. Any program can be executed directly
from the menu just by pointing to it. It can also let you wander
across all subdirectories on your disk.
SAMPLE5
SAMPLE5
A little Demo Program giving an overview on some of the features of
SCL. Run it !
Appendix A, sample programs discussion page 191
Appendix A, sample programs discussion page 191
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
Example 1 (OASIS Easy Fields)
Example 1 (OASIS Easy Fields)
______________________________
Due to its simplicity, the first example program offers little
practical use, but beside showing the very basic structure and the
minimum requirements of any SCL program it is perfectly suited for
your first acquaintance with OASIS.
It consists of the following files:
SAMPLE1.SCS : The format file, containing a single format.
SAMPLE1.SCI : The index file to above.
SAMPLE1.MSG : Contains all Field Messages.
Field Messages
SAMPLE1.PAS : The Turbo Pascal source program as listed below.
SAMPLE1.EXE : Compiled version of SAMPLE1.PAS.
Below is a complete listing of SAMPLE1.PAS. It is meant to give you
some basic knowledge about programming with SCL. As you can see it
can't be easier. Note how little code is required.
PROGRAM first;
{$V-} {No Length Checks for Strings. Mandatory for SCL} USES
SCL; {Make SCL accessible}
PROCEDURE handle_first; {This Procedure handles format 'first'.}
BEGIN;
Select_Format('first'); {Load the format from disk}
Display_Format(0,0); {Display it in the upper left corner}
REPEAT
Handle_Format; {Complete Loop to handle format input}
UNTIL Format_Done; {Either completed or abort key pressed} END;
BEGIN; {of main}
Select_Format_File('Sample1'); {initialize SCL and load the}
{format file 'Sample1'}
handle_first; {load,display and handle the format}
Close_Formats; {terminate SCL }
END. {of main}
Appendix A, sample programs discussion page 192
Appendix A, sample programs discussion page 192
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
Explanations of SAMPLE1.PAS
Explanations of SAMPLE1.PAS
Compiler Option '$V-'
Compiler Option '$V-'
This Option is required in any SCL program. More details about
compiler options can be found in your 'TURBO PASCAL' manual. Without
this compiler option specified SCL programs won't compile.
USES Statement
USES Statement
"USES SCL;" makes SCL accessible from within this program.
Main Program
Main Program
The first statement is Select_Format_File('Sample1');. This procedure
Select_Format_File('Sample1');
initializes SCL and all required files. Since no file SAMPLE1.ERR
exists in this case, SCL only initializes the error numbers (without
the messages).
'Select_Format_File' is the first SCL statement to be executed and it
appears only once in any program.
Close_Formats; is the last SCL statement. It`closes all files and
Close_Formats;
frees the memory space previously used by SCL.
Between these two statements, the procedure which processes the
format in this program, Handle_first, is called.
Handle_first
Format Handling
Format Handling
The procedure 'Handle_First' performs the complete handling of our
screen format.
The first statement, 'Select_Format('first');' loads our format (with
'Select_Format('first');'
the name 'First') from the format file into the format stack in
memory.
'Display_Format(0,0);' then displays it on the screen starting at the
upper left corner (Displacement 0,0).
Then follows the actual format handling loop:
REPEAT
Handle_Format;
UNTIL Format_Done;
Appendix A, sample programs discussion page 193
Appendix A, sample programs discussion page 193
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
The same Loop is used to process any format in SCL. The procedure
Handle_Format is exited when any of the following occurs:
Handle_Format
* Before a new field on the format is initialized (=entered)
* Before a field is left
* Before the format is left (if it is finished)
* and, optionally, depending on the format specifications, if a
User Function Key has been pressed.
User Function Key
The boolean function 'Format_Done' returns FALSE as long as the
'Format_Done'
format has not been finished.
The format is considered to be finished if any one of the following
conditions occurs:
* All mandatory fields are filled in and either 'Escape' was hit
or 'Return' was pressed while being in the last field.
* The 'Abort' key (F10) is pressed.
Apart from reading and writing fields and, the format handling loop
is always the same, independent of the number and type of fields on a
format. In fact, the above loop can fulfill the handling of any SCL
any
screen format. There is no need to define any logic for Help screens,
Display of messages, Input error handling, field check and so on.
All this is performed automatically by SCL as part of the Format
Specifications which can be modified anytime via SFD.
Note: This program does not provide the facility to read or to write
Note:
into fields. This will be covered in the next examples.
What you could try :
What you could try :
1. Run the program and see what happens.
2. Load the format into SFD and study its specifications.
3. Add a field to the format 'First' and/or re-specify existing
fields.
4. Create your own format and modify the program to process it
according to your requirements.
Appendix A, sample programs discussion page 194
Appendix A, sample programs discussion page 194
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
Example 2 (OASIS Print Labels)
Example 2 (OASIS Print Labels)
_______________________________
This program captures address data from a screen format and uses it
to output a specified number of mailing labels on your printer. Its
basic structure is exactly the same as in example 1. For this reason
only the new features are discussed.
Notice the use of prompt and error message fields (called output
output
field in OASIS) at the bottom of your screen.
field
The error messages are held in a file called SAMPLE2.ERR. Failing to
provide such file would still produce error numbers. In this very
case SAMPLE2.ERR is just a straight copy of 'SCL.ERR' therefore
exclusively contains messages for SCL internal errors handling rather
than any user defined ones.
References to other files description can be found in example 1.
It consists of the following files:
SAMPLE2.SCS : The format file, containing a single format.
SAMPLE2.SCI : The index file to above.
SAMPLE2.MSG : Contains all Field Messages.
Field Messages
SAMPLE2.PAS : The Turbo Pascal source program as listed below.
OAS2LAB.EXE : Compiled version of SAMPLE2.PAS.
The format file SAMPLE2.SCS
The format file SAMPLE2.SCS
It contains 3 formats:
'Address' : The label entry format.
'Autohelp': See the AutoHelp Feature and the note below.
AutoHelp Feature
'Forhelp' : Specified as the format to be displayed if F1 is
F1
pressed in the global specifications of 'Address'.
Note: In case 'Autohelp' cannot be found, SCL displays the adequate
Note:
error message. Setting the SCL variable 'Autohelp_Set' to false would
prevent its display.
For the format 'Address', no Field Help Formats have been specified.
Field Help Formats
Appendix A, sample programs discussion page 195
Appendix A, sample programs discussion page 195
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
Explanations of SAMPLE2.PAS
Explanations of SAMPLE2.PAS
The following describes all new SCL constructs introduced with this
program. You can find the complete program listing on your
distribution disks.
Beep_Time:=2;
Beep_Time:=2;
This statement changes the duration of SCL's 'Beep' sound. By default
this value is set to 4. Modifying it as shown above causes the 'Beep'
to be shorter.
Most of the other SCL default values can be modified in exactly the
same fashion.
REPEAT {stay in loop until 'Abort' is pressed}
Get_Data; {display format and obtain data}
IF NOT Format_Aborted THEN {format contains valid data}
Print_Labels; {then print the desired labels}
UNTIL Format_Aborted; {F10 ('Abort') key was pressed}
'Get_Data' is the familiar format handling loop, literally identical
to the one discussed in example 1.
'Format_Aborted' is a boolean variable, which is TRUE if a format is
aborted rather than normally completed. In other words, as long as
'Format_Aborted' is FALSE we know that the format was completed in
the normal way and therefore contains valid data in agreement to the
format specifications.
'Print_Labels' contains routines to read out the content of the
format and print the appropriate mailing labels. Obviously, this can
only be done if the format contains valid data (i.e has not been
aborted).
This sequence (Display of an empty format, reading the information
and printing the desired quantity of labels) is repeated until the
user terminates by pressing 'Abort'.
Display_Format(X_Max DIV 2,Y_Max DIV 2);
Display_Format(X_Max DIV 2,Y_Max DIV 2);
X_Max is a function returning the maximum horizontal displacement
possible for the current format. Y_Max returns the maximum vertical
displacement. Hence 'Display_Format(X_Max,Y_Max)' would display a
format in the lower right corner of the screen. Combined with 'DIV
2', the format is consequently displayed in the center of the screen.
Appendix A, sample programs discussion page 196
Appendix A, sample programs discussion page 196
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
Reading the Format Content
Reading the Format Content
The procedure 'Print_Labels' is also tasked to read the format
content. Below you find a complete listing of this procedure. Its
relevant contructs are discussed afterwards.
PROCEDURE Print_Labels; {prints desired Qty of labels using the} VAR
{data on format 'Address'}
Wrkstr: String80;
I : INTEGER;
BEGIN;
FOR I:=1 TO Nr(G_Cont(7)) DO {number of labels}
BEGIN;
IF G_Sel(1) THEN Wrkstr:=G_Cont(1) ELSE` {'Mr'}
IF G_Sel(2) THEN Wrkstr:=G_Cont(2) ELSE {'Mrs'}
IF G_Sel(3) THEN Wrkstr:=G_Cont(3); {'Miss'}
WRITELN(lst,wrkstr,' ',g_cont(4));{concatenate the above}
{with a space and the content of the 'Name' field}
WRITELN(Lst); {Blank line}
WRITELN(Lst,G_Cont(5)); {the street}
WRITELN(Lst,Capital(G_Cont(6))); {the city}
WRITELN(Lst,Charstring('=',LENGTH(G_Cont(6))));
{underline the city with '=' chars}
WRITELN(Lst);
WRITELN(Lst); {Two blank lines}
END; {for loop}
END; {procedure print_labels}
Explanations to the above Procedure
Explanations to the above Procedure
As mentioned earlier in this manual, fields on formats can be read
from the very moment a format is handled ('Handle_Format') until the
next one is just about to be processed.
In our example this is done at the completion of the format.
'G_Cont(n)' is a function returning the content of field 'n' in form
of a string.
'Nr' is another function converting a string into an integer number.
Therefore the construct 'Nr(G_Cont(7)' reads the content of
field 7, converts it and returns it in form of an integer number.
Please note that there is no need to check whether field 7 really
contains an Integer number, since the relevant checks have already
been performed by SCL in accordance with the specifications of
the format itself. We can therefore be sure at this moment that the
field contains an integer in the predetermined range (1..25 in this
case).
Appendix A, sample programs discussion page 197
Appendix A, sample programs discussion page 197
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
'G_Sel(n)' is a function returning the Selected status of field 'n'.
Selected
Fields 1 to 3 are arranged into a Group of constants. This means that
Group
only one field can be selected at any time. Since we also have
specified this group as Mandatory, we know that at least (and only)
Mandatory
one field has been selected. In our example, we find out which field
this is and move its content ('Mr','Mrs' or 'Miss') to 'Wrkstr'. The
content of field 4 (the name) is then added to it, seperated by a
blank space, and finally the whole string is printed.
Next, the content of field 5 (Street) is read and printed.
The City (content of field 6) is printed in capital letters. The
construct 'Capital(G_Cont(6))' elegantly performs this operation.
Finally to underline the city with '=' characters, the construct
'Charstring('=',length(g_cont(6)))' returns a string of '='
characters with a length of the information contained in field 6
(City).
Help system
Help system
As previously mentioned, the format file for this program contains 3
formats, two of them being 'Help screens'. As you probably realized,
there is no logic whatsoever in the program to handle these screens.
In order to feature an SCL program with help screens, all you have to
do is to design them and add their names in the format specs of the
format(s) they relate to. The Autohelp screen does not have to be
Autohelp
specified at all. SCL checks whether it exists and if it does, it is
automatically displayed after a predetermined number of consecutive
input errors has occurred.
The name of the 'Autohelp' format must be identical to the one
specified as 'Autohelp_Screen' in SCLs Global Declarations (Default:
'AutoHelp').
Note: Help screens relative to a Format are specified in that
Note: Format
formats Global Specifications. Help screens associated with one or
Global Specifications
more fields on a format are specified in the Field specifications of
fields Field specifications
the appropriate field(s).
Input Messages
Input Messages
In order to display explanatory field input messages in an SCL
program you just have to specify these messages in the Field
Field
Specifications of the appropriate field and enter the number of the
Specifications
field they should be displayed into in the Global Specifications of
Global Specifications
the format. Again, there is no logic required within the program
itself for this feature to be incorporated.
Appendix A, sample programs discussion page 198
Appendix A, sample programs discussion page 198
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
Error Messages
Error Messages
System or user generated error messages are automatically displayed
if the number of the field they should be displayed into is specified
in the Global Specifications of the appropriate format.
Global Specifications
In case no error file (
be shown, otherwise the suitable message is displayed.
What you could try :
What you could try :
1. Run the program and see what it does.
2. Try to enter invalid data and see how the program reacts.
3. Load the format file into SFD and study the specifications of
the three formats.
4. Run the program without the file SAMPLE2.ERR being available
and see what happens if you make an input error.
5. Change the parameters 'Error Msg Field' and/or 'Input Msg
Field' in the Global Specifications of the format 'ADDRESS' to
0 (zero) and run the program. See what happens.
6. Try to implement 'Field Help Screens' for 'ADDRESS'.
7. Allow the program to print up to 50 labels (25 is the current
maximum).
8. Change some other Global SCL Parameters in the program,
recompile and run it.
9. Add a field for the postal code on 'ADDRESS' and modify the
program in such a way that it is printed on the label.
Appendix A, sample programs discussion page 199
Appendix A, sample programs discussion page 199
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
Example 3 (OASIS Formats Stack)
Example 3 (OASIS Formats Stack)
________________________________
This Program is a demonstration of the ability of SCL to stack
formats. A format is pushed on the stack whenever a new format is
loaded while the previous one is not yet finished. It is popped from
the stack, i.e. restored as soon as the format on top of the stack is
finished.
In simple terms, this program works as follows:
Load & Display format 'One'.
Start handling format 'One'.
Load & Display format 'Two'.
Start handling format 'Two'.
-- Keep doing the --
- same -
- with formats -
- 'Three' to 'Nine' -
Load & Display format 'Ten'.
Start handling format 'Ten'.
Terminate format 'Ten'.
Restore format 'Nine'.
Continue handling format 'Nine'.
Terminate format 'Nine'.
-- and so on down --
-- to format 'Two'--
Restore format 'One'.
Continue handling format 'One'.
Terminate format 'One'.
Terminate program.
This means that while format ten is being loaded, nine unfinished
formats are waiting in the stack to be continued. This may sound a
lot, but SCL can simultaneously hold far more formats in its stack
without any problems. There is no real limit apart from the size of
your computer memory.
If you should require more than 20 unfinished formats on the stack
simultaneously, you must then adjust the Global Constant
Global Constant
'Max_Heap_Screens' in SCL to reflect the required maximum number of
formats. For guidelines to calculate the memory requirements of an
SCL program please refer to 'System Resource Considerations' in the
reference manual.
Note: The above consideration only refers to the number of
Note:
unfinished Formats, formats that are finished before another format
unfinished Formats
is loaded do not take up any space on the stack. The Total Number of
Total Number of
Formats in a program is only restricted by your disk space capacity.
Formats
Appendix A, sample programs discussion page 200
Appendix A, sample programs discussion page 200
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
Listing of SAMPLE3.PAS
Listing of SAMPLE3.PAS
PROGRAM Stackdemo;
{$V-} {Disables LENGTH Checks FOR Strings}
USES SCL; {invoke SCL}
PROCEDURE Scl_Defaults;
BEGIN;
Beep_Time:=20; {Beep shorter}
Auto_Help_Set:=FALSE; {No autohelp in this program}
END;
FUNCTION Up:BOOLEAN;
BEGIN;
Up:=FALSE;
IF User_Function THEN {user function key pressed}
BEGIN;
IF (Active_Field = 1) AND {'Up' field}
(Char_Code = Code_Return) THEN { wants to select field}
BEGIN;
Up:=TRUE;
Char_Code:=Code_Noop; { SCL should not do anything}
END { with this input character,}
END; { i.e not mark the field as }
END; { selected}
PROCEDURE Do_Format(This_Name:String10;This_X,This_Y:INTEGER);
VAR
N,
Next_Name:String10;
Next_X,
Next_Y :INTEGER;
BEGIN;
Select_Format(This_Name); {load it from disk}
Display_Format(This_X,This_Y); {display it }
Next_X:=This_X+2; {increase displacements}
Next_Y:=This_Y+1; {for the next format to be loaded}
REPEAT
Handle_Format; {handle this format}
IF Up THEN {user wants to go up}
BEGIN;
N:=Capital(This_Name); {capital letters}
IF N = 'ONE' THEN Next_Name:='Two' ELSE {Which}
IF N = 'TWO' THEN Next_Name:='Three' ELSE {format}
IF N = 'THREE' THEN Next_Name:='four' ELSE {is}
IF N = 'FOUR' THEN Next_Name:='Five' ELSE {the
IF N = 'FIVE' THEN Next_Name:='Six' ELSE {next}
IF N = 'SIX' THEN Next_Name:='Seven' ELSE {one}
IF N = 'SEVEN' THEN Next_Name:='Eight' ELSE { ? }
Appendix A, sample programs discussion page 201
Appendix A, sample programs discussion page 201
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
IF N = 'EIGHT' THEN Next_Name:='Nine' ELSE
IF N = 'NINE' THEN Next_Name:='Ten';
Do_Format(Next_Name,Next_X,Next_Y); {Recursive}
END; {call with new name and displacements}
UNTIL Format_Done; {this format is finished.}
END; {of Do_Format}
BEGIN; {of main}
Select_Format_File('Sample3'); {initialize SCL and load}
{format file 'Sample2'}
Scl_Defaults; {change some SCL defaults}
Do_Format('one',0,0); {display&handle format 'one'}
Close_Formats; {terminate SCL}
END. {of main}
Explanations of SAMPLE3.PAS
Explanations of SAMPLE3.PAS
The only new features in this sample program are a User Interrupt
User Interrupt
Procedure and the fact that a new format is called up while the old
Procedure
one is not yet finished. There is no need to emphasize how simply
this can be achieved using SCL.
User Interrupt Procedure
User Interrupt Procedure
We mentioned already in the explanations of Sample 1 that there were
four conditions under which the procedure 'Handle_format' was exited.
A User Interrupt Procedure is a user written routine which takes
User Interrupt Procedure
control at this point. To accomplish this, the appropriate routine
(or a call to it) must be positioned within the format handling loop
as follows:
REPEAT
Handle_Format;
{---User Interrupt Routine----}
UNTIL Format_Done;
Hence the User Interrupt routine is always executed if
User Interrupt routine
'Handle_Format' has been exited, i.e. one of the four conditions
occurred.
Among those four possible conditions one states that a User Function
User Function
Key has been pressed.
Key
This is actually the condition our user interrupt procedure is based
on in this example.
We want to interfere as soon as the program user tries to select
field 1 (Up). In case field 2 (Down) is selected no action is taken
and SCL terminates the format. (If no interference occurs in the case
of field 1, SCL also automatically finishes the format since there
are no further fields to be filled in).
Appendix A, sample programs discussion page 202
Appendix A, sample programs discussion page 202
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
The test pertaining to the occurrence of the above mentioned
condition is performed by the boolean function 'Up'. Up returns TRUE
if:
1. A User Function Key (in this case Return) was pressed
and
2. field 1 (the 'Up' field) is currently selected.
and
3. the current Input character (char_code) is 'Return'.
If 'Up' is TRUE, the input character is replaced by a 'No-Op', which
causes SCL to ignore it later on (SCL will then act as if the Return
key was never pressed and consequently wait for User input).
If this does not happen SCL would, as soon as it regains control,
carry on from where it left off and consequently mark field 1 as
'Selected' before it automatically terminates the format.
If 'Up' returns TRUE, a recursive call to 'Do_Format' is made and the
whole process starts over again with the next format. If one format
is finished, i.e 'Down' has been selected or F10 (Abort) has been
pressed then SCL automatically restores the previous format from the
stack.
What you could try:
What you could try:
1. Load the format file into SCL and study the specifications of
one of the formats (they are all identical except format
'Ten', which does not have any fields).
2. Remove the statement 'Char_code:=Code_Noop;' from the function
'Up', recompile and run the program and see what happens.
3. Write your own program without recursion and with only 2 or 3
formats (you may use the format file from this example).
Appendix A, sample programs discussion page 203
Appendix A, sample programs discussion page 203
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
Example 4 (OASIS Automatic Disk Menu)
Example 4 (OASIS Automatic Disk Menu)
______________________________________
This example program is quite a useful DOS utility program. It
displays all executable files of the current directory along with all
subdirectories and the parent directory (if applicable) on a screen
format.
You can execute any program from the current directory or move to a
different subdirectory by just pointing to it.
When compared to the three previous examples, this one is fairly
complex and employs a lot more SCL features.
Despite (and maybe especially because of) the fact, that SCL has
certainly not been designed to develop DOS utilities, this example
demonstrates and highlights its tremendous power and flexibility.
The main new features exhibited in this program are:
- The 'Execute' and , 'ExecuteDos' routines.
- Background processing.
- More sophisticated User Interrupt Procedures.
The relevant components of the program will be discussed in the
following.
The Procedure Menu
The Procedure Menu
This program only uses one Format and the procedure handling this
format is called 'Menu'. It uses some advanced technics we have not
covered yet.
In the previous examples 'Display_format' was immediately called
after 'Select_format' whereas here the format is first 'filled'
before being displayed.
The procedures involved in this task are 'Init_Dir_Search',
'Display_Files' and 'Tell_Result'.
Apart from this, within the actual Format handling loop, you find a
Format handling loop
statement which invokes a User Interrupt Procedure ('Handle_Key') in
User Interrupt Procedure
case a User Function Key has been pressed. If the format has been
User Function Key
finished (and was not aborted), the procedure 'Do_Work' is executed.
All the above mentioned procedures are described in detail on the
following pages.
Appendix A, sample programs discussion page 204
Appendix A, sample programs discussion page 204
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
Init_Dir_Search
Init_Dir_Search
This procedure initializes the parameters for our Directory search.
It sets the boolean variable 'First' to TRUE and the search mask to
'*.*' (all files).
Note: 'First' is a parameter for the directory search which if TRUE,
Note:
causes it to initialize a new search, i.e to find the first filename
matching the specified mask. Once the first file has been found, it
is set to false and subsequent searches will search for the remaining
files.
Display_Files
Display_Files
The first part of this procedure is a REPEAT..UNTIL loop which calls
'Dir'. If 'Dir' returns a result of 0 (zero), meaning that a
filename matching the mask was found, the procedure
'Pick_it_if_we_need_it' is called, which determines whether this file
is either an executable file or a directory entry. If this is the
case, the file name is moved to the first available field and the
field count is increased by 1. In order to determine whether the file
found should be displayed on the format, we access the SCL variable
'Dta' (For details about the content of 'Dta' please refer to
'Advanced Programming Technics'in the reference manual).
We exit the REPEAT..UNTIL loop under any one of the following two
conditions: either the format is full or there are no more files
matching the mask. In the latter case we reinitialize 'Dir' by
calling 'Init_Dir_Search' again and we also blank the remaining
fields on the format. In every case, we also make a note of the
highest field on our format containing a filename entry.
Now that's where the real tricky part starts:
On this format we want to have two active fields at the same time,
one being the field containing the filename to be executed and the
other one where the optional parameters can be entered. SCL can only
have one active field at a time, therefore we have to cheat somehow.
One way to achieve this is to declare all the fields holding
filenames (2 to 46) as 'Output' fields and manipulate these fields
independent from the normal SCL field processing. This just leaves,
what SCL concerns, field 49 as the only cursor accessible field on
this format which is consequently active, i.e ready for input,
anytime the format is displayed.
In order to highlight the currently chosen filename field, we use the
'selected' field attribute. The procedure 'Handle_Keys', which
monitors the 'arrow' keys, determines which filename is to be
highlighted next and the highlighting itself is performed by the
procedure 'New_Field'.
Appendix A, sample programs discussion page 205
Appendix A, sample programs discussion page 205
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
Handle_Keys
Handle_Keys
This procedure acts on all User Function Keys defined for this
User Function Keys
format.
In case F9 is pressed, the field holding the currently highlighted
filename is deselected and 'Display_files' is called to refill the
format.
In case the display of the current directory is not yet complete,
('first' is FALSE) the remaining entries are searched to be displayed
now, otherwise a new search cycle is initiated to display the first
page of file names.
In case, one of the 'arrows' or 'Home' or 'End' is pressed we
determine the next field (file name) to be highlighted and call
'Next_Field' to do it.
The next two keys are only intercepted for user convenience: If
'Escape' is pressed, it is replaced by 'F10' (Abort) which
subsequently causes the program to be terminated.
If 'Return' is pressed and the parameter field (49) contains spaces
this key is replaced by an 'Escape' character, which causes the
format to be terminated instantly. The reason for this is that SCL
would interpret 'Return' in this case as a command to switch field 49
to 'Edit Mode' and we would have to press 'Return' (or 'Escape')
again to finish the format, therefore this manipulation saves the
user an additional keystroke.
With the exception of the last two cases we want SCL to ignore any
other key depression by substituting 'No_Op'.
New_Field
New_Field
This procedure is called with two parameters, the field currently
highlighted (due to be deselected) and the new field (the one about
to be selected, i.e highlighted).
This task is performed by the first two statements.
Once this is done, 'current field' matches the new field now being
highlighted.
In the same time frame three more fields need to be updated but
instead of being processed here it is treated as a background task
because another 'Arrow' key could also already be pressed. In this
case priority is given to handle this key first before attempting to
update any one of the three fields.
By making this task a background job we ensure that it is only done
when spare time is available, without delaying any pending keyboard
input.
In order to notify the Background processing procedure that updates
Background processing procedure
are to be carried out , three boolean flags are set, one for each
field to be revised.
Appendix A, sample programs discussion page 206
Appendix A, sample programs discussion page 206
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
Do_Work
Do_Work
This procedure first fetches the file name from the field currently
highlighted. In case of a directory entry it changes the current
directory accordingly.
If we are dealing with an executable file instead it first builds a
string out of the filename (including path) and the parameter entry
and then executes this file. Depending on whether it is an '.EXE'
file or not, 'Execute' or 'ExecuteDos' is used.
The reason for this is that all '.BAT' and some of the '.COM' files
(mainly some external DOS commands) require COMMAND.COM to be present
while '.EXE' files can be started directly.
On return from the previously executed program, a check for
successful execution is done and if this is the case a prompt asks
the user to press 'Return' to go back to the menu program (The reason
for not going directly back is to give him a chance to read the
screen content).
In case of problems during execution we directly go back to the menu
program and 'Tell_Result' displays an appropriate error message.
Tell_Result
Tell_Result
This procedure simply checks whether 'Execute' or 'ExecuteDos' caused
a result code indicating an error.
If an error occurred the relevant (user defined) error message is
displayed in field 50 and a 'beep' is initiated.
Note: More information on user defined error messages can be found
Note:
under 'Advanced Programming Technics'in this appendix.
LP_Background_Task
LP_Background_Task
This is assigned as a SCL background Task via the
'LP_Background_Pointer:[email protected]_Background_Task;' statement in the main
body of the program.
It is called by the SCL procedure 'Handle_Format' whenever there is
no keyboard input pending and no other work needs to be done. This
procedure is used here to update fields 46,47 and 49 after a
different filename has been selected by the user. It is based on the
simple principle that whenever the procedure is entered all three
flags set by 'Next_Field' are checked.
If one of these flags is found to be TRUE the pertinent update
procedure is performed and the flag is then set to FALSE. The update
procedures themselves are clear and easy to understand and therefore
not separately described here.
Appendix A, sample programs discussion page 207
Appendix A, sample programs discussion page 207
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
Example 5 (OASIS SCL Demo)
Example 5 (OASIS SCL Demo)
___________________________
This program is a little demo giving an overview on some SCL
features. Although 14 different screen formats are handled it remains
a rather simple program.
It consists of a main menu proposing a selection of 8 different demos
plus the possibility to terminate the program.
In order to demonstrate background processing it also features a
display of time and date on each format.
The following is a detailed explanation of its various procedures.
Menu
Menu
The Menu procedure is very straightforward. The menu format is
processed using the very same basic Format Handling Loop already
Format Handling Loop
described in example 1. Once the format is finished, upon detection
of the selected field the corresponding demo procedure is called up.
In the case field 13 being selected, the boolean variable 'Progend'
becomes TRUE which then causes the program to exit the REPEAT..UNTIL
loop and subsequently terminates the demo program. The reason for
using this boolean variable rather than 'UNTIL G_Sel(13)' is simple:
Just imagine you would come from a demo format where field 13 was
selected. Since R_Ptr would still point to this demo format,
R_Ptr
'G_Sel(13)' would access field 13 on this format rather than on our
menu. We must therefore make sure that we pass 'Handle_Format' (which
adjusts R_Ptr to the menu again) before any attempt to read a field.
This is realized by simply including the 'G_Sel' into our 'case'
statement.
Five out of the eight different demos are performed by just calling
the procedure 'Do_Format' with the appropriate format name while the
other three demos required some additional programming.
'Do_Format' is a simple procedure which selects a format, displays it
and then handles it.
In order to be able to blank the format when completed the User
Interrupt Procedure monitoring 'End_Of_Format' is employed. The other
three demos are a bit more complicated and will therefore be
discussed in detail.
Appendix A, sample programs discussion page 208
Appendix A, sample programs discussion page 208
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
Country Demo
Country Demo
Country demo demonstrates SCL's capability to work with the DOS
country information.
When compared with 'Do_Format', the main procedure of country demo
offers two additional features.
The first procedure was added to set up the fields before the format
was actually displayed on screen ('Update_Fields'). The second
procedure acts on 'End_of_field'-User Interrupts.
Interrupts
Procedure Update_Fields
Procedure Update_Fields
This procedure accesses some of the Country dependent Information
provides by SCL and writes it to the proper fields on the format.
Please note that the numeric (integer) values are converted to
strings using the 'St' function.
Procedure Handle_End_of_Field
Procedure Handle_End_of_Field
This procedure is the actual heart of 'Country demo'. Below you can
examine its listing. All programming details are discussed
afterwards.
PROCEDURE Handle_End_Of_Field; {user interrupt procedure}
BEGIN;
IF Active_Field = 4 THEN {new country code entered}
BEGIN;
IF G_Cont(4) > ' ' THEN {not blank}
BEGIN;
Scl_Country:=Nr(G_Cont(4)); {move it to SCL_Country}
Get_Country; {get country information}
IF (Country <> Scl_Country) AND (Scl_Country > 0) THEN
BEGIN; {invalid country code was entered}
Glb_Error:=24; {error number to SCL}
Scl_Country:=Nr(G_Cont(5)); {restore old country}
Get_Country; {get country info}
END
ELSE {country code was valid}
Update_Fields; {display new country info}
END;
END;
END;
Appendix A, sample programs discussion page 209
Appendix A, sample programs discussion page 209
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
The first two 'IF' statements ensure that we are in field 4 and that
this field contains data.
If this is the case, the content will be read, converted to an
integer and placed into 'SCL_Country'.
We then call the SCL procedure Get_Country' which accesses the DOS
country information and updates the relevant SCL variables
accordingly.
'Get_Country' acts as follows:
If 'SCL_Country' contains 0 (the default value) it borrows the
country information according to the setting of your computer
(Country=xxx statement in CONFIG.SYS). If SCL_Country contains any
other value (a Country-code) then SCL is set up according to this
code.
Once 'Get_Country' has been called, a check for country code validity
is performed.
It is valid when either the value returned in 'Country' is equal to
'SCL_Country' or if 0 was specified for 'SCL_Country'.
In case of invalid country code, the one previously used is restored
from field 5 (we wrote it to this field in 'Update_Fields'), and
'Get_Country' is called again with this latter value in 'SCL_Country'
to restore the variables in SCL back to valid information.
In addition, 'Glb_Err' is set to an error number pointing to a
message in SAMPLE5.ERR stating that an invalid country code was
entered.
Since 'Glb_Err' returns a value different from 0 (zero),
'Handle_Format' will enter its input error routine, beep, display the
error message and also refuse the attempt to leave field number 4
until a valid country code is keyed in.
In case of a valid code 'Update_Fields' is called once more to write
the new information into the corresponding fields.
Note: Further details about user generated error messages and the
Note:
use of 'Glb_Err' can be found in this appendix.
Appendix A, sample programs discussion page 210
Appendix A, sample programs discussion page 210
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
Date Demo
Date Demo
Date Demo demonstrates most of the date/time routines in SCLn With
the exception that the field update procedure is called 'Prefill'
here, the main procedure of 'Date_Demo' is identical to the one
described in 'Country_Demo'.
However both 'Prefill' and the user Interrupt Procedure contain a
user Interrupt Procedure
great number of new constructs which will be discussed in the
following pages.
Prefill
Prefill
This procedure fills some fields with information about todays date.
First, the SCL routine 'Get_Date' is called to retrieve todays date
as integer values.
Then the 'day of week' value is converted to the actual name which is
effectively written to field 4.
The date is then converted into a julian date. Since the function
'St' cannot be used with REAL numbers, 'STR' is used instead to
convert the julian date to a string before it finally can be written
to field 5.
Handle_End_of_Field
Handle_End_of_Field
User Interrupt Procedure is invoked whenever a 'End_of_Field'
Interrupt Procedure
condition occurs and also in the case of fields 6 and 15.
Field 6 is the one where the user can enter a date. Upon leaving
this field, a check for data entry is performed and if something has
been keyed in the following occurs:
The procedure 'Check_Date' checks the date entered for validity and
converts it to three integers for year, month and day. (Please note,
that the date is checked according to the country information
currently used. In the case of USA (1) the date is interpreted as
MMDD whereas for most other countries it is DDMM). If the date
entered is invalid, 'SCL_Err' is set to point to a user defined error
message in SAMPLEu.ERR, which causes SCL to display this message,
beep and to reject the attempt to exit this field. In addition to
this, fields 7 to 14 are blanked out. If the date entered is
found valid, the procedure 'Update_User_Date' is called which in
turn does some calculations and writes the results to fields 7 to 14.
For field 15 the process is similar, in this case the user is
supposed to enter a valid time and if he does so, 'Up
date_User_Time' is called to analyze the time entered and to write
appropriate information to fields 16 to 19.
If the time entered is invalid, a sequence identical to the one
described for the date takes place, the only difference being the
error message.
Appendix A, sample programs discussion page 211
Appendix A, sample programs discussion page 211
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
Update_User_Date
Update_User_Date
This procedure uses most of the SCL date related routines. It first
writes the values for day, month and year of the date in field 6 (and
decoded by 'Check_Date') to fields 7, 8 and 9. Then these three
values are converted into a date string by 'Date_String' and written
to field 10.
The julian date is calculated, converted to a string using 'STR' (St
cannot be used for REAL numbers, only for Integers) and written to
field 11.
After this, the number of days between today and the date entered is
calculated by simply subtracting them from each other and converting
the result to a positive number. This value is written to field 12.
The procedure 'weekday' is used to calculate the 'day_of_week'. The
result, an Integer number between 0 (sunday) and 6 (saturday) is then
converted into the matching day name and written to field 13.
100 days are then added to the julian date, the result is converted
back into year, month and day via the procedure 'Normal_Date',
formatted with the function 'Date_String' and finally written to
field 14.
Update_User_Time
Update_User_Time
This rather simple procedure converts the integer values for hours,
minutes and seconds of the time entered into field 15 to strings and
writes them to fields 16, 17 and 18.
These values are then converted to a formatted time string by the
function 'Time_String' and written to field 19.
Appendix A, sample programs discussion page 212
Appendix A, sample programs discussion page 212
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
Special Fields Demo
Special Fields Demo
Main procedure
Main procedure
This procedure is identical to those used for the 'country' and
'date' demos with one exception however; it embeds an additional User
User
Interrupt Procedure, which monitors the keyboard keys. This User
Interrupt Procedure User
Interrupt Procedure, 'Handle_User_Function' is probably the most
Interrupt Procedure
interesting part of this demo because it reveals some useful tricks
which you will find most helpful when writing your own application
programs.
Handle_User_Function
Handle_User_Function
This procedure deals with fields that have the 'Char Check' field
attribute set to TRUE.
It is therefore executed whenever one of these fields is active and
any keyboard key is pressed. Each field will be discussed separately.
Note: The reason for using 'Char Check' here is quite simple: in
Note:
this demo we have to take into consideration far more keys than the
maximum number that can be specified as 'User Functions' on one
format (10, plus any of the function keys).
In a real world program it would probably be preferable to specify
'User Function Keys' because, beside the fact it is faster
('Handle_Format' is not interrupted for each single key) it also can
save you programming work since you would know that the key pressed
must belong to the specified set.
Field 5
If the input key is a 'Space' the content of the field is changed to
something else. In this example we only use three different
possibilities but in a user program it could also be any other
number.
This field shows a nice way to make programs more userfriendly which,
in many cases can also save an additional menu.
Field 6
While this field is active we check if one of a specified set of keys
has been pressed, and if this was the case, an appropriate string is
written into the field. This construction can equally be used in the
same manner as the one demonstrated with field 5.
Appendix A, sample programs discussion page 213
Appendix A, sample programs discussion page 213
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
Field 7
When active this field displays the ASCII Code of each key pressed
with the exception of 'Return' which moves us to the next field. The
SCL internal character code notation is as follows: if the key
creates a two byte code (an ASCII Code preceded by a 'ESC'
character), 1000 is added to it, otherwise the normal ASCII value is
kept.
Field 8
The handling of this field is simple, each input character (if it is
not a 'two byte key') is converted to upper case and then displayed.
This can be useful in many application programs as well.
Note: In all cases, where you don't want SCL to take any action on a
Note:
character, simply replace it by 'Char_NoOp'. SCL will then just
ignore it.
Handle_End_of_Field
Handle_End_of_Field
This procedure monitors field 4 and checks whether it is selected or
not.
If selected it writes 'Yes' to its content, otherwise 'No'is written.
Similarly the same method can be used in all cases where the
objective is to display the state of a field with text rather than
with a display attribute.
Background Processing
Background Processing
The capability to support background processing is one of the most
powerful features of SCL.
In this example program it is used to display the time and the date
(obviously, you can do a lot more with it).
In this example program the current date and time are displayed in
two fields on each format and 'LP_Background_Task' is used to update
these fields constantly.
'LP_Background_Task' simply checks whether the actual time and date
is still reflected by the content of the two fields and if this is
not the case, updates them.
Appendix A, sample programs discussion page 214
Appendix A, sample programs discussion page 214
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
Appendix A, sample programs discussion page 215
Appendix A, sample programs discussion page 215
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
The Screen Control Language
The Screen Control Language
(SCL)
(SCL)
SCL System Details
SCL System Details
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
Service Routines
Service Routines
Interrupt Service Routines are routines which are called to handle
events within your computer. They are normally located in the
computers BIOS (Basic Input Output System). A user program can take
over the handling of interrupts. This is accomplished by placing the
address of its own interrupt routine into the BIOS Interrupt Vector
table.
SCL takes control of two interrupts with its own routines:
The clock tick interrupt (Interrupt 1CH)
The clock tick interrupt (Interrupt 1CH)
This interrupt is called by the BIOS time handling routines (Hardware
Clock) 18.2 times per second (about once every 55 milliseconds).
Every time Interrupt 1CH is called by the BIOS, control is passed to
the routine 'Clock_ISR' in SCL which then performs the necessary SCL
internal functions before control is returned to BIOS. These
functions are to control the duration of the 'Beep' Sound and the
field blinking frequency (see also the description of 'Blink_Count').
By using an Interrupt service routine instead of a normal SCL
procedure to manage these tasks it is ensured that they are performed
entirely independantly of the logic of your application program and
SCL itself. Hence a lot of unnecessary overhead is avoided because
instead of waiting for an event, SCL can perform other functions.
Consider the following example of a typical 'Beep' routine:
PROCEDURE Do_Beep;
BEGIN;
SOUND(500);
DELAY(250);
NOSOUND;
END;
If SCL was programmed like this, one would have to wait 250
milliseconds for this routine to exit without being able to do
anything else. This would not only slow down the program considerably
but it would also make background tasks like datacom etc.. virtually
impossible.
For this reason, the 'Beep' routine in SCL looks in principle as
follows:
PROCEDURE Beep;
BEGIN;
SOUND(Beep_Frequency_1);
Beep_Counter:=Beep_Length;
END;
Appendix A, SCL system details page 217
Appendix A, SCL system details page 217
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
Instead it is left to 'Clock_ISR' to decrement 'Beep_Counter' and to
issue a 'NOSOUND' when the counter has reached 0 (zero). 'Clock_ISR'
is installed by the routine 'Get_Clock_Tick' which is called by
'Select_Format_File' during the initialization of SCL. It is
deinstalled (the pointers in the BIOS Interrupt Vector Table are
restored to their original values) by either 'Close_Formats' or, in
case of an error, by 'Fatal_SCL_Error'.
The Data Communications Hardware Interrupt (Interrupt 0CH)
The Data Communications Hardware Interrupt (Interrupt 0CH)
This interrupt is handled by a SCL Interrupt Service routine in case
your program involves data communications.
It is a Hardware Interrupt signalling several conditions on the
asynchronous communications port (COM1:). SCL uses this interrupt in
its 'Low Level' data communication system to recognize if a character
has been received on the RS232 interface and to read this character
into its receive buffer. For further information on SCL's Data
communications routines please refer to Appendix B.
Note: Do not call a Interrupt Service Routine directly from your
Note:
program because it could hang the system and make a reboot necessary.
The same applies for the ISR installation and deinstallation
routines.
Appendix A, SCL system details page 218
Appendix A, SCL system details page 218
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
Background Processing Tasks
Background Processing Tasks
SCL provides two 'userhooks' for background processing tasks, one
referred to as 'Low Priority' and the other as 'High Priority'.
SCL provides these 'userhooks' in form of two pointer-variables,
'LP_Background_Pointer' and 'HP_Background_Pointer'.
The Procedures these pointers point to are performed by SCL as
Background Tasks.
If SCL is initialized, both pointers point to dummy procedures within
SCL which only contain a begin-end statement.
These pointers can be redirected by you to point to any other
procedure which is subsequently performed as background task by SCL.
You can basically specify any procedure as a background task as long
as you follow a few rules:
The procedure may not contain any statements which could cause to
wait it on an event, like for example 'keypressed'.
A Background Procedure must be compiled with the 'Force far calls'
option active ( {$F+} ).
Both Background Tasks are being called from within the SCL procedure
'Handle_Format'. 'Handle_Format' is event driven. This means that a
loop containing several conditional statements is continuously
executed and whenever one of the these conditions becomes TRUE the
appropriate task is performed. In addition to the background
procedures, the other tasks are reading the keyboard if a key is
pressed, processing an input character and updating field attributes.
The logic within this loop is as follows:
1. Start
2. Perform the High Priority background task (unconditionally,
once per loop).
3. If a key is pressed then read it into the keyboard buffer
otherwise,
4. If a character is still being processed then carry on
processing it (processing a single character takes between
2 and 4 loops depending on its type)
otherwise,
5. If the keyboard buffer is not empty then fetch the next
character
otherwise,
Appendix A, SCL system details page 219
Appendix A, SCL system details page 219
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
6. Perform the Low Priority Background Task and, if a field
attribute needs to be updated then update it.
7. Go to Start.
As you can see, the High Priority Background Task is executed
unconditionally in every loop and the Low Priority Background Task is
executed only in case no keyboard input is waiting to be processed.
Due to the dynamic nature of such a loop, no exact figures can be
given on how often the Background Tasks are executed. As a rule of
Background Tasks
thumb, on a plain PC (4.77 Mhz) HP_Background_Task is executed about
1300 times per second and in a fast AT as much as 10000 times per
second (assuming that the processing time required for the background
task itself is negligible). The figures for Low Priority Background
Tasks are roughly the same if the system is idle (typically most of
the time) but can dramatically drop at times of heavy activity.
There are certain rules you should follow if you use Background
processing in order to avoid slowing down a program:
1. Split any task into as many subtasks as possible, for example,
if you want to write output to a printer, write one character at
a time rather than the whole line.
2. Exit the Background Task procedure as quick as possible if no
work has to be performed (Preferably use the 'Exit' statement).
3. Use High Priority Background tasks only when you have to. Most
jobs can well be accomodated with Low Priority.
4. Don't use any statements in a background procedure which wait on
an event like 'Repeat until keypressed' or 'Delay(n)'.
5. If you use a High Priority Background Task, its execution time
should typically not exceed a few milliseconds, otherwise you
may slow down your program dramatically.
The following is a short example intended to give you an idea how
to use 'Background Tasks'.
Further examples can be found in some of the 'Sample' programs,
namely SAMPLE4.PAS, SAMPLE5.PAS and SAMPLE7.PAS.
Appendix A, SCL system details page 220
Appendix A, SCL system details page 220
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
Program EXAMPLE;
uses Printer,SCL;
{$F+} {Force far calls}
Procedure My_Background_Task; {prints asterixes on printer while}
begin; {format is being handled}
write(lst,'*');
end;
{$F-} {reset far calls}
Procedure do_format;
begin;
select_format('main');
display_format(0,0);
repeat
handle_format;
until format_done;
end;
begin;
select_format_file('myformats');
lp_background_pointer:[email protected]_Background_Task; {assigns it as LP }
Do_Format; { background task}
Close_formats;
end;
Appendix A, SCL system details page 221
Appendix A, SCL system details page 221
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
READING AND WRITING FIELDS
READING AND WRITING FIELDS
For a better comprehension of the mechanisms that govern the
handling of formats the following scenario will be used as working
platform:
1. Select format A and display it on the screen.
2. Select format B and display it on top of format A.
3. Exit format B restoring format A in its integrity on the
screen.
4. Exit format A
5. Select format C and display it on the screen.
6. Exit format C.
For each step a status of the various pointers is given along with
any relevant annotation.
Select_Format_file('thisfile'); ** STEP 1 **
** STEP 1 **
The format stack is still empty and all S_Ptr, R_Ptr, W_Ptr do not
point yet to any valid format. In other words no field can be
accessed, whether read or written at this point in time.
Select_Format('A');
Format 'A' is loaded into record 1 of the format stack. Both S_Ptr
and W_Ptr point to this record and take 1 for value. From now on it
is possible to write to format 'A'. However read of format 'A' is
still not possible since R_Ptr does not point yet to a valid format.
Display_format(0,0);
This statement does not affect the value of the pointers.
Repeat
Handle_Format;
This is where R_Ptr is adjusted making a read from format 'A'
possible. All three pointers are now pointing to format 'A' and have
a value of 1.
Select_Format('B'); ** STEP 2 **
** STEP 2 **
A second format is now selected coexisting with format 'A' which
remains on the stack with entry number 1 while format 'B' is loaded
to the top of the stack assigned to record number 2. As a result both
W_Ptr and S_Ptr point to format 'B' and have 2 for value while R_Ptr
is still looking at format 'A' with its value remaining unchanged
(1). For this reason the construct W_Cont(5,G_Cont(4)); is
interpreted as read the content of field 4 of format 'A' and place it
into field 5 of format 'B'. By manually altering the W_Ptr value (ie.
'W_Ptr:=1') it is still possible to write to format 'A' should you
fancy it.
Display_format(0,0);
Pointers keep their previous value.
Repeat
Handle_Format;
All three pointers are now pointing to format 'B'.
UNTIL Format_Done; ** STEP 3 **
** STEP 3 **
This statement finishes format 'B' letting SCL restoring format
'A'and implicitly having both S_Ptr and W_Ptr point to format 'A'
with a value of 1 again. R_Ptr however is still pointing to format
Appendix A, SCL system details page 222
Appendix A, SCL system details page 222
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
'B' keeping its value unchanged (2). The construct
'W_Cont(5,G_Cont(4)); would now mean: read the content of field 4 of
format 'B' and place it into field 5 of format 'A'.
UNTIL Format_Done; ** STEP 4 **
** STEP 4 **
This finishes format 'A' and both W_Ptr and S_Ptr do not any longer
point to a valid format and have 0 for value. The R_Ptr however still
point to format 'A'. The construct 'WrkStr:=G_Cont(5) would then read
the content of field 5 on format 'A' into WrkStr. Although both
formats are now finished, this does not mean that they were destroyed
but still remain in the stack. For that matter a manual manipulation
of R_Ptr is genuinely possible and effective (ie. 'R_Ptr:= 2'; to
point to format 'B'.
Select_Format('C'); ** STEP 5 **
** STEP 5 **
This loads format 'C' to record 1 of the format stack physically
overwriting format 'A' previously sitting there. Both S_Ptr and W_Ptr
point to format 'C' taking 1 for value while R_Ptr does not point to
any format any longer and becomes 0.
Display_format(0,0);
The pointers are not affected.
Repeat
Handle_Format;
Now all three pointers point to format 'C' and have a value of 1.
UNTIL Format_Done; ** STEP 6 **
** STEP 6 **
At this moment both S_Ptr and W_Ptr no longer point to a valid stack
record and have the value 0. R_Ptr however still points to format 'C'
and keep its value of 1. The stack itself has format 'C' in record 1
and format 'B' in record 2. Any subsequent format would load on top
of format 'C'.
As seen in this scenario, unfinished formats always remain in the
stack while finished formats stay in the stack until they are
overwritten by new formats. While a format is still in the stack, its
content can always be accessed by manual modification of the
appropriate pointer to the desired record number.
Appendix A, SCL system details page 223
Appendix A, SCL system details page 223
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
SCL Input Character Processing
SCL Input Character Processing
All Input Character processing in SCL is done by 'Handle_Format'. The
sequence of events is as follows:
1. Read a Character from the Input Buffer into 'Char_Code'. Then go
to 2.
2. If Char_Code is specified as a User function Key in this format
User function Key
or if Char Check is specified for the active field then set
Char Check
'User_Function' to TRUE and exit 'Handle_Format' and go to 3
upon return; otherwise go directly to 3.
3. If 'Glb_Err' > 0 or char_Code = NoOp then discard Char_code and
go to 1; otherwise if Char_Code is invalid then perform the
input error routine and then go to 1; otherwise go to 4.
4. If this character is to be displayed, display it and then go to
1; otherwise go to 5.
5. If Char_Code is a 'Help' key then perform the appropriate Help
routine and then go to 1; otherwise go to 6.
6. If Char_Code terminates the current field then perform the
internal validity check as specified for this field. In case of
failure perform the error routine, discard the character and go
to 1; otherwise set 'End_of_Field' to TRUE, exit 'Handle_Format'
and go to 7 upon return.
7. If Glb_Err > 0 then perform the error routine, discard the
character and go to 1; otherwise, if char_Code = NoOp then go to
1; otherwise terminate the field and go to 8.
8. If this character terminates the format as well then go to 10
otherwise go to 9.
9. Determine the next field and initialize it (make it the 'Active
Field'). Then set 'Begin_of_Field' to TRUE and exit
'Handle_Format. Upon return go to 1.
10. Perform the internal format end check (all mandatory fields
filled in). If this fails, perform the error routine, discard
the input character and go to 1; otherwise set 'End_of_Format'
to TRUE and exit 'Handle_Format'. Upon return go to 11.
11. If 'Glb_Err' > 0 then perform the error routine, discard the
input character and go to 1; otherwise if Char_Code = NoOp then
go to 1; otherwise terminate the format.
Appendix A, SCL system details page 224
Appendix A, SCL system details page 224
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
The Error Message File
The Error Message File
The file
SFD. It is a simple ASCII text file and can be modified with most
word processors (or Turbo Pascal, for example). The first 21 records
and records 36 to 39 are occupied by SCL internal error messages, all
other records are available for your own use.
You find a 'virgin' errorfile only containing the SCL internal error
messages on your distribution disks under the name 'SCL.ERR'. The
contents of SCL.ERR is also listed in Appendix B. You can simply copy
this file to
required. The records may contain any text and are not bound to a
special format. The only limitation is that their maximum length may
not exceed 70 characters.
On top of SCL internal error messages, this file can be used to store
your own error messages as well as any other strings you may require
in your program.
All you have to do to display a specific message in the event of an
error occuring while processing a format is to set 'Glb_Err' to the
appropriate record number.
If you just want to access a string stored in the error file you can
use the SCL function 'Sys_Msg'.
Since during execution of an SCL program, all records of this file
are stored in the heap memory, access to them is very fast. Please
note that an error file is optional for an SCL program. If it is not
found during the initialization of SCL, the appropriate record spaces
in the heap are initialized with just their corresponding record
number which will then be displayed should an error be found.
Example:
Example:
Select_Format('X');
W_Cont(2,Sys_Msg(18)); {writes content of record 23 to field 2}
Display_Format(0,0);
REPEAT
Handle_Format;
IF End_of_Format THEN
IF not (G_CONT(1) in ['A'..'D','a'..'d']) THEN
Glb_Err:=43; {SCL will execute its error routine and}
{display the string stored in record 43 in}
{the error message field, the attempt to}
{terminate the format will be refused} UNTIL Format_Done;
Note: See also Programming sample 4, 'Tricks & Tips' and 'System
Note:
Resource considerations'.
Appendix A, SCL system details page 225
Appendix A, SCL system details page 225
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
SCL - System Resource Considerations
SCL - System Resource Considerations
Disk Access
Disk Access
SCL reads its formats from disk. This process can be speeded up
considerably by including a 'BUFFERS=NNN' statement into the
CONFIG.SYS file. It is recommended to set the number of buffers to at
least 20 on computers running SCL programs.
Another effective way is the use of a RamDisk or, preferably, a Disk
Cache Software (for example 'Lightning' from PCSG Inc).
Processor Requirements
Processor Requirements
SCL performs well on any compatible PC system. Due to a highly
optimized program layout, the speed differences to be expected
between a 8088 and a 80286 based system are relatively small if
compared with some other programs. The performance of an 8088 System
running an SCL program can be increased considerably by exchanging
the 8088 processor against a NEC V20. The V20 features, beside being
fully compatible with the 8088, a highly optimized string handling
which results in about 20 % performance improvement if used with SCL
programs.
Format File -Disk Space Requirements
Format File -Disk Space Requirements
The format file occupies 4608 bytes per format.
This means that a 360 KB Floppy can hold a format file with up to 79
formats. The other SCL files are relatively small and typically only
take up a few kilobytes all together.
SCL Code Space Requirements
SCL Code Space Requirements
SCL takes up about 15 to 35 KB of space in the code segment
(Dependent on the number of SCL routines you use).
SCL Data Space Requirements
SCL Data Space Requirements
SCL stores most if its informations in the Heap, therefore the actual
space required in the data segment is relatively small. It depends
largely on whether Datacom is used or not and is typically between
3.5 KB (no datacom) and around 10 KB if datacom is used.
Within the heap memory, the static space required by SCL is about
12 KB plus the size of the file "
In addition to the static space, SCL`dynamically allocates during
program runtime 4.6 KB for every format required to be stacked (refer
to SCL Details for more informations on the format stacking
mechanism).
Appendix A, SCL system details page 226
Appendix A, SCL system details page 226
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
The heap shares its space with the program stack.
There is no exact way to predict the size of the stack required for a
program. It largely depends on the program's logical structure,
especially if recursive routines are used.
The only way to find it out is by 'trial and error', i.e by
decreasing it until the program does not run anymore.
Total Memory Requirements
Total Memory Requirements
Example1: A small SCL program with about 5 to 10 screen formats, no
Example1:
datacom and 100 field input messages. Format stacking is assumed to
occur to up to 3 levels, i.e max 3 unfinished formats can be on the
stack while a fourth one is being processed.
Example2: A very large program with 50 to 100 screen formats, 500
Example2:
field messages, datacom and extensive data space requirements.
Up to 10 formats are assumed to be stacked on the heap. The code and
data requirements quoted represent the maximum values allowed in
Turbo Pascal programs.
The approximate total memory required to run the above two example
programs can be roughly calculated as follows:
Example1 Example2
-----------------------------------------------------------------
Code space (approx) ............................. 50 KB 90 KB
Data space (approx) ............................. 10 KB 64 KB
Program Stack (approx) .......................... 5 KB 40 KB
Heap space (static) ............................. 12 KB 12 KB
Heap space (field messages) ..................... 7 KB 36 KB
Heap space (format stacking) .................... 14 KB 46 KB
Static space required by DOS (approx) ........... 35 KB 35 KB
-----------------------------------------------------------------
Minimum total memory required to run (approx) .. 133 KB 323 KB
Example 1 could run in a 256 KB system with no problems and would
Example 1
even permit another 90 KB of memory to be used for a Ramdisk or
another memory resident program.
Example 2 could just run on a system with 384 KB of memory.
Example 2
Note: The above figures represent only coarse guidelines assuming
Note:
two typical examples. The exact requirements of a specific program
are influenced by many different factors and may deviate from these
examples quite considerably.
Appendix A, SCL system details page 227
Appendix A, SCL system details page 227
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
Tips & Tricks
Tips & Tricks
Entry of Characters not normally accessible via the keyboard
Entry of Characters not normally accessible via the keyboard
During the design of a format layout it is possible to redefine any
keyboard key to any other character by using SFD's keyboard
redefinition feature. Outside of the Layout Designer, such a feature
does not exist. If you have to enter such a character outside the
layout designer (for example to define a graphic character as a field
delimiter), you can use a BIOS feature: Press the 'ALT' key, hold it
down and key in the ASCII`value of the desired character in decimal,
then release 'ALT'.
This feature works on most 'compatible' machines and you can use it
in many other programs as well.
Blinking Fields
Blinking Fields
In case you use the 'Blink' field attribute set the SCL Constant
'Timer_Intervall' to a very low value. Fast blinking fields are much
easier on the eyes than slow blinking ones. In general, for ergonomic
reasons, try to avoid blinking fields at all whenever possible.
Use of the 'Intensity' field attribute on Color systems
Use of the 'Intensity' field attribute on Color systems
If you use the 'Intensity' attribute together with 'Invert' to mark a
field 'active' careful selection of the field background color can
lead to interesting effects. If you assume for example 'Brown' as the
background color this will lead to 'Yellow' foreground if the field
becomes active.
The 'Selected' Attribute in Menus
The 'Selected' Attribute in Menus
If a format only contains one group of 'Constant fields' like a
typical menu, don't be concerned about any 'Selected' attributes
since this format will instantly be terminated as soon as a field has
been selected and for this reason it would never be visible anyway.
Probably the nicest combination for such a field is to select
'Inverted' for active fields and no attributes at all for 'Selected'.
Appendix A, tips and tricks page 228
Appendix A, tips and tricks page 228
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
Preventing automatic termination of a format
Preventing automatic termination of a format
In some cases it may be desirable to prevent a format from being
automatically terminated after the last field has been filled in. To
achieve this, just add another field (A Constant) after the last
field and ask the user via a message to press 'Return' to end the
format (See Sample5).
Highlighting text on screen formats
Highlighting text on screen formats
You can simply highlight text on a format by declaring this area of
text as an 'output' field, then specify the field as being selected
and choose the appropriate 'Selected' attributes according to the
appearance you desire. If you want to switch the highlighting on and
off while the format is being displayed, just use the 'W_Sel'
construct.
Special Fields
Special Fields
See Programming sample 5 for some suggestions and ideas.
Storing strings in
Storing strings in
It is good practice to store text strings in the error message file
instead of hardcoding them into the program itself. Any text stored
in the error message file can be easily modified without recompiling
the program which makes customization and/or nationalization much
easier.
Any strings stored in the error message file can be accessed using
the function 'Sys_Msg'.
Appendix A, tips and tricks page 229
Appendix A, tips and tricks page 229
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
Using Field Input Messages for Help Screens
Using Field Input Messages for Help Screens
Especially on small formats it is not always possible to display
field input messages. Using a 'User Interrupt Procedure', you can
display these messages in an own format whenever for example 'F2'
(Field Help) is pressed.
This works as follows:
Design a small format with just one 'output' field big enough to hold
the field input message (70 characters long).
Write a procedure similar to the following (assuming you named the
above format 'Msg').
PROCEDURE Msg_Help; {Loads format 'Msg' and displays the Field}
BEGIN; {Msg of the present field in it if F2 is pressed}
IF User_Function_Key and Char_Code = Code_F2 THEN
BEGIN;
WITH Stack[S_Ptr].Field[Active_Field] DO
BEGIN;
IF (Field_Msg_Nr > 0) AND {a msg for this field exists}
(Input_Msg_Nr = 0) AND {no field to display it}
(Field_Help_Screen <= Spaces THEN {none defined}
BEGIN{
Select_Format('Msg');
W_Cont(1,User_Msg(Field_Msg_Nr); {obtain the Msg}
Display_Format(0,0);
REPEAT Handle_Format UNTIL Format_Done;
Char_Code:=Code_Noop;
END;
END;
END;
END;
To use this feature declare the trigger key (here 'F2') as a user
function key in all formats.
Within your program, make a call to 'Msg_Help' in the format handling
loop as follows:
REPEAT
Handle_Format;
Msg_Help;
{other optional interrupt handling statements}
UNTIL Format_Done;
This results in the following:
Whenever the trigger key is pressed and a message is defined for the
current field and if that format does not contain a message field and
no help screen is defined for the current field then the format 'Msg'
is called up displaying the message defined for the current field.
Appendix A, tips and tricks page 230
Appendix A, tips and tricks page 230
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
Using 'Goto_Field'
Using 'Goto_Field'
Sometimes it is desirable to skip one or more fields depending on a
certain entry. For example, let's assume you have a format where you
want to skip fields 5 and 6 if field 4 contains 'N'. This can be
easily realized using 'Goto_Field' as the following example shows.
REPEAT
Handle_Format;
IF end_of_field THEN
BEGIN{
IF (Active_Field = 4) AND G_Cont(4) = 'N' THEN
BEGIN;
Goto_Field(7);
Char_Code:=Code_Noop; {must do this because otherwise}
END; {we would leave field 7 again}
END;
UNTIL Format_Done;
Appendix A, tips and tricks page 231
Appendix A, tips and tricks page 231
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
Appendix B
Appendix B
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
This Page is intentionally left blank
Appendix B, SCL procedures & functions page 233
Appendix B, SCL procedures & functions page 233
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
Alphabethic List of all User accessible SCL Procedures & Functions
Alphabethic List of all User accessible SCL Procedures & Functions
Explanation of symbols used.
Explanation of symbols used.
+ Full explanation in the SCL part of this manual.
+ Full explanation in the SCL part of this manual.
* Usage possible. See text.
* Usage possible. See text.
/ Usage possible but restricted. See text.
/ Usage possible but restricted. See text.
F Function
F Function
P Procedure
P Procedure
+ P Beep;
+ P Blank_Format;
+ F Capital(Wrkstr: String): String;
+ F Charstring(Whatchar:CHAR;Len:INTEGER):String;
+ P Check_Date(VAR Date_Str:String10;VAR Y,M,D:WORD);
+ P Check_Time(VAR Time_Str:String10;VAR H,M,S:WORD);
+ P Clear_Rx_Buffer;
+ P Close_Dc;
+ P Close_Formats;
+ F Cts:BOOLEAN;
* P Cursor(Top,Bottom:byte); Sets cursor shape
* P Cursor_off; Makes Cursor invisible
+ P C_Cont(Fieldnr:INTEGER);
+ F Date:String10;
+ F Date_String(Y,M,D:WORD):String10;
* P DC(X,Y,Charcode:Byte); Writes Charcode at screen pos X,Y.
* P Dc_Break; Sends a 'Break' onto the datacom line.
+ P Dc_Diagnose(On:BOOLEAN);
+ P Dc_Write(Code:Byte;VAR Ok:BOOLEAN);
+ P Disable_Port;
+ P Display_Format(Xoffset,Yoffset:INTEGER);
+ P DosExecute:String128);
* P Draw_Char(Charcode:Byte);
Writes Charcode at current pos on screen.
+ F Dsr:BOOLEAN;
+ P Enable_Port;
+ F Environment(Env_Name:String128):String128;
+ P Execute(Progstring:String128);
+ F Exist(Fn : String80):BOOLEAN;
* P Fatal_Scl_Error(Errornr:INTEGER);
Displays error msg and halts SCL. Dont use Errornr < 4,
these are for internal use only.
+ P Finish_Format(Check:BOOLEAN);
+ F Format_Done:BOOLEAN;
Appendix B, SCL procedures & functions page 234
Appendix B, SCL procedures & functions page 234
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
* F Format_Name:string80; Returns the name of the active format
+ P Frontstring(STR:String;VAR Head,Tail:String);
* P Ftab(VAR Wrkstr:String;Fill_Char:CHAR;
Just:Position;Len:INTEGER);
Justifies Wrkstr in a field of length Len according to Just.
All blanks are replaced by Fill_Char. See declaration of type
Position.
/ F Get_Att(X,Y:INTEGER):Byte;
Returns video attribute of position X,Y. X=1..80, Y=1..25.
* P Get_Country;
Updates Country dependant Info. If SCL_Country > 0 then Info
is updated accordingly, otherwise according to CONFIG.SYS.
+ P Get_Dc_Status(VAR Status:INTEGER);
/ P Get_Next_Char(VAR Charnumber:INTEGER ; VAR Inputchar:CHAR);
Waits until a key is pressed and returns Code and Image of
the key. Code is SCL notation. Don't use together with
background processing (you're stuck until a key is pressed).
* P Get_Screen_Mode;
Sets the variables Screen_Mode, Mono_Adapter and Color_True
according to the current screen mode used.
+ P Goto_Field(Fn:INTEGER);
+ F G_Cont(Fn:INTEGER):String80;
+ F G_Sel(Fn:INTEGER):BOOLEAN;
+ P Handle_Format;
+ P Hp_Background_Task; FORWARD;
* P Input_Error(Msgnr:INTEGER);
Displays error msg in Err msg Field and beeps.
+ F Julian_Date(VAR Y,M,D:WORD):REAL;
+ F Justify_Center(STR:String;Len:INTEGER):String;
+ F Justify_Left(STR:String;Len:INTEGER):String;
+ F Justify_Right(STR:String;Len:INTEGER):String;
/ F Next_Char(VAR Esc:BOOLEAN):CHAR;
Waits until a key is pressed and returns ASCII Code. If key
generated a two byte code then 'Esc' is true. See
'Get_Next_Char' for restrictions.
+ P Normal_Date(Julian:REAL;VAR Y,M,D:WORD);
+ F Nr(St:String80):INTEGER;
+ P Open_Dc(VAR Result:INTEGER);
/ P Paint_Format_Frame(Color:Byte);
Changes video attr. of first and last row and column of current
format to color. S_Ptr must be valid ( > 0).
+ F Power(Mantissa,Exponent:REAL):REAL;
+ P Receive_Char(VAR Code:INTEGER;VAR Ok:BOOLEAN);
+ F Ri:BOOLEAN;
+ F Rnr(s:string80):real;
+ F Rst(r:Real;Decimals:integer):string;
* F Rtime:REAL;
Returns current time in hundreds of seconds since midnight.
Appendix B, SCL procedures & functions page 235
Appendix B, SCL procedures & functions page 235
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
+ P R_Cont(Fieldnr:INTEGER;VAR Contents:String80);
+ P R_Sel(Fieldnr:INTEGER; VAR Sel:BOOLEAN);
+ P Select_Format(Fname:String10);
+ P Select_Format_File(Filename:String10);
+ PSend_Buffer(VARTx_Buff;Buff_Start,Buff_Length,Bcc_add
:INTEGER;
+ P Send_Char(Code:Byte;var Ok:BOOLEAN);
+ P Send_String(Data:String255;VAR Ok:BOOLEAN);
/ P Set_Att(X,Y:INTEGER;Color:Byte);
Changes the video attribute at X,Y to color. X = 1..80,
Y = 1..25.
+ P Set_Dc_Params;
+ P Set_Dtr(On:BOOLEAN);
/ P Set_Edit_Mode(Yes:BOOLEAN);
Sets or resets edit mode. Make sure that Active_Field > 0.
/ P Set_Field_Color(Fieldnr:INTEGER;Color:Byte);
Changes video attributes of current field to color. Fieldnr
must be valid.
/ P Set_Mx(Value:INTEGER);
Move Cursor to Column = Value. Conflicts with SCL likely.
/ P Set_My(Value:INTEGER);
Move Cursor to Row = Value. Conflicts with SCL likely.
+ P Set_Rts(On:BOOLEAN);
/ P Set_Screen_Color(Color:Byte);
Changes the complete screen to color (incl all fields).
+ F St(I:INTEGER):String80;
+ P Strip(VAR Wrkstr:String;VAR Len:INTEGER);
+ F Stripleft(Wrkstr: String): String;
+ F Stripright(Wrkstr: String): String;
+ F Sys_Msg(Nr:INTEGER):String80;
+ F Time(Seconds:BOOLEAN):String10;
+ F Time_String(H,M,S:WORD):String10;
+ F Tx_Ok:BOOLEAN;
+ F Weekday(Y,M,D:WORD):INTEGER;
+ P W_Cont(Fieldnr:INTEGER;Cont:String80);
/ P W_Crt(Fieldnr:INTEGER;Msg:String80);
Writes Msg to the specified field. Does not change/Update
Format content (Screen only). S_Ptr must be valid (>0).
+ P W_Sel(Fieldnr:INTEGER;Sel:BOOLEAN);
+ F X_Max:INTEGER;
+ F Y_Max:INTEGER;
Appendix B, SCL procedures & functions page 236
Appendix B, SCL procedures & functions page 236
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
Datacom Control Characters
Datacom Control Characters
CONST
Nul = $0;
Soh = $1;
Stx = $2;
Etx = $3;
Eot = $4;
Enq = $5;
Ack = $6;
Bel = $7;
Con = $7;
Bs = $8;
Ht = $9;
Lf = $a;
Vt = $b;
Ff = $c;
Cr = $d;
S0 = $e;
S1 = $f;
Dle = $10;
Dc1 = $11;
Dc2 = $12;
Dc3 = $13;
Dc4 = $14;
Nak = $15;
Syn = $16;
Etb = $17;
Can = $18;
Em = $19;
Sub = $1a;
Esc = $1b;
Fs = $1c;
Gs = $1d;
Rs = $1e;
Us = $1f;
Pol = $70;
Sel = $71;
Fsl = $73;
Bsl = $74;
Del = $7f;
Appendix B, SCL procedures & functions page 237
Appendix B, SCL procedures & functions page 237
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
Field Attributes and Colors
Field Attributes and Colors
___________________________
Possible Field Attributes:
Possible Field Attributes:
-------- Monochrome ----------
Normal Active Selected Active (Color)-----
-----------------------------------------------------------
Inverted N Y Y Y
Intensity Y Y Y Y
Underlined N Y Y N
Marked N Y 1) Y N
Blink N Y N Y
1) The marks blink if used as an attribute for 'Active'.
Note: Multiple choices of the above attributes are possible. Refer
Note:
to the SFD part of the manual for restrictions applying to certain
combinations of attributes.
'Normal' and 'Selected' on color systems are specified by any valid
Foreground/Background color combination according to the table below.
Colors. (Systems with color graphics adapter).
Colors. (Systems with color graphics adapter).
Background Foreground
---------------------------------------
Black Y Y
Blue Y Y
Green Y Y
Cyan Y Y
Red Y Y
Magenta Y Y
Brown Y Y
Light grey Y Y
Dark Grey N Y
Light Blue N Y
Light Green N Y
Light Cyan N Y
Light Red N Y
Light Magenta N Y
Yellow N Y
White N Y
Appendix B, SCL procedures & functions page 238
Appendix B, SCL procedures & functions page 238
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
Functions in SCL Programs
Functions in SCL Programs
_________________________
Right : 1. In Travel Mode : Next Field.
Travel Mode
2. In Entry Mode : Next Character.
Entry Mode
Left : 1. In Travel Mode : Previous Field.
Travel Mode
2. In Entry Mode : Previous Character.
Entry Mode
Down : First field on next line.
Up : Last field on previous line.
Home : First field in line.
End : Last field in line.
PgDn : Last field on format.
PgUp : First field on format.
Tab : Next field.
ShiftTab : Previous field.
Backspace : Delete character left of cursor.
Insert : Insert a space at the cursor position.
Delete : Delete character under cursor.
Return : 1. Entry mode.
2. Finish field and advance to next field (if
already in the last field, finish the format).
3. Toggle Selected Status of a Constant.
Selected
Escape : Finish Format.
F1 : Format related Help information.
F2 : Field related Help information.
F3 : UNDO. Restores field to previous content.
F10 : Abort current activity (not valid with every format).
Appendix B, SCL procedures & functions page 239
Appendix B, SCL procedures & functions page 239
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
Standard SCL Error Messages
Standard SCL Error Messages
___________________________
<1> Format File not found
<2> Not enough Memory to run
<3> This program requires 80 column screen
<4> Format does not fit at specified location
<5> Format not found
<6> Insufficient Mem in Heap for screen
<7> Runtime or I/O error while SCL was running
<8> Format file not sorted or integrity error
<9> Attempt to read field while format read pointer is zero
<10> Attempt to read from invalid fieldnumber
<11> Break key pressed
<12> Attempt to write to field while format write pointer is zero
<13> Attempt to write to invalid field number
<14> Invalid path specified
<15> Invalid Key Pressed
<16> Warning: End of Field
<17> Format has only one Field
<18> Input mandatory
<19> Numeric Data expected
<20> Value entered too small
<21> Value entered too big
<22>
<23>
<24>
<25>
<26>
<27>
<28>
<29>
<30>
<31>
<32>
<33>
<34>
<35>
<36> Integer number expected
<37> Helpfile not available
<38> This Helpfunction not available
<39> Autohelp-Format not found
<40>
Appendix B, SCL procedures & functions page 240
Appendix B, SCL procedures & functions page 240
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
The Shareware Idea
The Shareware Idea
Shareware (sometimes called User supported Software or
freeware) attempts to provide useful programs to the PC community at
low cost by reducing the dependence on conventional marketing
channels.
Several software developers have proven that the concept works, to
the mutual benefit of the independent program authors and the PC
community itself.
The user benefits by the availability of low cost software which he
can evaluate on his own system before making the decision to purchase
it. The author benefits by being able to enter the software market
without extensive monetary risks. The user community determines
which products succeed based on their true utility, rather than on
their marketing achievements.
Appendix B, OASIS products page 241
Appendix B, OASIS products page 241
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
OASIS Products & Licencing Terms
OASIS Products & Licencing Terms
The following products will be available from EUREKA SOFTWARE
ASSOCIATES:
- OASIS Demo package
- OASIS Evaluation software
- OASIS
OASIS Demo package
OASIS Demo package
__________________
Description
Description
This package as its name indicates is only to be used for
demonstration purposes. It is ment to give you a taste of what you
can achieve with OASIS. Each demo application comes with the source
code and the associated documentation commenting each procedure. This
package does not require you to register, feel free to copy and
distribute this package and use some of its handy utilities.
Distribution
Distribution
- Download
- Mail order
Pricing (No registration required)
Pricing
- Download no charge
- Mail order $10
includes disk & hard copy
Appendix B, OASIS products page 242
Appendix B, OASIS products page 242
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
OASIS Evaluation (This package)
OASIS Evaluation
________________
Description
Description
This package is the evaluation version of OASIS. It offers almost all
OASIS features and formats (screens) created with the evaluation
version are entirely compatible with full blown version of OASIS. The
limitation of this version resides in the number of formats (screens)
you can handle in any single file, the limit is set to 20 for OASIS
Evaluation. This mean you can still create an application that
requires up to 20 screens, for more complexe applications with more
screens you need the full version of OASIS.
Distribution
Distribution
- Download
- Mail order
Licencing Terms
Licencing Terms
OASIS Evaluation is NOT public domain software, it is a copyrighted
product distributed by EUREKA SOFTWARE ASSOCIATES. You are hereby
granted a limited license to use OASIS, and to copy it and further
distribute it, under the following conditions:
1) No fee other than the cost of media and copying (max $10 per copy)
may be charged for such copying and distribution, otherwise
permission of EUREKA SOFTWARE ASSOCIATES is required.
2) OASIS Evaluation may ONLY be distributed in its original state,
complete and without any modifications or changes to the program
itself or to any of its data files.
3) Use without registration must be limited to a reasonable time (no
more than 14 days) and for test and evaluation purposes only, after
which it must be registered in accordance with the following terms.
Appendix B, OASIS products page 243
Appendix B, OASIS products page 243
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
Commercial use:
______________
If OASIS Evaluation Software is used in a commercial & institutional
environment users must register under the 'Commercial Users Licence
Agreement' scheme. Any use of OASIS Evaluation beyond the trial
period is a copyright violation.
Conditions:
Within the terms of this agreement, a corporation, company,
institution, organization, or individual can use OASIS Evaluation to
produce programs for commercial purposes subject to the following
conditions:
1. This license applies to the OASIS Evaluation software as
described in this manual and its documentation.
2. You must treat this software just like a book ONLY ONE CPU PER
LICENSE can use the software at the same time in the original or
modified forms. However, you are authorized to make archival
copies for safekeeping.
3. You may produce any number of executable code programs for
profit for world-wide distribution with this software without
royalties to the author.
4. The license applies to the original copy of this software as
well as to updated versions which may become available. There is
no further charge for using the updated versions. The author is
neither obligated to provide updated versions nor notices of
error corrections. The author is not obligated to provide any
services of any kind to support OASIS Evaluation .
6. The user agrees to conscientiously respect the copyright to the
author of the code and not to illegally, unethically, or
neglectfully exploit the services provided by the author.
7. This code is provided "as is" without warranty of any kind,
either expressed or implied, included but not limited to the
implied warranty of merchantability and fitness for a specific
purpose. The entire risk as to the quality and performance of
the coding is with you. Should the code prove defective, you
assume the entire cost of all necessary servicing, repair or
correction.
8. In no event will the author be liable to you for any damages,
including any lost profits, lost savings or other incidental or
consequential damages arising out of the use or inability to use
this code.
9. The User acknowledges having read this agreement and the License
Statement, understands them, and agrees to be bound by their
terms and conditions.
Appendix B, OASIS products page 244
Appendix B, OASIS products page 244
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
Private (non-profit) use:
________________________
If OASIS Evaluation is used privately only and not for profit making
purposes, please register under the private user licence agreement
scheme.
The applicable terms are, apart from point 3, identical to the ones
listed above.
Pricing
Pricing
Registration
Registration $40
does not include disk or manual
Private Licence
Private Licence
includes registration, distribution disks $60
& reference manual on disk
includes registration, distribution disks $80
& with hard copy manual
Commercial Users Licence
Commercial Users Licence
includes registration, distibution disks $120
& hard copy manual.
Appendix B, OASIS products page 245
Appendix B, OASIS products page 245
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
OASIS
OASIS
_____
Description
Description
Identical to OASIS Evaluation but no limit to the number of format
per file.
Distribution
Distribution
- Mail order
Note: Application available, Documentation draft version
approx. 250 pages.
Licensing terms
Licensing terms
- Same as OASIS Evaluation Commercial use.
Pricing
Pricing
- includes registration, distibution disks $199
& hard copy manual.
Appendix B, OASIS products page 246
Appendix B, OASIS products page 246
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
------------------------
| Invoice & Order Form |
Invoice & Order Form
------------------------
=================================================================
" O R D E R F O R M "
O R D E R F O R M
"==============================================================="
" Date: __ / __ / __ PO#: ______________ "
"---------------------------------------------------------------"
" Qty Description $/unit "
"---------------------------------------------------------------"
" | | | "
" __ |OASIS Demo package mail order * | $10.00 |___.__ "
" | | | "
" __ |OASIS Evaluation Registration | $40.00 |___.__ "
" |(does not include disk) | | "
" | | | "
" __ |OASIS Evaluation Private Licence * | $60.00 |___.__ "
" |(registration, disks, manual on disk) | | "
" | | | "
" __ |OASIS Evaluation Private Licence ** | $80.00 |___.__ "
" |(registration, disks and manual) | | "
" | | | "
" __ |OASIS Evaluation Commercial User Licence|$120.00 |___.__ "
" |(registration, disks and manual) ** | | "
" | | | "
" __ |OASIS Commercial User Licence ** |$199.00 |___.__ "
" |(registration, disks and manual) | | "
" | | | "
"==============================================================="
" Michigan residents add 4% sales tax Subtotal: $____.__ "
" Shipping per order Shipping: $____.__ "
" * US $3 first copy, $1 other copies Tax: $____.__ "
" ** US $3 first copy, $2 other copies Total: $____.__ "
Total
"---------------------------------------------------------------"
" Method of Payment: ( ) Check ( ) Money Order "
" "
" Make check payable to: EUREKA SOFTWARE ASSOCIATES "
EUREKA SOFTWARE ASSOCIATES
" 2344 Yorkshire "
" Ann Arbor, MI 48104 "
" USA "
" "
" For orders outside the U.S. please send check drawn on U.S. "
" bank in U.S. dollars, or international money order in U.S. "
" dollars. "
"==============================================================="
" Name: ________________________________________________ "
" Address: ________________________________________________ "
" ________________________________________________ "
" City: ______________________ State: __ Zip: _____ "
" "
=================================================================
Appendix B, OASIS products page 247
Appendix B, OASIS products page 247
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
------------------------
| Invoice & Order Form |
Invoice & Order Form
------------------------
=================================================================
" I N V O I C E "
I N V O I C E
"==============================================================="
" Date: __ / __ / __ PO#: ______________ "
"---------------------------------------------------------------"
" Qty Description $/unit "
"---------------------------------------------------------------"
" | | | "
" __ |OASIS Demo package mail order | $10.00 |___.__ "
" | | | "
" __ |OASIS Evaluation Registration | $40.00 |___.__ "
" |(does not include disk) | | "
" | | | "
" __ |OASIS Evaluation Private Licence | $60.00 |___.__ "
" |(registration, disks & manual on disk) | | "
" | | | "
" __ |OASIS Evaluation Private Licence | $80.00 |___.__ "
" |(registration, disks and manual) | | "
" | | | "
" __ |OASIS Evaluation Commercial User Licence|$120.00 |___.__ "
" |(registration, disks and manual) | | "
" | | | "
" __ |OASIS Commercial User Licence |$199.00 |___.__ "
" |(registration, disks and manual) | | "
" | | | "
"==============================================================="
" Remit to: Subtotal: $____.__ "
" EUREKA SOFTWARE ASSOCIATES Shipping: $____.__ "
" 2344 Yorkshire Tax: $____.__ "
" Ann Arbor, MI 48104 USA Total: $____.__ "
Total
"==============================================================="
" SOLD TO: "
" "
" Name: ________________________________________________ "
" Address: ________________________________________________ "
" ________________________________________________ "
" City: ______________________ State: __ Zip: _____ "
" Country: ______________________ "
" "
"---------------------------------------------------------------"
" SHIP TO: "
" "
" Name: ________________________________________________ "
" Address: ________________________________________________ "
" ________________________________________________ "
" City: ______________________ State: __ Zip: _____ "
" Country: ______________________ "
" "
=================================================================
Appendix B, OASIS products page 248
Appendix B, OASIS products page 248
OASIS Evaluation Reference Manual
OASIS Evaluation Reference Manual
Appendix B, OASIS products page 249
Appendix B, OASIS products page 249
December 24, 2017
Add comments