Function Executor Concepts

---

This section contains the following topics:

• Overview
• What Function Executor Can Do
• Features Unique to the Win32 Function Executor
• Automatic Mode in 32-bit Function Executor
• Where to Learn More

Overview

The 16-bit and 32-bit Function Executors run on Win16 and Win32 platforms for the Pervasive.SQL Server and Workgroup products. With these interactive utilities, you can learn how Btrieve operations work. By allowing execution of Btrieve operations one at a time, the Function Executors enable application developers to simulate the operations of a Btrieve application. This simulation can isolate the database calls from the rest of your application, which can help in testing and debugging your program.

The Function Executors are primarily tools for application developers; this chapter assumes a basic knowledge of Btrieve operations. For more information about Btrieve operations, refer to the API Programmer's Reference that is available with the Pervasive.SQL Software Developer's Kit (SDK).

What Function Executor Can Do

• Perform Btrieve operations while monitoring the contents of memory structures.
• Allow you to capture a series of Btrieve operations and save them as a history file for later playback
• Display the Btrieve version for clients, and local and remote engines.
• Display the Btrieve characteristics of data files and allow you to save those characteristics as a template (description file) or create a new file based on those characteristics. See File Statistics GUI Reference for more information.

Features Unique to the Win32 Function Executor

The Win32 version of the Function Executor includes all the functionality of the Win16 utility as well as some additional features. Many ways of performing familiar Win16 operations are different in the Win32 version. These include the features listed below.

• Editor Status Bar
• Statistics
• Get and GetExt
• Transaction Toolbar
• Login Dialog
• History Log
• Viewing as Any Data Type

Editor Status Bar

The status bar contains these elements:

	The last/current status code is shown in the editor window's status bar at the bottom of the window for the open file, and appears red if the last status was not zero.
	Placing the mouse cursor over the status code shows a description of the status and what operation caused it. You can also click on the display in red in order to display the full help for the status code. See To get help for a status code for more information.
	When your cursor is in the input area on the main window of the Function Executor, the status bar displays the offset within the buffer: the hex, the decimal, and the ASCII value of the byte you are presently on.
	The status bar also indicates how many operations have been performed when there are multiple items in the queue. Normally this displays 1 of 1, but if you are executing multiple operations, it will display the count as the operations are executed.
	The status bar also displays when you are in a transaction.

Statistics

Clicking on the File Statistics icon displays a dialog box listing the currently-open file's statistics. You can print these statistics to a text file or save them to a description file usable by BUTIL -CREATE (you may also create a new blank file with the same characteristics.) Previously, these items had to be manually picked out of the data buffer after executing a Btrieve operation 15.

Get and GetExt

From the Get menu, you can retrieve the First, Next, Previous, and Last records in the table. The GetExt menu includes the Goto Percent, Get Position, and Find Percent commands.

The Get and GetExt commands are available from both the menu bar and toolbar. The toolbar offers Step (Physical) and Get (Logical), allowing you to move either through the natural order of the file (Physical) or in a specific order (Logical).

Goto Percent allows you to choose whether to jump to a point within the physical layout of the file, or down any key path, limited to the keys defined in the file. You can also set lock biases using the option buttons in the Locks group box.

Find Percentage is the opposite of Goto Percent. It tells you how far into the data you are, depending on whether you are stepping through the file logically or physically.

Transaction Toolbar

The Transaction toolbar lets you start, stop, and abort transactions. You can set all aspects of the Transaction API through this toolbar, and the operation is executed immediately. The Transaction status also appears on the main window status bar, since it affects all open files for the client ID.

Login Dialog

The Login dialog allows you to perform the Btrieve login operation via a GUI interface.

See the following topics for more information about the Login dialog:

• Login GUI Reference
• Login Tasks
• Pervasive.SQL Databases
• Pervasive.SQL Security

History Log

When you perform operations using the Function Executor utility, they are recorded in a History log. You can use this log to perform the operations contained therein, or save the history as a file that you can later reload and step through.

See the following topics for more information about the History log:

• History GUI Reference
• History Tasks

Viewing as Any Data Type

When a file is open, you can right-click on any position in the buffer and select Show As. A dialog appears in which you can view the bytes at the chosen buffer position as any data type.

Table 12-1 lists controls available only in the Win32 version of the Function Executor.

 
Table 12-1 Win32-Only Function Executor Controls

Control	Description
Repeat	Allows you to repeat commands.
Create	Allows you to create a new file.
File Statistics	Gives information from the BSTAT function. You can print these statistics.
MDI	The Multiple Document Interface permits the opening of multiple files.
Reset	Reset Client ID
Stop	Btrieve Stop
Version	Btrieve Version

Automatic Mode in 32-bit Function Executor

For each open file (see Application Window (32-Bit) ), you have the option of performing Btrieve operations with or without the assistance of Function EXECUTOR. You do not need to make any configuration changes to use one method or the other. Whether you use automatic mode or manual mode depends on which GUI elements you use as shown in Figure 12-1.

 
Figure 12-1 Automatic Mode vs. Manual Mode

---

Note
Selections from the menus (see Application Window (32-Bit) ) also are part of the automatic mode.

---

When you click a button in the automatic area, the following assistance is provided by the utility:

• Data buffers are set automatically to prevent Status code 22.
• Assumptions are made about certain operations. For example, if you select continuous operations from the menu, Function Executor assumes that it should put the file in focus under continuous operations; it does not require that the Data Buffer

Where to Learn More

The Function Executor is a valuable tool for program developers, but it assumes you have a working knowledge of Btrieve fundamentals. You should have knowledge of the following before attempting to understand all the features of this utility:

• Btrieve Fundamentals in Pervasive.SQL Programmer's Guide

  http://www.pervasive.com/library/index.asp?_pub=GDE&_topic=BTRIEVE_FUNDAMENTALS

• Btrieve Operations reference in API Programmer's Reference

  http://www.pervasive.com/library/index.asp?_pub=API

• For information about security models for Btrieve:

  Pervasive.SQL Security