sa-application tools and software expert version 5.0

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.


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


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


•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.


•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


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


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


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


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


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


• 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


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


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.


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.


• 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


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


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.


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.


• 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


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


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


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.


Rebuilding all the items in a project

To build all the items in a project:

• From the Build menu, choose Rebuild All.


Updating Your Project


Updating Your Project

Overview You can update just the targets in your application or the entire project file, including associated targets and items.


• 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


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.


• 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


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.

The SA-Script IDE


1


•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


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


•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.



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;


x :=c *(a+b); x :=c*a+b;

Working with Code


• 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.


3 June 1997 6, 3, 1997



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


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.



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


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.



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


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.



2


•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


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



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.


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.




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.



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.



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.



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.



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.




-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.)




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


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.



3

$EVENTPARM is not defined in the scope of <function>.


$HANDLE is not defined in the scope of <function>.


$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



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



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



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



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



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



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



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



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



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



3


•Introduction

•Generating .dfc Files


•Interface Generator Errors

4The Interface Generator

The Interface Generator


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


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.



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 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



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.



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



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



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


•Introduction

•Searching for .KB Files


•Interpreter Errors

5The SA-Script Interpreter

The SA-Script Interpreter


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




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.



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.




-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.




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


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



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


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



5


•Introduction

•Viewing .dfc Files

6The Interface Viewer

The Interface Viewer


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


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.

The Interface Viewer


6

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


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


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


<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


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


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


log filesInterface Generator errors, 70

log messageswriting with Script Interpreter, 74

M

-m argument (Script Parser), 47-M command prompt flag (Interface Generator), 66memory


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


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


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


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


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


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

sa-application tools and software expert version 5.0

Documents