View
4
Download
0
Category
Preview:
Citation preview
Copyright © 1997 by Software Artistry, Inc.
All rights reserved
Tools and Utilities Guide
SA-ApplicationSoftware ExpertVersion 5.0
All rights to this publication are reserved. No part of this manual may be reproduced or transmitted in any formor by any means, electronic or mechanical, including photocopying and recording, for any purpose other than thepurchaser’s personal use without the written permission of Software Artistry, Inc.
SA-Application Software Expert and SA-Expert Advisor are trademarks of Software Artistry, Inc.
IBM, OS/2, DB2/2, and ECCO are registered trademarks of International Business Machines Corp.
Microsoft , Windows, Windows NT, and Windows 95 are registered trademarks of Microsoft Corp.
Oracle, Oracle 7, SQL*DBA, SQL*Net, and SQL*Plus are trademarks of Oracle Corp.
SYBASE, Transact-SQL, and DB-Library are trademarks of Sybase, Inc.
Crystal Reports is a trademark of Crystal Technology, Inc.
Any other products mentioned in this document are trademarks of their respective companies.
About This Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5Purpose of This Book . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6Audience Considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6Overview of the Contents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7Document Conventions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7The SA-ASE 5.0 Documentation Set . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
Chapter 1 The SA-Script IDE . . . . . . . . . . . . . . . . . . . . .11Introduction. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12Programs Used in the IDE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13Working With Project Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14Using Targets in a Project File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16Working With Items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19Editing Items with a Text Editor. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21Building Items. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23Updating Your Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25Building and Updating .KB Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26Running Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
Chapter 2 The SA-Script Debugger . . . . . . . . . . . . . . . . .29Introduction. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30Opening and Closing the SA-Script Debugger. . . . . . . . . . . . . . . . . . . . . 30Code in the SA-Script Debugger . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32Working with Code. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33Tracing Execution Paths in Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36Break Points . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38Debugging Windows and Dialog Boxes. . . . . . . . . . . . . . . . . . . . . . . . . . 39
Chapter 3 The SA-Script Parser. . . . . . . . . . . . . . . . . . . .41Introduction. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42Searching for Source Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42Using The SA-Script Parser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43Command Prompt Arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
Table of Contents
SA-Application Software Expert 5.04
IMPORT Declarations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50Circular Usage in .KB Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51SA-Script Parser Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
Chapter 4 The Interface Generator . . . . . . . . . . . . . . . . . 63Introduction. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64Generating .dfc Files. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64Command Prompt Arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66Interface Generator Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
Chapter 5 The SA-Script Interpreter . . . . . . . . . . . . . . . . 71Introduction. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72Searching for .KB Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72Command Prompt Arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73Interpreter Errors. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76
Chapter 6 The Interface Viewer . . . . . . . . . . . . . . . . . . . 81Introduction. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82Viewing .dfc Files. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
This chapter covers the following topics:
•Purpose of This Book
•Audience Considerations
•Overview of the Contents
•Document Conventions
•The SA-ASE 5.0 Documentation Set
About This Guide
6 SA-Application Software Expert 5.0
Purpose of This Book
What this book contains
The SA-ASE 5.0 Tools and Utilities Guide explains how to use the tools and utilities included with SA-ASE.
What you will be able to do
By using the material in this book, you will be able to:
• Create customized SA-Script applications
• Understand how SA-Script is used to build applications in SA-ASE
Audience Considerations
Who should read this book
This book is intended for users who configure or customize applications at your site, including:
• SA-Script programmers
• System administrators
What you should know before beginning
Before you use this book, you should be familiar with:
• Customization practices at your site, and how your function relates to the customization process
• Knowledge of the operating system used at your site
Overview of the Contents
Tools and Utilities Guide 7
Overview of the Contents
What is in this book
The SA-ASE 5.0 Tools and Utilities Guide contains the following chapters. Primary chapter topics are noted as well.
• Chapter 1, “The ASE IDE,” describes how to use the ASE Integrated Development Environment.
• Chapter 2, “The ASE Debugger,” describes how to use the ASE Debugger to find code errors.
• Chapter 3, “The SA-Script Parser,” describes how to use the SA-Script Parser to build application files.
• Chapter 4, “The Interface Generator,” describes how to use the Interface Generator to build dialog box files.
• Chapter 5, “The SA-Script Interpreter,” describes how to use the SA-Script Interpreter.
• Chapter 6, “The Interface Viewer,” describes how to use the Interface Viewer to view components in an application.
How to use this book
This book is a reference guide to the various tools that developers can use to customize applications that use SA-Script. This book does not refer to specific programming issues, but instead gives a functional view of the tools and their use.
Document Conventions
Introduction Several conventions are used throughout this book to identify different text use or to point out particularly important information.
8 SA-Application Software Expert 5.0
Instructions for Windows, OS/2, and UNIX users
This book contains only one set of instructions for any task that you can perform. Because SA-ASE works in basically the same way in Windows, OS/2, and UNIX, only instructions that differ significantly from one operating system to another are shown separately. Graphics for this guide were created in the Windows 95 operating system.
Text use • Italic text is used in procedures to indicate text that a user must substitute in the course of a procedure:
Type the file name: SAIDEV
• Italic text is also used for new terms:
client/server architecture
• Bold text is used for variable and data source names when they appear in text references:
SQLFetch
• Bold text also denotes text that users must type, either at a command prompt or in a text box.
• Monospace fonts are used for code examples:
Function Add Data : INTEGER IS
Icons used in this book
Icons appear occasionally as a means of emphasizing a particularly important point.
Notes use the format shown below:
Note: This is an example of a note.
Cautions occur at points where user actions might adversely affect data integrity:
Caution: This is an example of a caution.
The SA-ASE 5.0 Documentation Set
Tools and Utilities Guide 9
Product names
The following tables shows the names by which Software Artistry products are referred to in the documentation set.
The SA-ASE 5.0 Documentation Set
Other books in the set
The following books, in addition to the SA-ASE 5.0 Tools and Utilities Guide, comprise the total SA-ASE document set:
•SA-ASE 5.0 Interface Designer Guide - A reference book that describes the Interface Designer. This new tool can be used to create dialog box forms, menus, toolbars, and string tables for any GUI applications that you build.
•SA-ASE 5.0 SA-Script Language Reference - A reference book that provides command references for SA-Script and for the APIs used with SA-Script. The command references include syntax, return codes, and system constants.
• SA-ASE 5.0 SA-Script Programming Guide - A reference book that provides information about SA-ASE and the SA-Script programming language.
•SA-ASE 5.0 Legacy APIs Guide - A reference book that contains information about the EHLLAPI and CPIC APIs used in SA-ASE.
Product Name Referred to as
SA-EXPERTISETM for CRM EXPERTISE
SA-EXPERTISETM for ESM EXPERTISE
SA-Application Software Expert
ASE
SA-Expert Administrator Expert Administrator
SA-Expert Advisor Expert Advisor
SA-Expert Evolution Expert Evolution
SA-Expert Foundation Manager
Expert Foundation Manager
SA-Expert Mail Agent Expert Mail Agent
SA-Expert Quality Expert Quality
SA-Expert Support Expert Support
SA-ExpertView ExpertView
SA-Expert Web Expert Web
10 SA-Application Software Expert 5.0
•SA-ASE 5.0 SA-Script Text Retrieval Guide - A reference book that explains the use of the Fulcrum SearchServer text retrieval engine.
•SA-ASE 5.0 Tutorials - A reference book that contains tutorial exercises for the primary functions found in SA-ASE.
This chapter covers the following topics:
•Introduction
•Programs Used in the IDE
•Working With Project Files
•Using Targets in a Project File
•Working With Items
•Editing Items with a Text Editor
•Building Items
•Updating Your Project
•Building and Updating .KB Files
•Running Files
1The SA-Script IDE
The SA-Script IDE
12 SA-Application Software Expert 5.0
1
Introduction
Purpose of the IDE
The ASE Integrated Development Environment, or IDE, is an integrated work space for writing SA-Script applications. The IDE is designed to allow users to build applications by selecting options in a graphical user interface (GUI) environment rather than working from the command prompt.You can use the IDE to organize SA-Script applications and access the tools you need to build them.
The IDE hierarchy
Within the IDE, all SA-Script applications are organized in a hierarchical structure within a project file. In the IDE, each project is a file made up of one or more windows called targets. Targets contain components called items that are used to build the application.
To build applications, your workflow typically follows the sequence of this hierarchy. The following steps summarize the process for building an SA-Script application project using a hierarchical approach.
Step Description
1 Identify any existing source code files that you want to include in the project file. You may want to set up a directory for these files.
2 Create a new project file.
3 Add targets to your project file.
4 Add items to the targets.
5 Create the source code file for each item, unless it already exists.
Programs Used in the IDE
Tools and Utilities Guide 13
What is a project?
A project is the highest level in the IDE’s hierarchical file structure. A project is a window that shows a list of targets. A project can have one target or many, depending on the complexity of the application you’re building and how you choose to organize it.
What is a target?
A target is a window that is linked to a project. The target window shows a list of items associated with the project. One target can hold all the items for a project, or the items can be grouped into multiple targets, depending on how you want to organize your SA-Script application.
What is an item?
An item is the lowest level in the IDE’s hierarchical file structure. An item is a window that is linked to a target. The item window shows the name of one item associated with a target. One item or multiple items can make up a target. Item names are the full path, including file name, of source files used to build an application. Because files are referenced by path name rather than being physically copied into the IDE, they do not have to be created within the IDE to be included in your project. You can define any file as part of the project in the IDE.
Programs Used in the IDE
Edit programs There are two edit programs: a default text editor and the Interface Designer. The default text editor is used to edit ASCII text files. A default text editor has already been defined for your operating system, however you can change it to a different editor. For more information, see the section “Editing Items with a Text Editor.”
The Interface Designer is used to edit .df files. For more information on using the Interface Designer, see the SA-ASE 5.0 Interface Designer Guide.
The SA-Script IDE
14 SA-Application Software Expert 5.0
1
Build programs
There are two build programs that convert files from a source format to an object format. During the build process, the build program creates a new file with an extension that is derived from the original file extension.
The build program converts the file to machine code and adds a “c” to the file extension. A build for a .kb (knowledgebase) file creates a file with a .kbc extension.
The following example shows the build programs and the type of files each converts.
Run programs The run process runs or displays files, and in doing so, designates the program that runs the selected file. For example, the program i-view.exe is the run program for the .df files.
When a program runs, its base extension is replaced with a specific derived extension to create a new file name. This file name is passed as the command line argument to the run program.
Working With Project Files
Overview This section covers the following topics:
• Creating a new project file
• Opening an existing project file
• Saving a project file
• Closing a project file
Build Program Converts
Interface Generator .df to .dfc
SA-Script Parser .kb to .kbc
Working With Project Files
Tools and Utilities Guide 15
Creating a new project file
When you create a new project file, it is recommended that you create a new, separate directory for your file(s).
To create a new project file:
1. From the SA-Application Software Expert, open the SA-ASE IDE.
2. From the File menu, choose New. Result: The IDE window appears.
At this point, you can set up the targets and items for a project file.
Opening an existing project file
Use this procedure to open an existing project file.
To open an existing project file:
1. Open the IDE, if it is not already open.
2. From the File menu, choose Open.
Result: The Open Project File dialog box appears.
3. From the Open Project File dialog box, select the file name of the project file you want to use.
4. Choose OK.
Result: The project file opens.
Saving a project file
When you name a project file, the default extension is .ide. You may specify any extension, however.
To save a project file with the original file name:
The SA-Script IDE
16 SA-Application Software Expert 5.0
1
• From the File menu, choose Save.
Result: Any new information you added to the project file is now saved to the original file name.
To save a project file to a different name:
1. From the File menu, choose Save As.
Result: A Save As dialog box appears.
2. Specify the path and file name you want to use for the file.
3. Choose OK.
Closing a project file
To close a project file, follow this procedure.
1. From the File menu, choose Close. If any information in the file has not been saved, you are prompted to save it.
2. Respond appropriately, then choose OK.
Result: The project file closes and the empty IDE window reappears.
Using Targets in a Project File
Overview Once you open or create a project file, you can add targets to it. You can create as many targets in a project file as you want, but there must be at least one. You can add any number of items to a target. However, as an organizational tool, each target should hold only items that are part of a logical group of information or files.
This section covers the following topics:
• Adding a target to a project file
• Editing a target name
Using Targets in a Project File
Tools and Utilities Guide 17
• Clearing a target
• Deleting a target from a project file
Adding a target to a project file
Each target holds items that are part of a related group of data used to build an application. Use the following procedure to add a target to a project file.
1. Open the project file you want to use.
2. From the Target menu, choose Add. Result: The Add Target dialog appears.
3. In the Target Title box, type the title of the new target.
Note: This is required. If you do not supply a title, an error message appears stating that a value must be supplied before the target is accepted.
4. Choose OK.
Result: The new target page appears in the IDE window as a tab in a notebook.
Editing a target name
Editing a target allows you to change the target name.
To edit a target:
1. Open the project file you want to use.
2. Activate the target you want to edit by choosing its tab.
The SA-Script IDE
18 SA-Application Software Expert 5.0
1
3. From the Target menu, choose Edit.
Result: The Edit Target dialog box appears.
4. Make any changes to the target title.
5. Choose OK to return to the project file.
Clearing a target
Clearing a target removes all items from it, although the source files are not affected by the clear process.
Caution: You cannot undo the clear process. Once you clear items from a target, the only way to restore them is to either close the project file without saving it or to manually add each item back in to the target.
To clear items from a target, use the following procedure.
1. Activate the target you want to clear items from by choosing its tab.
2. From the Target menu, choose Clear.
Result: A Warning message appears that asks if you want to remove all items from the target.
3. Choose one of the following options.
If you... then...
want to clear the target choose Yes
do not want to clear the target
choose No
Working With Items
Tools and Utilities Guide 19
Deleting a target from a project file
If you delete a target from a project file, all items on that target are also removed from the project file. The source files are not affected by the deletion.
To delete a target:
1. Activate the target you want to delete by choosing its tab.
2. From the Target menu, choose Delete.
Result: A Warning message appears that asks if you want to delete the target.
3. Choose one of the following options.
Working With Items
Overview A target item is a reference to a source file, and can be added to or deleted from its target at any time.
This section covers the following topics:
• Adding an item to a target
• Placeholders
• Removing an item
Adding an item to a target
Before you add items to the targets in a project file, consider the information that follows:
• You cannot move an item to a different target after you add it to a target. If you add an item to the wrong target, you must delete it and then add it to the correct target.
If you then
want to delete the target choose Yes.
do not want to delete the target
choose No.
The SA-Script IDE
20 SA-Application Software Expert 5.0
1
• You may have multiple items in a project that refer to the same source file. However, they must be placed in separate targets.
• An item listed in a target for the project does not have to reside in the same directory as the project file. If the item resides in a different directory, an absolute path is set for the item.
To add an item to a target:
1. Activate the target you want to use by choosing its tab.
2. From the Item menu, choose Add.
Result: The Select File to Add dialog box appears.
3. From the File name list, select the file name of the item you want to add to the target.
4. Choose OK.
Result: The item is added to the current target.
Placeholders As you build project files, you may want to add placeholders for source files that have not yet been created. Placeholders are empty files that allow you to form the structure of your application though you may not have source material. For example, you may want to create files that will eventually become help files for your application, even though you have not created the help text yet.
To create a placeholder:
1. Activate the target you want to use by choosing its tab.
2. From the Item menu, choose Add.
Result: The Select File to Add dialog box appears.
3. In the File name box, type the name of the item you want to add.
Editing Items with a Text Editor
Tools and Utilities Guide 21
4. Choose OK.
Result: The item is added to the current target.
Deleting an item
You may choose to remove an item either because you don’t want it associated with a particular target anymore, or because you need to move it to another target. The only way to move an item is to remove it from its current target and add it to another target.
To remove an item from a target:
1. Select the item you want to remove.
2. From the Item menu, choose Remove. Alternatively, press DELETE.
Result: A Warning message appears that asks if you want to remove the item.
3. Choose one of the following options.
Editing Items with a Text Editor
Overview Editing items in a target allows you to make changes when you build an application. Items can be associated with different text editors, depending on the type of item. For instance, a module of code can be associated with a text editor, while a dialog box file is associated with the Interface Designer.
This section covers the following topics:
• Opening a text editor
• Working with a text editor for an item
If you then
want to delete the item choose Yes.
do not want to delete the item
choose No.
The SA-Script IDE
22 SA-Application Software Expert 5.0
1
• Quitting a text editor
• Changing the default text editor
Opening and Closing a text editor
Each item in a project file is automatically associated with a text editor that can be used to modify its contents.
To open a text editor:
1. Select the item you want to edit.
2. From the Item menu, choose Edit.
Result: The text editor you specified in the Options menu opens.
Note: You can also open a text editor by double-clicking the item you want to edit.
To close a text editor:
1. Review the changes you made to the item file.
2. From the File menu, choose Save.
Result: The item is saved.
3. From the File menu, choose Close.
Result: The window that contained the item you changed disappears.
Changing the default text editor
There may be occasions when you want to change the default text editor. For example, if you have a text editor that you use regularly, you may prefer to continue to use it rather than the default text editor provided with the IDE.
To change the default text editor:
Building Items
Tools and Utilities Guide 23
1. From the Options menu, choose Editor.
Result: The SA-ASE IDE Options dialog box appears, with the default editor listed.
2. Change the listed editor to one of your choice.
3. Choose OK.
Building Items
Overview The IDE provides several options for building and updating object code for an item. This section covers the following topics:
• Building an item
• Rebuilding all the items in a target
• Rebuilding all the items in a project
The difference between a build and an update is that when you build items, all specified items are rebuilt unconditionally. For more information on building your application, see the chapter “The SA-Script Parser.”
When you update items, only those items that have source code that is newer than the object code are rebuilt. For more information, see the section “Updating Your Project.”
Note: If there is no object code for an item that is selected for an update, it is built.
When the IDE executes the build program, it passes the name of the item(s) to build as command line arguments. When you build or update multiple files, a message appears confirming a successful build or update.
The SA-Script IDE
24 SA-Application Software Expert 5.0
1
If a build program is specified as a command line for an item, substitutions are performed in the application. If no command line is defined, the name of the selected item is used. If no build program is specified for the selected item, a warning message appears.
Building an item
To build an item in a target:
1. Choose the item you want to use.
2. From the Item menu, choose Build.
Result: The build process begins immediately.
Rebuilding all the items in a target
To build all the items on a target:
1. Select the target you want to use.
2. From the Build menu, choose Rebuild Target.
Result: The build process begins immediately.
Rebuilding all the items in a project
To build all the items in a project:
• From the Build menu, choose Rebuild All.
Result: The build process begins immediately.
Updating Your Project
Tools and Utilities Guide 25
Updating Your Project
Overview You can update just the targets in your application or the entire project file, including associated targets and items.
This section covers the following topics:
• Updating all the items in a target
• Updating the project file
Updating all the items in a target
To update all the items on a target:
1. Select the target you want to use.
2. From the Build menu, choose Update Target.
Result: The update process begins immediately.
Updating the project file
To update all the items in a project file:
• From the Build menu, choose Update All.
Result: The update process begins immediately.
The SA-Script IDE
26 SA-Application Software Expert 5.0
1
Building and Updating .KB Files
Overview Knowledgebases are built and updated in the same manner that items are built and updated. That is, for an update, the SA-Script Parser parses all .kb files in the project whose time stamp is newer than its .kbc file, or if no .kbc file exists, one is created.
Rebuilding a .kb file allows the SA-Script Parser to parse all .kb files in the project regardless of their modification times.
This section covers the following topics:
• Rebuilding a knowledgebase
• Updating a knowledgebase
Rebuilding a knowledge-base
To build a knowledgebase:
1. From the Integrated Development Environment window, select the .kb file you want to use.
2. From the Build menu, choose Rebuild KB.
Result: An Information message appears that tells you the operation was successful.
Updating a knowledge-base
To update a knowledgebase:
1. From the Integrated Development Environment window, select the .kb file you want to update.
2. From the Build menu, choose Update KB.
Result: An Information message appears that tells you the operation was successful.
Running Files
Tools and Utilities Guide 27
Running Files
Overview The IDE can run any executable file. This section covers the following topics:
• Running a file
• Setting the working directory to run SA-Script programs
Running a file To run a file:
1. From the Integrated Development Environment window, select the item that you want to run.
2. Do one of the following:
From the Item menu, choose Run.
or
Click the Run toolbar button.
Setting the working directory to run SA-Script programs
To set the working directory to run SA-Script programs:
1. From the Options menu, choose Run Directory.
Result: The Set Working Directory dialog box appears.
2. Type the directory name from where you want SA-Script programs to run.
3. Choose OK.
This chapter covers the following topics:
•Introduction
•Opening and Closing the SA-Script Debugger
•Code in the SA-Script Debugger
•Working with Code
•Tracing Execution Paths in Code
•Break Points
•Debugging Windows and Dialog Boxes
2The SA-Script Debugger
The SA-Script Debugger
30 SA-Application Software Expert 5.0
2
Introduction
The SA-Script Debugger is used to debug SA-Script programs. Using the SA-Script Debugger, you can review the step-by-step execution of run-time code.
The following sections describe the basic techniques for working with the SA-Script Debugger. Additional information about working with different viewers is contained in subsequent sections.
Opening and Closing the SA-Script Debugger
Opening the SA-Script Debugger
There are several ways you can start the SA-Script Debugger.
•You can open the SA-Script Debugger from a command prompt by typing the -t switch before the .kb file name on the command line:
KML -t <.kb file name>
Note: <.kbc file name> must be in compiled or parsed format to run.
The SA-Script Debugger starts in single-step mode; that is, code execution stops. You can then use step in, step over, or step out to debug the code. For more information, see the section, “Tracing Execution Paths in Code.”
To open the Debugger:
Opening and Closing the SA-Script Debugger
Tools and Utilities Guide 31
•If the debug500.dll is present when you run an SA-Script application, some runtime error messages may ask if you want to open the SA-Script Debugger.
If you choose to open the SA-Script Debugger, the line that was executing when the error occurred is selected. If the debug500.dll is not present, any error messages you receive do not contain the option to start the SA-Script Debugger.
•You can start the SA-Script Debugger by embedding BreakPoint statements in your code. When a BreakPoint statement executes, the SA-Script Debugger is invoked. The BreakPoint statement is selected. For more information on BreakPoint statements, consult the SA-ASE 5.0 SA-Script Language Reference as well as the section “Break Points” in this chapter.
•You can also set temporary break points in the code. These temporary break points remain for the duration of the application’s execution. The break points are removed automatically when you quit the SA-Script Debugger.
•You can configure the IDE to start the SA-Script Debugger automatically whenever a .kb file runs in the IDE. Choose the Debug command from the Options menu to configure the IDE.
Note: Only one copy of the SA-Script Debugger can run at a time.
Quitting the SA-Script Debugger
The Run menu contains two commands that can be used to quit the SA-Script Debugger: Close and Abort.
• Close closes the SA-Script Debugger and returns control to the application. Application execution resumes.
• Abort closes the SA-Script Debugger and the application being debugged.
The SA-Script Debugger
32 SA-Application Software Expert 5.0
2
Code in the SA-Script Debugger
Introduction The SA-Script Debugger enables you to debug without having the actual source code present. (What you see in the SA-Script Debugger is not an exact copy of the source code.) The process of reorganizing source code results in the following changes:
• Code comments are eliminated.
• User formatting is eliminated.
• Named and numeric constants appear in decimal format.
• String variables and constants that contain internal quote characters (Dave”s Mother) are resolved (Dave’s Mother).
• Expressions composed of constant values appear as a single value in the SA-Script Debugger. (This applies to both numeric and string expressions.) For example:
• Numeric relational expressions appear as a combination of ‘<‘ , ‘=’ , or logical NOT.
• The parentheses in expressions are always removed, but the order of evaluation is consistent with the original source code. For example, assume that a=5, b=4, and c=3:
In both formats, x equals 27.
Source SA-Script Debugger
x :=3*(5+4); x := 27;
Source SA-Script Debugger
x :=c *(a+b); x :=c*a+b;
Working with Code
Tools and Utilities Guide 33
• Date constants appear in their internal format, rather than in their source format:
Working with Code
Overview The SA-Script Debugger has a code viewer that displays all the modules in a .kb file. These include:
•routines
•types
•constants
•global variables
The following is the SA-Script Debugger with .kb file information shown.
Source SA-Script Debugger
3 June 1997 6, 3, 1997
The SA-Script Debugger
34 SA-Application Software Expert 5.0
2
Viewing functions
The Lexical tab, located to the right of the code viewer, provides a high-level view of an application’s structure. It contains a tree of the modules in your file as well as the corresponding functions in each module.
To select a function to view:
1. On the Lexical tab, click the module containing the function you want to view.
Result: The module displays its corresponding functions.
2. Click the function you want to view.
Result: The function displays in the code viewer.
Note: The SA-Script Debugger automatically displays functions when it encounters a break point. For more information on break points, see the section “Break Points” on page 38.
Viewing variables
Variable viewers are used to see the storage data and access paths for local and global variables.
You can view a variable in the following ways:
• Click a variable hot spot (denoted by an underline) in the code viewer or a variable in the Locals or Globals tab.
Result: The variable information appears in the Variable tab.
• Double-click a variable hot spot in the code viewer.
Result: The variable information appears in the Variable Viewer dialog box.
Automatically refreshing variables
A variable viewer shows information for all fields in a record. If any field changes its value, the entire variable viewer refreshes.
Note: If the record being accessed by the variable viewer is large, it may take a few moments for the variable viewer to refresh itself.
Working with Code
Tools and Utilities Guide 35
To set a variable for automatic refresh:
1. In the code window, double-click a hot variable name.
Result: A variable window appears.
2. Select the Auto Refresh check box.
Result: The variable window automatically refreshes itself as the value of the data changes.
Note: A variable viewer may be left open in the SA-Script Debugger as you work with an application.
Closing a variable viewer
The variable window can only be closed manually, by choosing the system menu or by choosing Close, in the Variable Viewer dialog box.
Viewing stacks
Clicking a function in the stack makes the function appear in the code viewer, with the current line highlighted.
Note: SA-Script functions are recursive, meaning that you can step into a function multiple times in the same SA-Script Debugger session. The name of the function appears in the stack viewer for each recursion.
When you step out of a function, its name disappears from the stack.
The SA-Script Debugger
36 SA-Application Software Expert 5.0
2
Tracing Execution Paths in Code
Introduction Using the SA-Script Debugger, you can trace the execution path of an application. To do this, the SA-Script Debugger provides three options:
•Step in
•Step out
•Step over
Stepping in executes the next line of code, and if a function call exists, steps into the function. Stepping over executes the next line of code without stepping into function calls. Stepping out executes the code until the end of the current function.
You can step in, out, or over code by choosing commands from the Run menu, or by clicking the corresponding buttons on the SA-Script Debugger toolbar. In addition, keyboard accelerators are provided:
• Press I to step into code.
• Press T to step out of code.
• Press O to step over code.
As you work with the SA-Script Debugger, you work through various levels of function calls. Each function can have embedded function calls.
Stepping into a function
The SA-Script Debugger enables you to step into the functions in your code and view the actions defined in the function. As you step into code, remember these points:
• When you step into a function, the next function to be executed is selected.
• The next function may be an event handler. For example, function calls may be WinCreate or SendMessage.
You can do any of the following to step into code:
• From the Run menu, choose Step In.
• Click the Step In toolbar button.
• Press I in the code window.
Tracing Execution Paths in Code
Tools and Utilities Guide 37
You can continue stepping through a function to advance to the next action defined in the function. Eventually, you reach an END statement. At that point, pressing I again returns you to the point where you stepped into the code.
Stepping out of a function
When you step out of a function, the current function, procedure, or event handler is executed without tracing; you do not see the line-by-line execution of the code. Tracing resumes on the first statement after the call.
Note: If you step out of an event handler, tracing resumes at the statement the statement that generated the event. If more than one event was generated, tracing resumes at the beginning of the next event.
You can step out of code whenever execution is stopped in the body of a function or event handler. You can also step out of code if execution has stopped at a break point.
You can do any of the following to step out of code:
• From the Run menu, choose Step Out.
• Click the Step Out button on the toolbar.
• From the code window, Press T.
Stepping over code
In addition to stepping in and out of code, you can step over code. Stepping over code traces the execution path at the statement level. Execution continues until the next statement is reached.
Note: Execution stops if there are errors or break points in the function that was stepped over.
You can do any of the following to step over code:
• From the Run menu, choose Step Over.
• Choose the Step Over button on the toolbar.
• From the code window, press O.
The SA-Script Debugger
38 SA-Application Software Expert 5.0
2
Break Points
Overview Break points are a method of stopping the execution of run-time code for purposes of checking on the current status of the execution. When a break point is encountered during execution, the SA-Script Debugger displays the function with the line containing the break point selected.
Note: Do not set break points in an event handler while it is processing $MsgDDEInitiate. $MsgDDEInitiate broadcasts a message to the applications and locks the message queue until a response is returned. Triggering a break point initiates an event handler that waits for a response from the (locked) message queue. This results in a deadlock, which effectively locks the user interface.
Setting temporary break points
Temporary break points exist only while an SA-Script program executes. Temporary break points automatically clear when you quit the SA-Script Debugger session. You set these break points as you interact with function viewers.
To set a temporary break point:
•Double-click a line in the code window.
Result: The * symbol appears to indicate the break point.
Note: Temporary break points must be set on statements that can be executed. You cannot set break points on lines beginning with ELSE and ELSEWHEN statements.
Debugging Windows and Dialog Boxes
Tools and Utilities Guide 39
Setting permanent break points
You can place permanent break points in SA-Script program source code by using the BreakPoint statement. A BreakPoint statement can be added wherever there is a “point of interest,” such as the start of a function call or event. This enables you to halt the application at a logical stopping point and review the current state of the application. The only way to remove a BreakPoint statement is to delete it from the source code and reparse the application.
Other BreakPoint uses
You can create a menu command that is associated with the BreakPoint statement. This enables you to start the SA-Script Debugger from the application.
The SA-Script Debugger does not run if the debug500.dll is not present. Because the debug500.dll is not part of the standard, installed product, the embedded BreakPoint statements do not affect run-time performance.
Debugging Windows and Dialog Boxes
Overview You can debug windows and dialog boxes using WinCreate and DlgCreate. These statements identify the names of event handlers that process window events.
To trace the execution of WinCreate, step into WinCreate, and then step out of each message generated.
Note: Do not use the SA-Script Debugger to trace paint, activate, or mouse processing.
This chapter covers the following topics:
•Introduction
•Searching for Source Files
•Using The SA-Script Parser
•Command Prompt Arguments
•IMPORT Declarations
•Circular Usage in .KB Files
•SA-Script Parser Errors
3The SA-Script Parser
The SA-Script Parser
42 SA-Application Software Expert 5.0
3
Introduction
Overview The SA-Script Parser translates ASCII text files that contain SA-Script source code into a binary format used to build application files. The SA-Script Parser translates .kb files to .kbc files.
The SA-Script Parser is available in both a command prompt version (kp.exe) and a windowed version (kpw.exe).
Note: These are the same in UNIX except for the .exe extension.
Searching for Source Files
Checking directories for source files
When the SA-Script Parser searches for a source file that has no explicitly specified directory, it checks directories in the following order:
1. Any directories specified at the command prompt for other .kb files either by means of the -U (or -F) argument or as part of a file name specification
2. The current directory
3. The directory containing the kmli500 library (for Windows and OS/2 only)
4. Any directories specified in the SAIPATH
5. Any directories specified in the dpath (OS/2 only)
6. Any directories specified in the path
Using The SA-Script Parser
Tools and Utilities Guide 43
Using The SA-Script Parser
Opening the SA-Script Parser
You can open the SA-Script Parser using either one of the following methods:
•From the Start menu, point to Program, point to SA-ASE, and then choose SA-Script Parser.
Result: The SA-Script Parser dialog box appears.
•From the command prompt, type the following:
kpw [option] [.kb file ...]
Press Enter.
Result: The SA-Script Parser dialog box appears.
Using the SA-Script Parser dialog box
The SA-Script Parser dialog box is used to specify the kb. file to parse and to set parse options.
Note: Using the switches at the command prompt is the same as typing commands in the text boxes.
1. Open the SA-Script Parser.
Result: The SA-Script Parser dialog box appears.
The SA-Script Parser
44 SA-Application Software Expert 5.0
3
2. Choose the Parser tab and type or select the appropriate parse options:
•File Name - specifies the .kb file to parse
•Browse - accesses a dialog box used to locate and select a source file instead of typing the file name in File Name
•Parse Options:•Parse (Default) - parses only the specified .kb file•Update - parses all .kb files referenced in an application.
If a .kbc file already exists that is not older than the current source code, the SA-Script Parser does not reparse the file.
•Build - translates the specified .kb file referenced in any USES section in a parsed .kb file. If you select this option and the .kb file contains the application's entry point, you rebuild the entire application.
3. Choose the Advanced tab (optional).
Result: The Advanced tab appears.
Using The SA-Script Parser
Tools and Utilities Guide 45
4. Type information in the boxes:
•Connect String - enables you to set the DBMS connection string
•Error Message Filename - specifies the file where error messages generated by the SA-Script Parser should be sent. If no error messages are generated, the specified file is removed automatically.
•Assert Symbol - used for conditional translation. You specify an identifier that is added to the SA-Script Parser’s internal database so that source text enclosed in the #IF ... #ENDIF construct is translated.
•Deny Symbol - used for conditional translation. You specify an identifier that is removed from the SA-Script Parser’s internal database so that source text enclosed in the #IF ... #ENDIF construct is ignored by the SA-Script Parser.
•Additional Search Dirs - specifies a path whose directories are added to the list of directories that are searched when the SA-Script Parser locates the source text path. The path may consist of any number of fully qualified directory names separated by semicolons.
•Cross-Reference - specifies a database in which three tables are created. These tables contain information on the definition and use of global constants, types, variables, routines, SQL tables, text files, icon files, and bitmap files.
The SA-Script Parser
46 SA-Application Software Expert 5.0
3
•Listing Filename - specifies the file where a list generated from the source text is sent. If no file name is specified, the list is sent to standard output.
•Code Page (Windows only) ANSI-P=ANSI(Default ) OEM-P=OEM - specifies whether the OEM or ANSI code page is used when writing strings to the .kbc output file.
5. After all entries and selections have been made, choose Run.
Result: The Parser runs.
Command Prompt Arguments
Introduction The SA-Script Parser accepts arguments using the following parameters:
-a, -b, -c, -d, -e, -f, -u, -l, -m, -o, -p, -q, -s, -x, -ide, -help
A parameter can follow the argument character (no intervening space) or precede it with an equal symbol (=) or colon (:). For instance, the three examples that follow all achieve the same effect, though you may prefer one form over another:
-uf:\sai\ea-u=f:\sai\ea-u:f:\sai\ea
Valid arguments for the SA-Script Parser are shown in the following table.
Command Prompt Arguments
Tools and Utilities Guide 47
Argument Value Comment
-b Build Tells the SA-Script Parser to translate the .kb file(s) specified at the command prompt. In addition, all .kb files referenced in any USES section in any .kb file are parsed.
If you specify the -b option when you parse the .kb file that contains an application's entry point, the SA-Script Parser rebuilds the entire application.
-m Make Tells the SA-Script Parser to parse the .kb file referenced anywhere in an application. If a .kbc file already exists that is not older than the current source code, the SA-Script Parser does not reparse the file.
-a<identifier> Assert Causes the identifier to be installed in the SA-Script Parser’s internal database so that source text enclosed in the #IF ... #ENDIF construct is translated.
-d<identifier> Deny Causes the identifier to be removed from the SA-Script Parser’s internal database so that source text enclosed in the #IF ... #ENDIF construct is ignored by the SA-Script Parser.
-u<path> Use Adds the directories in the path to the list of searched directories when the SA-Script Parser locates source text for a .kb file. The path may consist of any number of fully qualified directory names separated by semicolons. In UNIX directory names are separated by colons.
The SA-Script Parser
48 SA-Application Software Expert 5.0
3
-l-l<file>-l+
List Generates a list of the source text. If you specify the -l option, the list is sent to standard output.
If you specify a file name(-l<file>), the list is sent to that file.
If you specify the -l+ option, the list is sent to a file whose name consists of the .kb file name with the extension .lst. (The .kb file name may be altered to fit the file-naming conventions of the operating system).
Any error messages generated by the SA-Script Parser are written to the list file unless a separate error file has been specified with the -E option.
-e<file> Error Sends error messages generated by the SA-Script Parser to the specified file. If no error messages are generated, the specified file is removed automatically.
-q Quiet Suppresses display of copyright banners and progress messages, which are otherwise sent to standard output.
-x<database> Cross-Reference Creates three tables in the specified database that contain information on the definition and usage of global constants, types, variables, routines, SQL tables, text files, icon files, and bitmap files.
Argument Value Comment
Command Prompt Arguments
Tools and Utilities Guide 49
-ide IDE Alters the format of error messages generated by the SA-Script Parser so that theASE IDE can find the appropriate source text lines in which the associated errors were detected.
-help/? Help Displays a usage summary in standard output.
-f <path><module>.KB
Shorthand Notation
Equates to typing the line: kp -u=<path> <module>.
-c<drive><path>
Switches to the specified drive and directory.
-s<string> Sets the DBMS connection string to <string>.
-o<directory>-o=<directory>-o:<directory>
Specifies the output directory in which all generated kbc files are written. By default, the Interface Generator generates .kbc files into the directory where the corresponding .kb file was found.
-p=oem -p=ansi -poem -pansi ( Windows only)
Specifies the OEM or ANSI code page to use when writing strings to the .kbc output file. If not specified at the command prompt, the Interface Generator uses the value read from the softart.ini file. If no code page is specified, the ANSI code page is used (EPSDIC in UNIX.)
Argument Value Comment
The SA-Script Parser
50 SA-Application Software Expert 5.0
3
IMPORT Declarations
Requirements for parsing code with IMPORT declarations
If the SA-Script source code to be parsed contains any IMPORT declarations, you must be connected and logged on to the appropriate database manager, and the necessary database(s) must be bound. Otherwise, error messages are generated.
Temporary files
Using the IMPORT declaration to import data from a database results in the creation of a temporary file. This file, kmlimprt.out, is automatically removed from the database on import completion.
If the SA-Script Parser terminates unexpectedly, deletion of these files may not be completed. You can manually delete these files as long as the SA-Script Parser is not running.
Parsing with the -S option
If you want to override any hard-coded database or connection information in the IMPORT statement, pass the -S option to the SA-Script Parser. This enables you to specify the database at parse time and eliminates the need to hard code the database source name.
The -S option also enables you to specify the user ID and password at parse time when running the SA-Script Parser from the command prompt. Any values specified in the sai_sql.cfg file are ignored.
The preferred method for using the -S option is to specify all values except the user ID and password in the sai_sql.cfg file. Then, at parse time, pass in these values. For example:
-S"UID=UserId; PWD=Password"
(where UserId is the user ID and Password is the user’s unique password.)
Circular Usage in .KB Files
Tools and Utilities Guide 51
Circular Usage in .KB Files
What is circular usage?
The SA-Script language is designed to allow .kb files to use each other. When .kb files use each other, each .kb file defines a record type that is accessed by the other. This results in circular usage. In other words, .kb file A cannot use .kb file B’s PUBLIC section if B already uses A’s PUBLIC section. Circular usage is supported by SA-Script, but it is not supported by the SA-Script Parser.
To avoid circular usage, move all affected record declarations into a separate .kb file that is used by both of the original .kb files. The two original .kb files can then continue to reference each other’s variables and routines.
SA-Script Parser Errors
The following table summarizes the error conditions reported by the SA-Script Parser. (These errors are common to the graphical, windows parser, as well as command line.)
Warning: Missing semicolons cause a variety of error messages to occur. If you encounter an error that you do not understand, make sure that all semicolons are present.
Error Explanation
$CURRENT is not a valid index for an array.
An attempt was made to index an array expression with the special index $CURRENT. This index is only valid for list expressions.
$EVENT is not defined in the scope of <function>.
The given function is not an event handler, nor is it nested in the scope of an event handler. Therefore, the special symbols associated with event handling are not defined.
The SA-Script Parser
52 SA-Application Software Expert 5.0
3
$EVENTPARM is not defined in the scope of <function>.
The given function is not an event handler, nor is it nested in the scope of an event handler. Therefore, the special symbols associated with event handling are not defined.
$HANDLE is not defined in the scope of <function>.
The given function is not an event handler, nor is it nested in the scope of an event handler. Therefore, the special symbols associated with event handling are not defined.
$NullHandler may not have an initialization argument when used as an argument to <creation routine>.
Passing an initialization argument to $NullHandler when used with the given creation routine serves no purpose.
#ELSE encountered without a matching #IF.
The SA-Script Parser read the preprocessor directive without encountering a matching #IF directive.
#ENDIF encountered without a matching #IF.
One of these preprocessor directives was read without having seen a matching #IF directive.
<name> is not a defined type.
The given name was encountered in a context where a type specification was expected.
<name> is not a field of the given record type.
An expression that refers to a field by name gives a name that does not belong to any field in that record.
<name> is not a function or procedure.
A call expression refers to an object that is not a routine.
A comma (,) is missing.
The SA-Script Parser did not encounter a comma it expected.
A file write error occurred.
A file write operation failed at some point after a successful open operation. Generally, this is indicative of an internal software error. It can also reflect a problem with the associated hardware.
Error Explanation
SA-Script Parser Errors
Tools and Utilities Guide 53
A parameter passing protocol (either VALue or REFerence) must be specified.
A formal parameter declaration must be prefixed with either the VAL or REF keyword to specify which protocol is used when the routine is called.
All selectors in a WHEN statement must have the same type.
A selector (or selectors) in a WHEN clause with multiple selectors has a type that is different than the other selectors in the WHEN clause.
An event-handling function is required.
Only event-handling functions can be passed to the creation routines for windows, dialog boxes, and other event-generating objects.
An unexpected delimiter was encountered.
The last specification in a formal parameter list has an unnecessary trailing comma.
Argument #<n> (<name>) to function <routine> is invalid.
The type of the given argument does not match the type of the corresponding formal parameter.
Constant expression required.
A constant expression is required in the current context.
Constant <name> is never referenced in the scope of <name>.
The given constant is declared but not used.
Did not find #ENDIF to match directive on line <n>.
The SA-Script Parser reached the end of the source file without finding an #ENDIF directive that matches the #IF or #ELSE on the given line.
Event handler type of <name> does not match forward declaration.
A FORWARD or PUBLIC declaration for the event handler specified a type of event to be handled that is different than what is specified in the effective declaration. (By default, WINDOW is the type of event to be handled.)
Event handler <name> may not be declared with a return type.
A routine declared as an event handler may not have a return type specified. Event handlers always return an integer. If no value is explicitly returned, one is the default return value.
Error Explanation
The SA-Script Parser
54 SA-Application Software Expert 5.0
3
Event handling function <name> does not handle the type of events generated for the object created by <creation routine>.
Window event handlers cannot handle events for Process objects, and vice versa.
Event handling function <name> may not have more than one formal parameter.
The given event handler was declared with more than one formal parameter.
Event handling functions can only appear at the outermost scope.
An event handler cannot be nested inside another routine.
Expression does not refer to an accessible location.
An assignment (or other expression that affects the value of an object) requires an accessible and mutable object upon which to operate.
Expression cannot be passed by reference.
An expression that does not evaluate to an accessible, mutable object cannot be passed as a REF parameter.
Forward declaration for <variable_name> does not match forward declaration of <Routine_name>
The PUBLIC ROUTINES section does not match the PRIVATE ROUTINES section. Make sure that the arguments declared in PUBLIC ROUTINES match those declared in PRIVATE ROUTINES. The arguments should be of the same data type and they should be spelled consistently.
Forward function <function> has no effective implementation.
The given function was declared either publicly or by a FORWARD declaration. However, it has no effective declaration.
fread() in flex scanner failed
The source .kb file became unreadable at some point after it was opened. Such an event could be caused by a disk or network failure.
Function <name> is missing a return type declaration.
A routine declared as a function must have a return type specified.
Error Explanation
SA-Script Parser Errors
Tools and Utilities Guide 55
Function <name> is never referenced in the scope of <name>.
The given routine is declared but not used.
Function <name> cannot be called in a procedural context.
The named function returns a value that cannot be ignored.
INTERNAL ERROR detected at line <n> in <file>.
An error condition exists within the SA-Script Parser. Note the file name and line number and contact the Software Artistry Customer Support Line.
Invalid $EXPORT annotation. Valid annotations are: LITTLE_ENDIAN, INTEL, BIG_ENDIAN, ASCII, EBCDIC, CUSTOM_CONVERT(...) and CTYPE(...)
An annotation that is not in the given list of valid annotations appeared in the $EXPORT clause of a record declaration.
Invalid coercion from type <type-1> to type <type-2>.
It is invalid to coerce between the given types in the current context.
Invalid control expression in FOR loop.
The FOR statement may only iterate over integer ranges and the contents of a list.
Invalid declaration. A syntactically invalid construct was encountered in a location where the SA-Script Parser expected to find a declaration.
Invalid expression. A syntax error was detected in a context where the SA-Script Parser expected to find an expression.
Invalid expression type.
A different type was expected.
Invalid field annotation.
An annotation that may not be applied to a field was found. The LITTLE_ENDIAN, INTEL, BIG_ENDIAN, CUSTOM_CONVERT(...), and FILL(...) annotations are all invalid in this context.
Error Explanation
The SA-Script Parser
56 SA-Application Software Expert 5.0
3
Invalid identifier: <string>.
An identifier specified on the command prompt (either as a .kb file name or as part of an -a or -d option) does not fit the lexical specifications for a SA-Script identifier.
Invalid operand to <op> operator.
The given operator requires an operand of a different type.
Invalid option: <???>. The SA-Script Parser encountered an unknown command prompt switch.
Invalid pseudofield annotation.
An annotation that cannot be applied to a pseudofield was found. Only the FILL(...) and VALUE(...) annotations are legal in this context.
Invalid redeclaration of symbol <symbol>.
The given symbol has more than one definition in the same scope.
Invalid statement. A syntax error was encountered in a location where the SA-Script Parser expected to find a statement. Make sure that all required semicolons are present.
Invalid type specification.
A syntax error was detected in a context where a type specification was expected.
Invalid WHEN statement expression type.
The WHEN statement can only select among values of type INTEGER or STRING.
KB file <kb-1> references type <typename> which is defined in .kb file<kb-2>, but does not list <kb-2> among the .kb files which it uses.
A type is referenced for which there is no available definition. This usually occurs when a record defined in one .kb file contains a field of a type that is defined in a different .kb file, and a third .kb file, which uses the first .kb file but not the second, attempts to access that field.
.KB file name <name-1> does not match the name (<name-2>) by which it is known externally.
The name given in the KNOWLEDGEBASE declaration at the beginning of the .kb file does not match the name by which it was accessed either from the command line or via a USES declaration in another .kb file.
Error Explanation
SA-Script Parser Errors
Tools and Utilities Guide 57
Parameter count for function <function> does not match FORWARD declaration.
A FORWARD or public declaration of the given function specified a different number of parameters than is specified by the effective declaration.
Parameter declaration for <parameter> does not match the FORWARD declaration of <function>.
A FORWARD or public declaration of the given function specified the given parameter differently (either a different type or a different parameter-passing protocol) than the effective declaration.
Parameter name <name-1> does not match <name-2> from FORWARD declaration of function <function>.
A FORWARD or public declaration of the given function specified the same formal parameter under a different name than the effective declaration.
Parameter <name> of function <function> is never referenced.
The given parameter is declared but not used.
Procedural function <name> has no $RESULT.
The $RESULT pseudovariable may not be referenced inside a routine declared as a procedure.
Procedure <name> cannot be declared with a return type.
A routine declared as a procedure cannot have a return type.
Selector <value> cannot appear multiple times in a WHEN statement.
Each selector can appear only once in a WHEN statement.
Specified size (-<n>) may not be negative.
An array or list was declared with a negative initial size.
Symbol <symbol> is defined in both <.kb file- 1> and <.kb file-2>.
The given symbol is publicly defined in both of the given .kb files. This is a warning only. The second definition shadows the first.
Symbol <symbol> is undefined.
The given symbol was used in an expression or declaration without having been previously defined.
Error Explanation
The SA-Script Parser
58 SA-Application Software Expert 5.0
3
Symbol <symbol or variable name> is undefined.
A variable is being used in the ACTIONS section that has not been declared in the VARIABLES section either locally, globally, or anywhere in the USES chain.
The argument to an event handler must be passed by reference.
The formal parameter to an event handler was not specified with the REF keyword.
The declaration of <symbol> is missing a colon (:) delimiter.
A colon delimiter is missing from the given declaration.
The declaration of <symbol> is missing the IS keyword.
The IS keyword is missing from the given declaration.
The predefined symbol <symbol> cannot be redefined.
The given symbol is predefined in the SA-Script language and cannot be given a new definition by application code.
Too many types defined (more than 65000).
There is an internal error condition in the SA-Script Parser. Contact the Software Artistry Customer Support Line.
Type <name> is never referenced in the scope of <name>.
The given type is declared but not used.
Type <type> is not a RECORD type.
A record type is required in the current context.
Type <type> cannot be indexed.
An attempt was made to index an expression that was not an array, list, or string type.
Type of initialization argument #<n> is invalid.
The type of the given initialization argument does not match the type of the corresponding parameter, field, or element.
Type returned by <function> does not match forward declaration.
A FORWARD or public declaration of the given function specified a different return type than is specified by the effective declaration.
Error Explanation
SA-Script Parser Errors
Tools and Utilities Guide 59
Unable to allocate a <n> byte block at line <m> in <file>.
The SA-Script Parser ran out of memory while parsing the source code. Unless the value given for n is extremely large (which may be indicative of some sort of internal error), it is unlikely that you will ever encounter this message unless you are running the debugging heap manager.The only way to run out of memory is to run out of swap space. In this case, the operating system will probably lock up.
Unable to coerce value <v> to type <type>.
The SA-Script Parser is unable to coerce the given constant value to the specified type.
Unable to IMPORT <view>, error code = <n>.
An IMPORT declaration failed. The database may not be bound or the machine may not be connected and logged on to the appropriate database manager.
Unable to locate file <file>.
The named file was not found in any of the directories searched by the SA-Script Parser. These directories include the current directory, the directory in which SA-Script i420.dll is located, and the directories specified in either the SAIPATH or dpath environment variable or via the -u command prompt argument.
Unable to make <path> the current directory.
The directory specified with the -c command prompt switch is inaccessible.
Unable to open file <file>.
The file open operation failed for the given file. The most likely cause of this is a lack of appropriate rights for that file.
Unexpected selector type.
The type of the selector in a WHEN clause does not match the type of the controlling expression.
Error Explanation
The SA-Script Parser
60 SA-Application Software Expert 5.0
3
Unrecognized character <char> encountered.
An unrecognized character was encountered by the SA-Script Parser. The character does not fit into any lexical specification in the SA-Script language.
Unrecognized preprocessor directive.
A line beginning with a '#' character was encountered, and the directive was something other than #ASSERT, #DENY, #IF, #IFNOT, #ELSE or #ENDIF.
Unterminated comment beginning on line <n>.
The SA-Script Parser reached the end of the source file without finding a ‘*)’ character sequence to match the ‘(*’ sequence on the given line.
Unterminated string. The SA-Script Parser reached the end of a line without finding the quote character to close a string literal.
Untrapped syntax error at or near column 0 of line 12.
The keyword, ROUTINES, is missing. The keyword, KNOWLEDGEBASE, at the top of the file is spelled incorrectly. One of the sections, ACTIONS, WHILE, or IF, is missing an END statement.
Variable <name> is never referenced in the scope of <name>.
The given variable is declared but not used.
Wrong number of arguments to <type> initializer.
The initializer for the given type requires a different (probably smaller) number of arguments.
Wrong number of arguments to function <name>.
The named routine requires a different number of arguments than the number provided in the call expression.
Wrong number of arguments to function <procedure_name>. Expected <number>. Received <number>.
When the procedure, function, or event is called in the ACTIONS section of the .kb file, it does not match the formal definition.
Error Explanation
SA-Script Parser Errors
Tools and Utilities Guide 61
Unable to find a file with the name <filename-1>. Using <filename-2> instead.
Note: This will not be supported in future releases.
If you specify a .kb file name in the USES section of a .kb file, it should have the same case as the file containing that .kb file. If it does not, the SA-Script Parser will attempt to find it anyway and if it succeeds, the above message is displayed.
Expected non-obsolete syntax for WinSetMousePointer. Replace with WinSetWaitPointer
The WinSetMousePointer statement in ASE versions 4.2 and earlier has been modified to support multiple windows in ASE version 5.0. To stay compatible with the old syntax, the SA-Script Parser recognizes the old syntax and translates it to a new function (WinSetWaitPointer) that performs the old behavior.
Invalid (or obsolete) linkage specification for EXTERNAL routine <routine>.
The $BC16 and $BC32 linkage specs are no longer supported in ASE 5.0 (which is now a 32 bit program and no longer able to load older 16 bit Windows DLLs). Use $C instead and be sure you are linking to a 32 bit DLL.
.KB file name <name> conflicts with a built-in function or other internal symbol.
Versions of ASE prior to 4.2 allowed you to give a .kb file the same name as an internal symbol. For example, STRING, WinCreate, when, etc.) resulting in confusion and potential internal errors. The ASE 5.0 SA-Script Parser now recognizes this error and reports it. Rename your .kb file to something that does not conflict and try again.
Error Explanation
This chapter covers the following topics:
•Introduction
•Generating .dfc Files
•Command Prompt Arguments
•Interface Generator Errors
4The Interface Generator
The Interface Generator
64 SA-Application Software Expert 5.0
4
Introduction
Overview The Interface Generator generates .dfc files in the directory where the corresponding .df file is found. Do not confuse the Interface Generator with the Interface Designer. The Interface Designer is used to customize and add functionality to your .df file. The Interface Generator processes the .df file to a .dfc file. The Interface Generator is run from a command prompt version (i-gen.exe) or a windowed version ( i-genw.exe).
By default, the Interface Generator generates .dfc files into the directory where the corresponding .df file was found. The Interface Generator also uses the OEM or ANSI code page when writing strings into the .dfc output file. If not specified at the command prompt, the Interface Generator uses the value read from the softart.ini file.
Generating .dfc Files
Using the windowed Interface Generator
You can open the windowed version of the Interface Generator using either one of the following methods:
From the Start menu, point to Program, point to SA-ASE, and then choose Interface Generator.
Result: The Interface Generator Dialog Box appears.
Generating .dfc Files
Tools and Utilities Guide 65
To use the Interface Generator:
1. Type the name of the .df file to parse in the File Name box or use the browse button to find the file.
Note: Unlike the SA-Script Parser, the Interface Generator does not search the SAIPATH or path environment variables for .df files. You must specify a full path to the file if it is not in the current directory.
2. If the .df file was generated by an older version of ASE ( 4.2 or earlier) select Convert from 4.x Format check box.
Result: The conversion process creates the .dfc file.
Note: For OS/2 users, if you did not paint OS/2 screens, do not use the conversion function in the Interface Generator. Use the Interface Designer to paint screens.
3. Choose Run.
Result: The current status information in the Build Status box and error messages and warnings in the Errors and Warnings box are parsed. A .dfc file is created in the same directory as the .df file.
The Interface Generator
66 SA-Application Software Expert 5.0
4
Using the Interface Generator from a command prompt
The command prompt version of the Interface Generator (i-gen) uses the following syntax:
i-gen [flags] [specification file]
Note: You must enter the name of the specification file.
Valid flags are listed in the following section.
Command Prompt Arguments
Command prompt flags
The following flags are used in the command prompt version of the Interface Generator only.
Flag Description
-convert Converts the specification file from a previous version (4.2 or earlier).
-d Defines a constant affecting #IFDEF directives in the .df file.
-l[filename] Specifies a listing file name. Outputs to a file instead of on screen.
-e[filename] Specifies an error file name. Error messages are written to a file instead of on screen.
-IDE Same as -e except error messages are written in ASE's hypertext format for easy access to the source of the error.
-M Generates a Motif C style header file which provides a constant for identifiers in the .df file.
-P Generates a Windows and OS/2 C style header file which provides a constant for identifiers in the .df file.
-Q Quiet mode. No text appears on screen.
-? Prints the syntax for running i-gen.exe.
Interface Generator Errors
Tools and Utilities Guide 67
Interface Generator Errors
Interface Generator errors
The following errors apply to graphical, windowed versions of the Interface Generator, as well as command line.
Error Description
Unknown character <c>
The SA-Script Parser has encountered a syntactically illegal character in the .df file.
Unknown command line switch <switch>
The syntax of the command line to i-gen (or i-genw) is incorrect. Remove or replace the offending switch and run the Interface Generator again.
Specification filename is required
You did not enter a specification file name at the command line.
Unable to open specification file
The file does not exist or is otherwise unreadable. A disk or networking failure may have occurred.
Unable to create a temporary file
The Interface Generator does not have access to create a new file in the current directory.
Missing quote at start of string
The syntax for string declarations is the following:
string <identifier> '<string text>'
This error occurs if that first single quote is missing.
String longer than 4096 characters - <string>
This is caused by a missing closing single quote on a string literal.
Illegal preprocesor directive <directive>;
The valid preprocessing directives are:#INCLUDE, #DEFINE, #IFDEF, #IFNDEF,#ELSE, #ENDIF
Cannot redefine <variable>
A value can only be defined once. This error is generated when a second definition occurs.
#else outside of #if block <name>
An #else was encountered without first seeing a #ifdef
#endif without opening #ifdef statement;
This error could be caused by a mismatched #IFDEF / #END pair.
The Interface Generator
68 SA-Application Software Expert 5.0
4
Obsolete syntax The <name> keyword is not supported in the current version. Use the-convert command line flag or select the ASE 4.x conversion check box to remove these keywords from the .df file.
DISPLAY is an obsolete keyword; use DEFINE.
The DISPLAY construct is obsolete. All controls are now declared using the DEFINE statement.
Re-declaration of FORM name <name>Re-declaration of STRING name <name>' Re-declaration of TOOLBAR name <name>'' Re-declaration of MENU name <name>''Redeclaration of FIELD identifer <name>'
Entity names must be unique. This error is generated by another occurence of the identifier.
'Undeclared constant <name>';
You have declared a constant that does not exist or exists in another scope. The .df grammer allows a CONSTANT section at the file and form scope.
String and Integer constants can be defined
The Interface Designer does not support the constant sections making it obsolete
Missing semicolon Semicolons must be used at the end of every statement.
Missing comma Commas must be used as delimiters.
Badly formed field qualifier <name>
One of the qualifiers in a field definition is invalid.
Badly formed window attribute <name>
One of the attributes in the WINDOW section of a form is invalid.
Error Description
Interface Generator Errors
Tools and Utilities Guide 69
Unable to open parsed code file <name>
Cannot create the .dfc file.
Mutually exclusive qualifiers specified
A field has two legal qualifiers specifed for a field but are mutually exclusive. For example, Accept, and Cancel are attributes for buttons.
More than one default button specified
Only one button with the default style should be specified. (Not strictly enforced with the introduction of subforms.)
'#include must be followed by a single quoted file name'
A #include statement has been encountered that does not include anything
'<name> not closed by #endif'
A #ifdef or #else has been encountered that is not closed by an #endif
'form name <name> not defined, page names must be defined forms'
When specifying a notebook, tabs must be declared before they are used. ASE 5.0 has alternate methods of declaring tabs so forward references and tabs from other files can be included.
'InputLength is overridden by a pattern definition'
An entry field or text box has an input length and a custom pattern specified. The pattern defines an input length so the InputLength statement is ignored.
'More than one fill character specified'
A pattern can only have one fill character. (The last one encountered is used.)
'Pattern <name> Display and Entry masks are not the same length'
Display and entry masks should be the same length for a pattern to work correctly.
'Radio buttons must have a button list'
A option button set is defined but no option buttons are specified.
'HorizontalScrollBar is ignored if NoWordWrap is not specified'
An MLE usually wraps lines that are too long for the right margin making horizontal scrolling difficult.
Error Description
The Interface Generator
70 SA-Application Software Expert 5.0
4
'Initial radio button value out of range'
An initial option button is specified that is not in the list of buttons.
'Unable to open log file.
Verify that the disk is not full and that you have network create/write access to the directory.
'Subform <name> not defined, subforms must be defined before they are referenced'
When specifying a subform, the embedded form must be declared before they are used. ASE 5.0 has alternate methods of declaring subforms so forward references from other files can be used.
Error Description
This chapter covers the following topics:
•Introduction
•Searching for .KB Files
•Command Prompt Arguments
•Interpreter Errors
5The SA-Script Interpreter
The SA-Script Interpreter
72 SA-Application Software Expert 5.0
5
Introduction
Overview The SA-Script Interpreter is the core of the SA-Script run-time system. The SA-Script Interpreter executes the statements and expressions that comprise an SA-Script application.
Searching for .KB Files
Checking directories for knowledge-bases
When the SA-Script Interpreter searches for a .kb file that has no explicitly specified directory, it checks directories in the following order:
1. Any directories specified at the command prompt for other .kb files by means of the -u (or -f) argument or as part of a file name specification
2. The current directory
3. The directory containing the kmli500 library (for Windows and OS/2 only)
4. Any directories specified in the SAIPATH
5. Any directories specified in the dpath (OS/2 only)
6. Any directories specified in the path
Command Prompt Arguments
Tools and Utilities Guide 73
Command Prompt Arguments
SA-Script Interpreter command prompt arguments
The SA-Script Interpreter accepts arguments from the command prompt with the following syntax:
kml [option ...] .kb file Valid arguments for the SA-Script Interpreter include those listed in the following table.
Note: These arguments are uppercase in UNIX.
Arguments Value Comment
-u<path> Use Adds the directories in the given path to a list of directories to be searched. This occurs when the SA-Script Interpreter locates the .kbc files that correspond to the .kb files used by the root .kb file. (The root .kb file is the parent to other child .kb files.). The path may consist of any number of fully qualified directory names separated by semicolons.
Note: UNIX requires the use of colons.
-t Trace (Debugger)
Starts the SA-Script Interpreter in trace mode. The SA-Script Interpreter enters the SA-Script Debugger prior to the execution of the first line of the root .kb file.
The SA-Script Interpreter
74 SA-Application Software Expert 5.0
5
-l Log Causes the SA-Script Interpreter to write a log message to a file named kml.log. This occurs in the current directory for every statement in the kml.log file. This option should be used with caution because it can consume quantities of disk space and slow application execution.
-o Optimization Off Turns off demand loading of .kbc files.
-? -HELP -H Help Displays a brief summary of the command line switches that it accepts.
-d DLLname “Preloads” dlls during program initialization. This is primarily used for debugging purposes during development.
-c Directory Changes the current drive and/or directory during program initialization.
Arguments Value Comment
Command Prompt Arguments
Tools and Utilities Guide 75
-f KBCfilename Used as an alternative method to specify one or more kbc files to load. You can specify -f=<filename> more than once on a command prompt. You can also load multiple kbcs into the process that are not related by means of the USES chain. Although .kbcs do not know about other .kbcs at parse time, they can still call back and forth via the CallFunction statement. The root .kb file is always the last file specified by -F at the command prompt.
-p netPort Supports the ASE networking extensions.
Arguments Value Comment
The SA-Script Interpreter
76 SA-Application Software Expert 5.0
5
Interpreter Errors
SA-Script Interpreter errors
The following table summarizes error conditions reported by the SA-Script Interpreter.
Error Explanation
A type conversion failed while attempting to pack SA-Script arguments for external routine <routine>.
The value passed as an argument to the external routine cannot be converted to the type expected by that routine.
An internal error occured while attempting to convert values returned from external routine <routine> back into SA-Script format.
This refers to an underflow condition where the value returned from the external routine did not conform to the declared type for the external routine.
Packing the argument list for external routine <routine> exceeded the maximum available storage.
The entire argument list for the external routine exceeded the 4096- byte limit imposed by the SA-Script Interpreter.
Unable to convert $UNKNOWN into a valid C/C++ value when calling external routine <routine>.
An unknown value was passed as a parameter (or as a field of a record passed as a parameter) to an external routine, and there is no default value specified for the type that the routine expects. There is no way to pass the value to the C or C++ routine.
Insufficient memory The SA-Script Interpreter is unable to allocate any additional memory.
Internal error detected at line <line #> in “<filename>”
An error condition exists within the SA-Script Interpreter. Note the file name and line number and contact Software Artistry’s Customer Support.
Index <n> out of bounds
The code attempted to access the nth item in an array or list that has less than n items in it.
Interpreter Errors
Tools and Utilities Guide 77
Unable to load <filename> Dynamic Load Library (DLL).
The named library was not found. Be sure the library exists and is in your path.
Function <name> (<filename>) is not implemented.
The SA-Script Interpreter was unable to access the named function. Be sure you have the correct version of ASE installed and that it is the only version available on your system.
An error occurred while reading file “<filename>”
This can be caused by a read-only setting on a file, a non-existant or deleted file, or a disk or network failure.
$EventParm #<n> does not exist. The valid range is 1 to <n>.
Review the valid event parameters for events in the SA-ASE 5.0 SA-Script Language Reference.
The type of EventParm #<n> (<type>) does not match the declared type (<type>).
Review the valid event parameters for events in the SA-ASE 5.0 SA-Script Language Reference.
Assignment to $EventParm #<n> illegal, because it was not passed by reference.
The $EventParm assignment was illegal. You can avoid the assignment using a field in the event handler’s instance data or a global variable.
Attempt to open file “<filename>” with an invalid mode: <mode>
Use the given internal constants ($Read, $Write, or $Create) to open files.
The formal parameter list for function <name> cannot be bound to the command-line arguments.
Be sure the arguments for the function are of the correct type. This error can also be caused by out of date .kbc files that need to be reparsed.
Unable to open file “<filename>”
This can be caused by a read-only setting on a file, a non-existant or deleted file, or a disk or network failure.
File is not a compiled Knowledgebase: <filename>
Be sure you specify the name of a .kbc (not .kb) file which is in the current directory or in one of the paths specified earlier in this chapter. For more information, see the section “Searching for .KB Files.”
Error Explanation
The SA-Script Interpreter
78 SA-Application Software Expert 5.0
5
File <filename> was parsed by an obsolete version of the parser.
Reparse the .kb file with the -b parameter (build) to eliminate this problem.
File <name>.kbc was not properly generated. Please re-parse the corresponding knowledgebase.
The .kbc file is corrupted. You must reparse.
File <filename> is out-of-date with respect to knowledgebase <name>.
Reparse the file with the -b parameter (build) to eliminate this problem.
Division by zero in <filename>
Use the SA-Script Debugger to determine where the division by zero occurs and add additional code to prevent it.
Square root of a negative number <n>
Use the SA-Script Debugger to determine why this occurs and add additional code to prevent it.
Attempt to assign an unknown value to character #<n> of string “<name>”
The SA-Script code is trying to perform an operation like:
TYPES s : string;ACTIONS s[5] := $UNKNOWN; END;
Use the SA-Script Debugger to determine why this occurs and add additional code to prevent it.
Unrecognized option: <option>
The syntax used at the command prompt for the SA-Script Interpreter was not recognized.
More than 65535 types defined within the application
Unless your .kb file is exceptionally large. this error is probably caused by an internal error or a corrupted .kbc file. Reparse and try again.
Unable to replace the string {{<reference string>}} with a value.
The reference string is invalid in some way.
Error Explanation
Interpreter Errors
Tools and Utilities Guide 79
An invalid bind parameter has been found. Either the syntax of the paramter was incorrect, or there was no parameter data to associate with the marker.
There is an error in the syntax of the SQL function call.
The entry named “<name>” has a type (<typespec>) that is not supported.
This can be caused by an internal error, an out of date, or corrupted .kbc file. Reparse and try again.
Knowledgebase <name> has no entry routine.
A valid entry routine is a procedure which meets the following requirements:
1. It is a procedure and not a func-tion
2. It is at module scope (for exam-ple, it is not nested in another rou-tine)
3. It is defined as a PUBLIC func-tion
Unable to make <drive letter> the default drive.
Be sure a drive with the given letter exists.
Unable to make “<name>” the current directory.
Be sure the given directory exists.
Unable to find a file with the name <filename>. Using <filename> instead. This behavior will not be supported in future releases.
If you specify a .kb file name in the USES section of a .kb file, it should have the same case as the file containing that .kb file. If the .kb file name does not use the same case, the SA-Script Interpreter cannot find it and the error message appears.
Error Explanation
The Interface Viewer
82 SA-Application Software Expert 5.0
6
Introduction
Overview The Interface Viewer is used to view the components of .dfc files without starting the application.
Viewing .dfc Files
Using the windowed Interface Viewer
You can open the windowed version of the Interface Viewer using either one of the following methods:
From the Start menu, point to Program, point to SA-ASE, and then choose Interface Viewer.
Result: The Interface Viewer Dialog Box appears.
To use the Interface Viewer:
1. From the File menu, choose Open.
Result: The Select resource file to view dialog box appears.
Viewing .dfc Files
Tools and Utilities Guide 83
2. Type or browse for the .dfc file you want to view and choose OK.
Result: The selected .dfc file information appears in the SA-Interface Viewer tabs.
3. Use the SA-Interface Viewer tabs to view the forms, strings, patterns, menus, and toolbars of the .dfc file.
Using the Interface Viewer from a command prompt
The command prompt version of the Interface Viewer (i-view) uses the following syntax:
i-view [.dfc file]
Result: The selected .dfc file information appears in the SA-Interface Viewer tabs.
Symbols
#ELSE parser error, 52#else statement
Interface Generator errors, 67#ENDIF parser error, 52, 53#endif statements
Interface Generator errors, 67, 69#include statement
Interface Generator errors, 69$CURRENT parser error, 51$EVENT parser error, 51$EventParm interpreter error, 77$EVENTPARM parser error, 52$EXPORT parser error, 55$HANDLE parser error, 52$NullHandler parser error, 52$UNKNOWN interpreter error, 76* (asterisk)
break point symbol, 38.dfc files
generating, 64, 65Interface Generator errors, 68
.kb file, 44
.kb filescircular usage
troubleshooting, 51parsing, 43updating, 44
.kbc filesloading
disabling in Script Interpreter, 74<name> is not a defined type parser error, 52<name> is not a field of the given record type parser
error, 52<name> is not a function or procedure parser error,
52-? command prompt flag (Interface Generator), 66-? -HELP command prompt (Script Interpreter), 74
A
-a<identifier> argument (Script Parser), 47Abort command (Debugger Run menu), 31aborting
Debugger, 31Add command (IDE Item menu), 20Add command (IDE Target menu), 17Add Target dialog box (IDE), 17adding
placeholdersfor target items, 20
project targets, 16, 17target items, 16, 19, 20
Additional Search Dirs option (Script Parser dialog box, Advanced tab), 45
Advanced tabScript Parser dialog box, 45
applicationssee also projects, 12
Argument to function is invalid parser error, 53arguments
parser errors, 60Script Interpreter errors, 76, 77Script Parser, 46, 47, 48
arraysparser errors, 57Script Interpreter errors, 76
ASE networking extensionsScript Interpreter support, 75
Assert Symbol option (Script Parser dialog box, Ad-vanced tab), 45
assigningdrives
Script Interpreter errors, 79asterisk (*)
break point symbol, 38attributes
windowsInterface Generator errors, 68
B
-b argument (Script Parser), 47break points
deleting, 39functionality of, 38setting, 39setting in event handlers, 38statement restrictions, 38temporary
Index
Index
SA-Application Software Expert 5.086
setting, 31, 38, 39triggering, 38
BreakPoint statement, 39BreakPoint statements, 31Browse parse option (Script Parser dialog box, Parser
tab), 44Build command (IDE Item menu), 24Build menu commands (IDE)
Rebuild All, 24Rebuild KB, 26Rebuild Target, 24Update All, 25Update KB, 26Update Target, 25
Build parse option (Script Parser dialog box, Parser tab), 44
Build programIDE, 14
buildingitems, 23, 24knowledgebases, 26, 44versus updating, 23
buttonsInterface Generator errors, 69
C
-c command prompt (Script Interpreter), 74-c<drive> <path> argument (Script Parser), 49changing
text editors for target items, 22characters
Interface Generator errors, 67Script Interpreter errors, 78
circular usage.kb files
troubleshooting, 51Clear command (IDE Target menu), 18clearing
target items, 18Close command (Debugger Run menu), 31closing
Debugger, 31projects, 16variable window in Debugger, 35
codebreak points
deleting, 39functionality of, 38setting, 39setting in event handlers, 38statement restrictions, 38temporary
setting, 31, 38, 39triggering, 38
embedded in text filesconverting to binary format, 42
execution pathtracing in Debugger, 36, 37
IMPORT declarationsparsing, 50
reorganizingin Debugger, 32
stepping in, 36stepping into, 36, 37stepping out, 36stepping out of, 37stepping over, 36, 37viewing
in Debugger, 33, 34, 35Code Page option (Script Parser dialog box, Ad-
vanced tab), 46command line switches
Interface Generator errors, 67Script Interpreter
displaying, 74command prompt arguments
Script Interpreter, 73, 74, 75Script Parser, 46, 47, 48
command prompt flagsInterface Generator, 66
command promptsScript Interpreter errors, 78
commands (Debugger)Run menu, 31
Step In, 36Step Out, 37
commands (IDE)Build menu
Rebuild All, 24Rebuild KB, 26Rebuild Target, 24Update All, 25Update KB, 26Update Target, 25
Item menuAdd, 20Build, 24Remove, 21Run, 27
Options menuDebug, 31Editor, 23Run Directory, 27
Target menuAdd, 17Clear, 18Delete, 19Edit, 17
commas
87SA-Script Language Reference
Interface Generator errors, 68parser error, 52
commentsparser errors, 60
conditional translationsknowledgebases, 45
configurationsIDE
running Debugger automatically during knowl-edgebase execution, 31
Connect String option (Script Parser dialog box, Ad-vanced tab), 45
Constant expression required parser error, 53constant parser error, 53constant values
Interface Generator errors, 67parser errors, 59
constantsInterface Generator errors, 68
controlsbutton controls
Interface Generator errors, 69MLE controls
Interface Generator errors, 69radio button controls
Interface Generator errors, 69-convert command prompt flag (Interface Genera-
tor), 66converting
code embedded in text filesto binary format, 42
filesfrom source format to object format, 14
typesScript Interpreter errors, 76
creatingprojects, 12, 15
Cross-Reference option (Script Parser dialog box, Advanced tab), 45
D
-d command prompt (Script Interpreter), 74-d command prompt flag (Interface Generator), 66-d<identifier> argument (Script Parser), 47data types
see types, 58databases
dataimporting, 50
DBMS(Database Management System)
connection stringsetting to string, 45
Debug command (IDE Options menu), 31
Debuggeraborting, 31closing, 31code reorganize changes, 32DLL file, 31functionality of, 30Globals tab, 34keyboard commands, 36Lexical tab, 34Locals tab, 34opening, 30, 31setting break points, 38, 39single-step mode, 30stepping into code, 36, 37stepping out of code, 37stepping over code, 37viewing code in, 33, 34, 35
debuggingdialog boxes, 39windows, 39
Delete command (IDE Target menu), 19deleting
break points, 39target items, 18, 21targets, 19
Deny Symbol option (Script Parser dialog box, Ad-vanced tab), 45
dfc files, 64, 65Interface Generator errors, 68
dialog boxesdebugging, 39
dialog boxes (Debugger)Variable Viewer, 34
dialog boxes (IDE)Add Target, 17Edit Target, 18Options, 23Select File to Add, 20Set Working Directory, 27
dialog boxes (Script Parser)Script Parser, 43, 44
directoriesparser errors, 59Script Interpreter errors, 79
displayingcommand line switches
for Script Interpreter, 74knowledgebases
in files, 33division by zero
Script Interpreter errors, 78DlgCreate statement, 39DLLs
preloading during initializationwith Script Interpreter, 74
Index
SA-Application Software Expert 5.088
Script Interpreter errors, 77drives
assigningScript Interpreter errors, 79
E
-e<file> argument (Script Parser), 48-e[filename] command prompt flag (Interface Gener-
ator), 66Edit command (IDE Target menu), 17Edit program
IDE, 13Edit Target dialog box (IDE), 18editing
files, 13items, 21, 22targets, 17, 18
Editor command (IDE Options menu), 23embedding
BreakPoint statementsin code, 31
entitiesInterface Generator errors, 68
entry routinesScript Interpreter errors, 79
Error Message Filename option (Script Parser dialog box, Advanced tab), 45
error messagesScript Parser
specifying files for, 45errors
checking for semicolon misuse, 51Interface Generator, 67, 68, 69Interface Generator errors
#else statements, 67#endif statement, 69#endif statements, 67#include statement, 69constants, 67, 68DISPLAY keyword, 68entities, 68field input overriden by pattern definition, 69field names, 68field qualifiers, 69filename, 67form name not defined, 69keywords, 68missing commas, 68missing semicolons, 68MLE controls, 69multiple default buttons, 69multiple pattern fill characters, 69pattern masks different lengths, 69preprocessor directive, 67
radio buttons, 69string-related, 67strings, 68subform not defined, 70unable to open log files, 70unable to open parsed file, 68unkown character, 67unkown command line switch, 67window attributes, 68
internal errorsScript Interpreter, 76
interpreter errors$EventParm, 77$UNKNOWN, 76arguments for external routine exceed storage
capacity, 76array item out of bounds, 76division by zero, 78file not a compiled knowledgebase, 78file not properly generated, 78file out of date with knowledgebase, 78file parsed by obsolete parser version, 78function not implemented, 77function parameter cannot be bound to com-
mand line arguments, 77insufficient memory, 76internal error at specified line, 76internal error during value conversion, 76invalid bind parameter found, 79invalid file opening mode, 77knowledgebase has no entry routine, 79reading files, 77square root of negative number, 78type conversion, 76type not supported, 79types defined exceed application limit, 79unable to create default directory, 79unable to create default drive, 79unable to find file, 80unable to load DLL, 77unable to open file, 77unable to replace string with value, 79unknown character value assigned, 78unrecognized command prompt option, 78
parser errors#ENDIF, 53$CURRENT, 51$ELSE, 52$ENDIF, 52$EVENT, 51$EVENTPARM, 52$EXPORT, 55$HANDLE, 52$NullHandler, 52<name> is not a defined type, 52
89SA-Script Language Reference
<name> is not a field of the given record type, 52
<name> is not a function or procedure, 52Argument to function is invalid, 53arguments, 60arrays, 57comma (,) is missing, 52comments, 60constant, 53Constant expression required, 53constant values, 59directories, 59event handler, 53, 54event handlers, 58event-handling function is required, 53expressionr, 54EXTERNAL routine, 61file write error occurred, 52filenames, 61FOR loop, 55FORWARD declaration, 54fread() in flex scanner failed, 54function, 55IMPORT statements, 59INTERNAL ERROR, 55Invalid coercion, 55Invalid declaration, 55Invalid expression, 55Invalid expression type, 55Invalid field annotation, 55Invalid identifier, 56Invalid operand, 56Invalid option, 56Invalid pseudofield annotation, 56Invalid redeclaration of symbol, 56Invalid statement, 56Invalid type specification, 56keywords, 60knowledgebases, 56lists, 57memory, 59parameter passing protocol must be specified,
53parameters, 56preprocessor directives, 60procedures, 57return type declaration, 54selectors, 57, 59strings, 60symbols, 57types, 58Unable to locate file, 59Unable to open file, 59unexpected delimiter was encountered, 53variables, 60
WHEN, 53, 56WinSetMousePointer function, 61
Script Interpreter errors, 76, 77, 78, 79Script Parser, 51, 52, 53, 54, 55, 56, 57, 58, 59,
60event handler parser error, 53, 54event handlers
identifying, 39parser errors, 58setting break points in, 38stepping out of in Debugger, 37
event-handling function is required parser error, 53events
Script Interpreter errors, 77windows
tracing execution paths, 39executing
files, 14execution path
codetracing in Debugger, 36, 37
expression parser error, 54EXTERNAL routine
parser errors, 61
F
-f <path> <module>.KB argument (Script Parser), 49
-f command prompt (Script Interpreter), 75fields
qualifiersInterface Generator errors, 68, 69
File Name parse option (Script Parser dialog box, Parser tab), 44
file write error occurred parser error, 52filenames
Interface Generator errors, 67parser errors, 61Script Interpreter errors, 80
filesconverting from source format to object format,
14editing, 13Interface Generator errors, 67log files
Interface Generator errors, 70opening
Script Interpreter errors, 77reading
Script Interpreter errors, 77running, 14
findingknowledgebases, 72source text, 42
Index
SA-Application Software Expert 5.090
flagsInterface Generator command prompt, 66
FOR loop parser error, 55forms
Interface Generator errors, 69subforms
Interface Generator errors, 70FORWARD declaration parser error, 54fread() in flex scanner failed parser error, 54function parser error, 55functions
recursive characteristics of, 35Script Interpreter errors, 77stacks
viewing in Debugger, 35stepping into, 35, 36, 37stepping out of, 35, 37stepping over, 37viewing
in Debugger, 34WinSetMousePointer
parser errors, 61
G
generating, 64, 65dfc files, 64, 65
Globals tabDebugger, 34
H
-help/? argument (Script Parser), 49
I
IDE(Integrated Development Environment), 11configurations
running Debugger automatically during knowl-edgebase execution, 31
functionality of, 12programs
Build, 14Edit, 13Run, 14
projects, 12, 13closing, 16creating, 15opening, 15saving, 15saving to different name, 16targets, 13
-ide argument (Script Parser), 49-IDE command prompt flag (Interface Generator),
66identifying
event handlers, 39IMPORT statements, 50
database/connection informationoverriding, 50
parser errors, 59importing
database data, 50InputLength statement
Interface Generator errors, 69Integrated Development Environment
see IDE, 11Interface Generator
command prompt flags, 66errors, 67, 68, 69
#else statements, 67#endif statement, 69#endif statements, 67#include statement, 69constants, 67, 68entities, 68field input overriden by pattern definition, 69field names, 68field qualifiers, 69filename, 67form name not defined, 69missing commas
, 68missing semicolons, 68MLE controls, 69multiple default buttons, 69multiple fill characters, 69pattern masks different lenths, 69preprocessor directive, 67radio buttons, 69string-related, 67subform not defined, 70unable to open log files, 70unable to open parsed file, 68window attributes, 68
opening, 64starting
from command prompt, 64Interface Generator errors
DISPLAY keyword, 68keywords, 68strings, 68
Interface Viewer, 82opening, 82
INTERNAL ERROR parser error, 55internal errors
Script Interpreter, 76
91SA-Script Language Reference
interpreter errors$EventParm, 77$UNKNOWN, 76arguments for external routine exceed storage ca-
pacity, 76array item out of bounds, 76division by zero, 78file not a compiled knowledgebase, 78file not properly generated, 78file out of date with knowledgebase, 78file parsed by obsolete parser version, 78function not implemented, 77function parameter cannot be bound to command
line arguments, 77insufficient memory, 76internal error at specified line, 76internal error during value conversion, 76invalid bind parameter found, 79invalid file opening mode, 77knowledgebase has no entry routine, 79reading files, 77square root of negative number, 78type conversion, 76type not supported, 79types defined exceed application limit, 79unable to create default directory, 79unable to create default drive, 79unable to find file, 80unable to load DLL, 77unable to open file, 77unable to replace string with value, 79unknown character value assigned, 78unrecognized command prompt option, 78
Invalid coercion parser error, 55Invalid declaration parser error, 55Invalid expression parser error, 55Invalid expression type parser error, 55Invalid field annotation parser error, 55Invalid identifier parser error, 56Invalid operand parser error, 56Invalid option parser error, 56Invalid pseudofield annotation parser error, 56Invalid redeclaration of symbol parser error, 56Invalid statement parser error, 56Invalid type specification parser error, 56Item menu commands (IDE)
Add, 20Build, 24Remove, 21Run, 27
items, 13(IDE project targets), 12adding, 16, 19, 20building, 23, 24clearing, 18
editing, 21, 22placeholders, 20rebuilding, 24removing from targets, 21running, 27see also knowledgebases, 25updating, 25
K
kbc filesloading
disabling in Script Interpreter, 74with Script Interpreter, 75
keyboard commandsDebugger, 36
keywordsInterface Generator errors, 68parser errors, 60
knowledgebasesbuilding, 26, 44conditional translations, 45displaying
in files, 33finding, 72parse options
setting, 44parser errors, 56running, 30see also items, 25see also modules, 33updating, 26
L
-l argument (Script Parser), 48-l command prompt (Script Interpreter), 74-l+ argument (Script Parser), 48-l<file> argument (Script Parser), 48-l[filename] command prompt flag (Interface Gener-
ator), 66Lexical tab
Debugger, 34Listing Filename option (Script Parser dialog box,
Advanced tab), 46lists
parser errors, 57Script Interpreter errors, 76
loadingkbc files
disabling in Script Interpreter, 74with Script Interpreter, 75
Locals tabDebugger, 34
Index
SA-Application Software Expert 5.092
log filesInterface Generator errors, 70
log messageswriting with Script Interpreter, 74
M
-m argument (Script Parser), 47-M command prompt flag (Interface Generator), 66memory
parser errors, 59Script Interpreter errors, 76
MLE controlsInterface Generator errors, 69
modulessee also knowledgebases, 33
N
namingtargets, 17
O
-o command prompt (Script Interpreter), 74-o:<directory> argument (Script Parser), 49-o<directory> argument (Script Parser), 49-o=<directory> argument (Script Parser), 49opening
Debugger, 30, 31files
Script Interpreter errors, 77Interface Generator, 64Interface Viewer, 82projects, 15Script Parser, 43text editors
for project target items, 22variable viewer window in Debugger, 35
Options dialog box (IDE), 23Options menu commands (IDE)
Debug, 31Editor, 23Run, 27
overridingdatabase/connection information
in IMPORT statements, 50
P
-p command prompt (Script Interpreter), 75-P command prompt flag (Interface Generator), 66-p=ansi argument (Script Parser), 49
-p=oem argument (Script Parser), 49-pansi argument (Script Parser), 49parameter parser errors, 56parameter passing protocol must be specified parser
error, 53parameters
Script Parser arguments, 46parse options
knowledgebasessetting, 44
parser errors#ENDIF, 53$CURRENT, 51$ELSE, 52$ENDIF, 52$EVENT, 51$EVENTPARM, 52$EXPORT, 55$HANDLE, 52$NullHandler, 52<name> is not a defined type, 52<name> is not a field of the given record type, 52<name> is not a function or procedure, 52Argument to function is invalid, 53arguments, 60arrays, 57comma (,) is missing, 52comments, 60constant, 53Constant expression required, 53constant values, 59directories, 59event handler, 53, 54event handlers, 58event-handling function is required, 53expression, 54EXTERNAL routine, 61file write error occurred, 52filenames, 61FOR loop, 55FORWARD declaration, 54fread() in flex scanner failed, 54function, 55IMPORT statements, 59INTERNAL ERROR, 55Invalid coercion, 55Invalid declaration, 55Invalid expression, 55Invalid expression type, 55Invalid field annotation, 55Invalid identifier, 56Invalid operand, 56Invalid option, 56Invalid pseudofield annotation, 56Invalid redeclaration of symbol, 56
93SA-Script Language Reference
Invalid statement, 56Invalid type specification, 56keywords, 60knowledgebases, 56lists, 57memory, 59parameter passing protocol must be specified, 53parameters, 56preprocessor directives, 60procedures, 57return type, 54selectors, 57, 59strings, 60symbols, 57types, 58Unable to locate file, 59Unable to open file, 59unexpected delimiter was encountered, 53variables, 60WHEN, 53, 56WinSetMousePointer function, 61
Parser tabScript Parser dialog box, 44
parsing.kb files, 43code
with IMPORT declarations, 50parsing code that contains, 50password protection
Script Parser, 50patterns
Interface Generator errors, 69placeholders
(target items)adding, 20
-poem argument (Script Parser), 49preprocesor directives
Interface Generator errors, 67preprocessor directives
parser errors, 60procedure parser errors, 57programs
IDEBuild program, 14Edit program, 13Run program, 14
Script programssetting working directory for, 27
projects(IDE), 12, 13building process, 12closing, 16creating, 15opening, 15saving, 15
saving to different name, 16see also applications, 12see also targets, items, 12targets, 13
adding, 16, 17clearing, 18deleting, 19editing, 17, 18naming, 17rebuilding, 24usage requirements, 16
updating, 25purpose, 82
Q
-q argument (Script Parser), 48-Q command prompt flag (Interface Generator), 66qualifiers
field qualifiersInterface Generator errors, 68
fieldsInterface Generator errors, 69
R
radio button controlsInterface Generator errors, 69
readingfiles
Script Interpreter errors, 77Rebuild All command (IDE Build menu), 24Rebuild KB command (IDE Build menu), 26Rebuild Target command (IDE Build menu), 24rebuilding
items, 24knowledgebases, 26targets, 24
refreshingvariables
in Debugger, 34, 35Remove command (IDE Item menu), 21removing
target items, 21reorganizing
codein Debugger, 32
return type parser error, 54routines
entry routinesScript Interpreter errors, 79
EXTERNALparser errors, 61
Script Interpreter errors, 76
Index
SA-Application Software Expert 5.094
Run command (IDE Item menu), 27Run command (IDE Options menu), 27Run menu commands (Debugger), 31
Step In, 36Step Out, 37
Run programIDE, 14
runningfiles, 14items, 27knowledgebases, 30Script Parser, 46
S
-S optionScript Parser, 50
-s<string> argument (Script Parser), 49SA-ASE
(Software Artistry-Application Software Expert)document set, 9, 10
SA-Scriptsee Script, 27
SA-Script Debuggersee Debugger, 30
SA-Script IDEsee IDE, 11
SA-Script Interpretersee Script Interpreter, 72
SA-Script Parsersee Script Parser, 42
savingprojects, 15projects to different name, 16
Scriptfunctions
recursive characteristics of, 35programs
setting working directory for, 27Script Interpreter, 72
adding directories for knowledgebase searches, 73ASE networking extension support, 75changing initial drive/directory, 74command line switches
displaying, 74command prompt arguments, 73, 74, 75errors, 76, 77, 78, 79preloading DLLs during initialization, 74starting in trace mode, 73writing log messages, 74
Script Parser, 42arguments, 46, 47, 48error messages
specifying files for, 45errors, 51, 52, 53, 54, 55, 56, 57, 58, 59, 60
finding source text, 42opening, 43password protection, 50running, 46-S option, 50troubleshooting .kb file circular usage, 51
Script Parser dialog box, 43, 44searching
knowledgebases, 72Select File to Add dialog box (IDE), 20selector parser errors, 57selectors
parser errors, 59semicolons
error generation, 51Interface Generator errors, 68
Set Working Directory dialog box (IDE), 27setting
break points, 39in event handlers, 38
parse optionsfor knowledgebases, 44
temporary break points, 38, 39temporary break points in code, 31working directory
for Script programs, 27single-step mode
Debugger, 30source code
see code, 30source text
finding, 42SQL function calls
Script Interpreter errors, 79square roots of negative numbers
Script Interpreter errors, 78starting
Interface Generatorfrom command prompt, 64
Script Interpreterin trace mode, 73
statements#else
Interface Generator errors, 67#end if statements
Interface Generator errors, 69#endif statements
Interface Generator errors, 67#include statements
Interface Generator errors, 69BreakPoint, 31, 39DlgCreate, 39IMPORT
database/connection informationoverriding, 50
95SA-Script Language Reference
parsing code that contains, 50InputLength
Interface Generator errors, 69WinCreate, 39
Step In command (Debugger Run menu), 36Step Out command (Debugger Run menu), 37stepping in code, 36stepping into code, 36, 37stepping into functions, 35stepping out of code, 36, 37stepping out of functions, 35stepping over code, 36, 37strings
Interface Generator errors, 67parser errors, 60Script Interpreter errors, 78, 79
subformsInterface Generator errors, 70
symbolsparser errors, 57
T
-t command prompt (Script Interpreter), 73Target menu commands (IDE)
Add, 17Clear, 18Delete, 19Edit, 17
targets, 13(IDE projects), 12adding, 16, 17deleting, 19editing, 17, 18items, 13
adding, 16, 19, 20building, 23, 24clearing, 18editing, 21, 22placeholders, 20rebuilding, 24removing, 21running, 27updating, 25
knowledgebasebuilding, 26updating, 26
naming, 17rebuilding, 24updating, 25usage requirements, 16
temporary break pointssetting, 31, 38, 39
text boxespatterns
Interface Generator errors, 69text editors, 13
changing for target items, 22opening
for project target items, 22tracing code execution paths
in Debugger, 36, 37triggering
break pointsin code, 38
troubleshootingcircular usage
in .kb files, 51types
convertingScript Interpreter errors, 76
parser errors, 58Script Interpreter errors, 79
U
-u<path> argument (Script Parser), 47-u<path> command prompt (Script Interpreter), 73Unable to locate file parser error, 59Unable to open file parser error, 59unexpected delimiter was encountered parser error,
53unknown character, 67unknown command line switch, 67Update All command (IDE Build menu), 25Update KB command (IDE Build menu), 26Update parse option (Script Parser dialog box, Parser
tab), 44Update Target command (IDE Build menu), 25updating
.kb files, 44items, 25knowledgebases, 26projects, 25targets, 25versus building, 23
V
Variable Viewer dialog box (Debugger), 34variable viewer window
opening in Debugger, 35variable window
closing in Debugger, 35variables
parser errors, 60refreshing
in Debugger, 34, 35viewing
Index
SA-Application Software Expert 5.096
in Debugger, 34viewing
codein Debugger, 33, 34, 35
function stacks in Debugger, 35functions
in Debugger, 34variables
in Debugger, 34
W
WHEN parser error, 53, 56WinCreate statement, 39windows
attributesInterface Generator errors, 68
debugging, 39events
tracing execution paths, 39WinSetMousePointer function
parser errors, 61
X
-x<database> argument (Script Parser), 48
Recommended