What's New

This entry provides quick reference to new features in SmartWare.

CREATE_OBJECT
REF
ACTXERROR
ACTXERRORTEXT
Member Operator
ViewLoad Event
ViewUnload Event
CurrentRecord Event
Data-file Type
Converting Between Data-types
Server Transactions
Attach Project-File
Create ActiveX
Replicate ActiveX
Running RAD Apps


DLL

Type: Command
Scope: All
OS: Windows (Win32S), Windows95, NT

The DLL group of commands provides SPL access to 32 bit Windows (Win32S, Windows95, and NT) Dynamic Link Libraries (DLL). For example, an SPL program can display a message dialog box by calling the Windows USER32.DLL library function: MessageBoxA.

NOTE: Since DLL functions vary widely, it is up to the programmer to determine the appropriate calling conventions and return values. Use of DLL functions requires great care. If a DLL function is called with the wrong number of arguments, the stack may become corrupted and the subsequent operation of SmartWare will be unpredictable. There is no error-checking or other protection for this.


Using DLLs - General Information

Basically, there are three library commands. The first step in calling a DLL function is to load the library.

        DLL LOAD "dll_name" #dll_handle

If the command is successful, a value greater than zero is placed in the handle variable.

The handle is then used to call functions in the loaded library. There are actually several variations of the CALL command, but in its most basic form, only the handle and function name are required.

        DLL CALL #dll_handle FUNCTION "function_name"

Note that the details for calling DLL functions and getting return values from them can be complex. Refer to the DLL CALL command for information.

When a DLL is no longer needed, the library can be unloaded.

        DLL UNLOAD #dll_handle

If left loaded, libraries are automatically unloaded when SmartWare exits.

DLL CALL
DLL LOAD
DLL UNLOAD
DLL Callback Functions


DLL Callback Functions

Callbacks provide SPL control over executing Windows Dynamic Link Libraries (DLLs). If you are not familiar with the DLL commands, read that section before continuing here.

NOTE: Due to the way Windows handles messages, using callbacks with some standard DLL functions may result in unpredictable behavior - possibly halting the program. The DialogBox function, which uses callbacks, is an example of this. -There will be more information in the next version of this document.

Because of the limitation described above, DLLs should be created by the programmer. For this reason, the C source code for the DLLSAMP library has been included in the example below.


Using DLL Callbacks - General Information

DLL callbacks are set up in SPL programs with the CALLBACK_CREATE function before calling a DLL function. This creates a stub and "announces" that a named public function can be accessed by the DLL.

Typically, the execution path taken is: an SPL program loads a library, names a public function as a callback and then calls a DLL function (that can handle callbacks). The DLL function, in turn, does whatever it needs to do - including calling the public SPL function named with CALLBACK_CREATE.

Callbacks are removed with the CALLBACK_DELETE function.

Example (part 1)

In the SPL code example, the DLLSAMP library is loaded, the public function CallbackTest is announced and the DLL function _dll_entry is called twice.

The CallbackTest function is also defined in the same program. It's job is to find out whether the DLL function was passed the message "First Call" or some other message. If "First Call" is detected, the AX register is set to one, otherwise AX is set to zero.

The first _dll_entry call passes the "First Call" message and so the CallbackTest function places a one in the AX register. The "magic" message is not passed in the second call to _dll_entry thus, zero is placed in AX.

Note that callback functions must have one and only one parameter. This parameter is a buffer variable which is UNPACKed and read within the callback. In this way, multiple parameters are passed to the callback.

     '------- SPL Code Example ------------------------------
     PUBLIC CallbackTest(1)

     MAIN
     LOCAL $msg #dllhandle #callback_test

        DLL LOAD "dllsamp.dll" #dllhandle

        #callback_test = CALLBACK_CREATE( "CallbackTest", 1, 0 )

        $msg = "First Call"
        DLL CALL #dllhandle FUNCTION "_dll_entry" STACK "PP" DOSPTR($msg) #callback_test
        $msg = "Second Call"
        DLL CALL #dllhandle FUNCTION "_dll_entry" STACK "PP" DOSPTR($msg) #callback_test

        CALLBACK_DELETE( #callback_test )

        DLL UNLOAD #dllhandle

     END MAIN

     '-------------------------------------------------------
     FUNCTION CallbackTest( $stack )
     LOCAL $msg $pmsg

        UNPACK $stack "P" $pmsg
        PEEK 0 $pmsg "S" $msg

        IF $msg == "First Call"
        SETREG(ax, 1)
        ELSE
        SETREG(ax, 0)
        END IF
     END FUNCTION

Example (part 2)

The API entry function, LibMain simply displays a message box when it is loaded and unloaded. In practice, this would not be done.

The dll_entry function executes the SPL callback function (in this case, CallbackTest) and passes it a message (CallbackTest takes one parameter). The return value from the callback is tested (in this case, the value is one when the passed message is "First Call"). The buf variable is then given the value "Callback returned 1" or "Callback failed" based on this test. Finally, the MessageBox function is called to display the results.

     '------- DLL Source Example ----------------------------
     #include<stdio.h>
     #include<windows.h>

     int     global_var = 1;

     int APIENTRY LibMain(HANDLE hdll, DWORD reason, LPVOID reserved)
     {
        switch (reason) {
        case DLL_PROCESS_ATTACH:
        MessageBox(NULL, "DLL_PROCESS_ATTACH", "Load DLL", MB_OK);
        break;
        case DLL_PROCESS_DETACH:
        MessageBox(NULL, "DLL_PROCESS_DETACH", "Unload DLL", MB_OK);
        }
        return (1);
     }

     void   cdecl dll_entry(char *msg, int   cdecl (*callback)(char*))
     {
        charbuf[80];

        if ((*callback)(msg) == 1)
        sprintf(buf, "Callback returned 1");
        else
        sprintf(buf, "Callback failed");

        MessageBox(NULL, buf, msg, MB_OK);
     }

CALLBACK_CREATE
CALLBACK_DELETE


Common System Features

This entry provides a brief explanation of the commands associated with Help, Remember, Tools, and Quit keywords.


Help Commands

Help commands invoke various types of on-line help information. On-line help includes context-sensitive help information and help for error messages.
NOTE: To leave on-line help and return to the module menu, press F10.


Help About-Help

SmartWare has extensive on-line help that displays context-sensitive help information from any menu or user-input level. The on-line help also provides information for all program error messages. The text for the on-line help is derived from the reference chapters of the printed documentation.

As in the printed documentation, on-line help is divided into two broad categories: common and module. The common help includes information that is common to all modules and is derived from the Software System Manual, the Project Processing Manual, and the Formula Reference Manual. Common help is available from both the Main Menu and from within a module.

The module help includes the information specific to the particular module in which you are working and is derived from the corresponding module manual. Module help is available only from within the module.

In addition to the help text, there is a six-level table of contents and a two-level index through which you can select a specific item of help information.

On-line help can be accessed either through the Help keywords or by pressing F1. When you press F1, the system displays the help text for the keyword or option that is highlighted, or the error message you received. By selecting Help from the keyword menu, you have a variety of options for receiving on-line help. For example, you can elect to view the table of contents or the index, from which you can choose a topic. You may also specify an error number for which you want help information.

You can view on-line help text in any of the following situations:
*** You've begun the process of building a command statement and you don't understand each option. Press F1. The help text for the highlighted keyword or option appears at the top of the screen.
** Using the table of contents or index, you select a particular subject. The help text for that subject appears at the top of the screen.
** You've received an error message and you need information in order to correct the problem. Press F1 while the error is still displayed. The text relating to the error message appears at the top of the screen.
** You want information about a particular error message. Select the Help On-Error command and enter the error number. The text relating to the error message appears at the top of the screen.

When you access on-line help, the Control Area of the screen displays a menu of keys to use.

Key | Function
F3 | Displays the Index at Level 1. Press F3 again to view two levels of detail.
F4 | Displays the Table of Contents. Pressing F4 additional times provides additional levels of detail to the Table of Contents.
F7 | Allows you to search the index for specific words or characters.
F8 | Allows you to search the help text for specific words or characters.
F9 | Repeats a search command. Also allows you to page through the help text of index entries.
F10 | Exits on-line help.
Home | Returns to the previous entry
Ctrl-Home | Returns to the original entry.

Help information for each topic always begins at the top of the screen. Subject headings are highlighted so that they are easily identified. In some instances, a single help text paragraph or section will contain information about several related command options. Since help information for a topic may continue on subsequent screens, be sure to read to the next command or option heading. Use Down-Arrow or Page-Down to scroll downward. Use Up-Arrow or Page-Up to scroll upward.

The help feature keeps a record of the last ten topics you display, as well as the original topic. Therefore, you may jump from topic to topic and back again, if necessary. To return to the original topic, press Ctrl-Home. To return to the previous topic, press Home.


Related Topics

The help text identifies other topics ("related topics") that are related to the subject you are reading about. If you want to read the help information about those topics, use the + (plus) and - (minus) keys to move the pointer to the topic and press Enter. The help text for that topic appears at the top of the screen.

Key | Function
+ | Moves the pointer down the list of related topics, or down to another group of related topics displayed on the screen.
- | Moves the pointer up the list of related topics, or up to another group of related topics displayed on the screen


Search String

You may also search the text for a particular word or phrase, if necessary. This word or phrase, called a string, cannot be longer than 40 characters. To search the text information, press F8 and enter the string. Press F9 to search for the next occurrence.


Help Contents

Displays a table of contents with first level headings for on-line help. Press F4 to display five additional levels of headings until you reach the heading you want. There are six heading levels altogether. Move the pointer to the topic you are interested in and press Enter. Help information for that topic is displayed. To return to the table of contents, press F4. To get to the index, press F3. To leave help, press F10.


Help Index

Displays an index of topics for on-line help. Initially, only the first level of the index is displayed. To reach the second level, press F3. To return to the first level, press Escape. To select a topic, move the pointer to it and press Enter. To move to the table of contents, press F4.

A topic shown only once in the index may actually have multiple entries in the help text. Once you have selected an index topic, press F9 to move to the next entry if there is one. When the Help key menu returns to the Control Area, there are no additional entries.

You can also search the index for a particular word or phrase by pressing F7 and entering the string you want to search for. The string can be no more than 40 characters.


Help On-Error

Displays help text for error messages. Press Enter to receive help for the last error that occurred, or enter a corresponding error message number to display the appropriate help information. SmartWare error messages and their corresponding numbers, are listed in Appendix A of Project Processing Manual.


Help Tutorial

Invokes the tutorial for the currently active module. Help Tutorial is not available from the Main Menu. Use the tutorial to learn about a particular feature, or step-by-step to learn the entire module. If you enter your name, SmartWare will keep track of the lessons you have completed.
IMPORTANT: Because SmartWare Tutorials run within the module they describe, you should unload all active files before entering the tutorial.


Remember Commands

The Remember commands allow you to create, edit, and run project files. Information about Remember commands is in the Project Processing Manual.


Remember Start

Remember Start activates Remember Mode which then records keystrokes or commands to create a project file.


 Commands. Records every module command used while the program is in Remember Mode. Keys are not recorded.


 Keys. Records every keystroke while the program is in Remember Mode.


 Both. Keystrokes that are part of commands are recorded as commands. Keystrokes that are text information are recorded as keystrokes.

After you select an option and name your project file, the reminder Remembering commands... is displayed in the bottom left-hand corner of the screen. Ctrl-F10 suspends and reactivates Remember Mode. You may append additional commands and keys to existing project files using Remember Start. When prompted, enter the name of a project file you want to append to. Remember Mode will be activated and your actions will be recorded in the file.


Remember Finish

Remember Finish deactivates Remember Mode, saves the project file, and compiles it. You can then execute the project file using Remember Execute.


Remember Tools

Remember Tools performs various file maintenance and debugging activities and creates custom menus and option lists. Tools options are listed below:


Remember Tools Compile

Remember Tools Compile produces an executable version of a project file that was created using the Text-Editor or Word Processor. For example, if you create a project file in the Text-Editor you would use Remember Tools Compile to convert it from a text version to a runtime version. When you select this command, you must specify one of the following options:


 Debug. Compiles the runtime version with the text statements included in the project file. This is advantageous in the debugging process, however, this compile option creates a larger, slower project than the No-Debug option.


 No-Debug. Creates a smaller, faster runtime file because it compiles without the text included. Your file will be protected because other users will not have access to the text version of commands.
NOTE: Do not use No-Debug if you are using the Quiet Execution or Single-Step project execution because these options require the text file commands during project execution.


Remember Tools Edit

This command allows you to create or modify project files. To create a project file, enter a file specification not currently used for a project file. To modify an existing project file, enter the filename when prompted.


Remember Tools Print

This command prints a project file with its name, date, and time at the top of the project. Pages are numbered and each line in the project is numbered.


Remember Tools Delete

Remember Tools Delete erases both runtime and text versions of a specified project file from disk.


Remember Tools Trace

This command allows you to determine conditions to identify possible errors and determine the current value of variables. When an error condition exists, project file execution is interrupted and two small windows are displayed. The first window identifies the current status of project execution. The second window displays the variables or conditions used to trap the error.


Remember Tools Input-Screen

Remember Tools Input-Screen allows you to design custom menus and option lists to use in projects, as well as custom data entry screens for databases and spreadsheets. For more information about creating input-screens, see the Project Processing Manual. Three options are displayed:


 Input-Screen Define. Allows you to define a new input-screen or edit an existing one.


 Load. Displays a list of existing input-screens. At the prompt, select one you want to load and press Enter.


 Undefine. Displays a list of existing input-screens. At the prompt, select one or more files you wish to erase.


Remember Execute

Remember Execute runs an SPL program. Select a file to run from the list of existing project files. F8 is the Quick Key used to initiate the Remember Execute command. Choose whether the project file should be run In-Memory or From-File. When selected from a pulldown menu, no other options are required since the program is run in memory automatically.


 In-Memory. Places the entire runtime version of a project file into memory before running it. This allows commands to be executed more quickly. This option is normally used for small project files that will not use much memory.


 From-File. Executes the runtime version from disk. The project will be executed more slowly than it would using the In-Memory option. From-File is normally used for large project files to save memory. If you choose In-Memory and your file is too large to fit into memory, SmartWare will default to the From-File option.


Remember Load

Remember Load executes a project file, keeping it available for use with other project files. Any public variables or functions within the project can be used during execution of another project.


Remember Unload

Remember Unload closes a project file and removes it from memory.


Remember Make-Application

With the SmartWare Developer, you can create both simple applications to help organize your personal SmartWare files, and large applications that businesses use for any number of purposes.

The Make-Application command is used to create a new RAD application.


Remember Run-Application

The Run-Application command is used to run a RAD application.


Tools Commands

The Tools commands allow you to perform calculations, create and use directories, perform file operations, set defaults, create and use macros, and manipulate printer fonts.

Options for Tools includes the following:


Tools Calculator

Tools Calculator or ALT-K activates the SmartWare Calculator, which has two modes: Formula Mode and Algebraic Mode. To switch between the two modes, press F2.


Formula Mode

In Formula Mode, you can type a formula in the Formula Window and press F5 to evaluate it. The result is displayed in the Result Window if a valid calculation has been entered. Otherwise, an error message appears.

A formula can be as simple as 1+1 or as complex as you can make it in the area provided. You may include functions such as AVG, DATE and DAYNAME. For a detailed list of the available functions, refer to the Command Reference section of Formula Reference Manual.

You may use public variables in Formula Mode and you can use the LET function to declare public variables within a formula. For example, if you need to calculate the percentage of the total for a number and you don't know the total, you can store the total in $total and then divide to calculate the percentages.

     FORMULA:  LET $total = 20 + 17 + 43 + 33
     RESULT:   113

     FORMULA:  43 / $total
     RESULT:   38

The SmartWare Calculator, in Formula Mode, will return and use a value or text from a Database field or Spreadsheet cell, including an external worksheet reference. For example, if you are currently in the Spreadsheet and require the value from cell r1c1 in your formula, simply enter r1c1 into the expression to be calculated.


Algebraic Mode

Works similarly to a standard desktop calculator to perform mathematical operations. As you enter numbers, they are displayed in the Result Window.

Signed numbers cannot be entered directly. Instead, use the change sign function key (F9). For example you do not type -2 to display a negative numeral 2. Instead, enter the number 2 and press F9 to change the sign. The entry will be displayed as -2 in the Result Window. Signed exponents may be entered.


Arithmetic Operators

You can use any arithmetic operator in Algebraic Mode that you would with a calculator. To use Algebraic Mode, enter a number into the Result Window and then enter an arithmetic operator (+, -, *, /). The operator appears to the right of the value. When you enter another number, the first number disappears from the screen, but remains in memory. When you enter either {=} or Enter, the values are calculated and the result is placed in the Result Window. This process may continue through successive arithmetic operations.

Example

The following example illustrates how the Algebraic Mode is used. Set numeric precision to 2.
1. Enter 1 and press +. This produces the following display in the Result Window:

     1 +
2. Now enter 4 and press *. The following is displayed:

     5.00 *
3. As long as you follow an entry with another arithmetic operator, the Calculator looks for another number to use. Enter 3 and press Enter. The following is displayed:

     15.00
4. Press either Enter or = to end the equation and display the result. Any numbers typed thereafter become part of a new calculation.
5. Press F8 to clear the calculation. The Result Window is cleared and you may use it for another calculation.


Using Percent

While the calculator is in Algebraic Mode, you may solve equations using the percent (%) operator in any of four ways. Following is an explanation and example of each use.

Finding a part of a whole. The percent operator can be used to determine what number is a certain percentage of another number. For example, last year, 80,000 widgets were sold in the United States. ACME Widgets had a 45% market share. How many Widgets did they sell last year? The following equation allows you to find out what 45 percent of 80,000 widgets would be.

     80000 * 45% = 36000

Percent that one number represents of a total. The percent operator can also be used to determine what percentage one number represents of another number. For example if Industrial Widgets sold 13,345 of the 80,000 widgets sold last year, what was their market share? The following equation allows you to divide 13,345 by 80,000 and determine the percentage.

     13345 / 80000% = 16.68

Percentage change. The percent operator can also be used to determine a change in percentage. For example, if widget sales are projected to grow from 80,000 last year to 150,000 next year, what percent increase will the industry experience? The following equation subtracts 80,000 from 150,000 and determines the percent change.

     150000 - 80000% = 87.5%

Total given a number and a percent. The percent operator also allows you to add, subtract, multiply or divide with a percent. For example, two years ago, ACME Widgets sold 20,000 widgets and had a 33 percent market share in the industry. How many widgets were sold industry-wide? The following equation divides 20,000 by 33 percent to determine how many widgets were sold.

     20000 / 33% = 60,606

The percent operator can be used only after you have entered a number, an operator and a second number. Different results are achieved, depending on the type of operation you are attempting.

For multiplying and dividing, the calculator interprets the % operator in the following way.

     X * Y% is interpreted X * (Y/100)
     X / Y% is interpreted X / (Y/100)

In addition and subtraction, the calculator interprets the % operator in the following way.

     X - Y% is interpreted ( (X - Y) /Y ) * 100
     X + Y% is interpreted ( (X + Y) /Y ) * 100


Precision

The precision determines the number of decimal places a value has. To change the precision, press F3 and enter a number 0 through 15. For example, if you set the precision at 4 and enter 1234, the value displayed in the Result Window will be 1234.0000. If you set the precision at 2, the same number would appear as 1234.00. A number too large to display with all the defined decimal places is truncated from the right in order to show the most significant digits.


Memory Storage

In Algebraic Mode values can be stored and recalled later. Press F5 to store the value displayed in the Result Window in memory. When you want to use that value, press F6 and the value is entered in the calculation.


Math Format

Normally, the SmartWare Calculator uses decimal numbers, but it can also use scientific notation, octal, or hexadecimal numbers. To convert values in the Result Window to a different math format, press F4 repeatedly until you get the format you desire.


Using Results

SmartWare saves the calculator's last valid calculation in memory. Therefore, you can use it in the current module by pressing Ctrl-C at the location where you would like the value entered. For example, in the SmartWare Spreadsheet, you can move to a specific cell, press Ctrl-C and the result of the last calculation made in the SmartWare Calculator appears.
NOTE: The result of the last valid calculation is stored in the same location as the results of calculations made in the Text-Editor, Project Editor, Macro Editor, and the calculations made with the math functions in the Word Processor. Only one result from the last calculation made in any of these four places is saved. Therefore, the SmartWare feature that was most recently used is the one from which the result will be drawn.


Exiting The Calculator

To exit the SmartWare Calculator and return to the module menu, press F10 or Escape.


Tools Directory

Tools Directory is used to get file information for a directory, make or remove a directory, or change the current data path.


Tools Directory Display

Tools Directory Display lists the file information for any available directory in alphabetical order. At the prompt or dialog box, enter the directory and/or file specification. No file spec will list the current directory. To display files in other directories, enter either a complete path, including filename (e.g., c:\mydir\letters), or wild card characters (* or ?) to designate a specific group of files (e.g., c:\mydir\*.doc). If you enter wild card characters without specifying a pathname (e.g., *.*), files in the current directory are displayed.

You may change the sort order using the following function keys (use the function key or click on the list):

Key | Action
F2 | Sorts by filenames in ascending order.
F3 | Sorts by date and time in ascending order.
F4 | Sorts by file size in ascending order.
F5 | Sorts on primary and secondary levels so you specify criteria when two or more files have the same key information.
F6 | Prints a list of files in the directory.

The F5 option requests a primary key for an initial sort and a secondary key for a more specific sort. For example, if you sort files by extension (primary key), you will notice that many files may have the same extension (e.g., .ws, .doc). You can then choose filename as the secondary key to sort by filename.

When you press F5, the following option list is displayed:

     Select primary key: F2 Name F3 Extension F4 Date/Time F5 Size

After pressing the function key for the primary key, the next option list appears:

     Select secondary key: F2 Name F3 Extension F4 Date/Time F5 Size

When you select the secondary key, the new file list appears sorted first by the primary key, then by the secondary key.


Tools Directory Make

This command creates a directory without exiting SmartWare. At the prompt, Enter a directory name:, enter the name for the directory you want to create.

If you want the new directory to be a subdirectory of the current directory, enter a subdirectory name. For example, to create a directory named "data" within the mydir directory, make certain mydir is the current directory, and type the name "data" at the prompt.
NOTE: To quickly determine the current path, select Tools Directory New-Directory and look at the Path: indicator at the left of the Status Line. Press Escape to cancel execution.

If you want to create a subdirectory in a location other than the current directory, you must enter a full pathname. The pathname includes a drive letter, directory name, and subdirectories. For example, if you not currently at the mydir directory, but want a directory called "data" located there, type c:\mydir\data at the prompt Enter a directory name. All directories in the pathname, except the last one, must already exist.

If the pathname you enter for the new directory has already been used, the message Unable to create the directory appears and you need to repeat the process using a different directory name or path.
IMPORTANT: For SmartWare to display a prompter of directory names or filenames within a directory, you must enable the setting Display of filenames for file prompting: on the Tools Global Preferences menu. For more information, see Using the File Prompter later in this chapter.

Remember that you can also include a pathname in the Data path: prompt on your module Preferences menu to automatically save files to a particular location. Files will be saved to this path from within the module unless you change directories with the Tools Directory New-Directory command.


Current Directory

The current directory is the directory from which you entered SmartWare, unless you have defined a default data path on one of the Preferences menus. If you have defined a default data path, it becomes the current directory when you enter SmartWare.

Any action performed in the current directory is saved in the current directory unless you specify otherwise. If you create and save a document without first changing directories or providing a different pathname at the filename prompt, that document is automatically saved in the current directory.
NOTE: To keep a hard drive well organized and to eliminate confusion, you should never save a document, worksheet, or data-file in the root directory or in the directory containing SmartWare program files.


Tools Directory New-Directory

This command temporarily changes the current data path without exiting SmartWare. At the prompt, either type the path specification or use the prompter to select one. The data path is changed only while you are in SmartWare. Once you exit the current module, the original data path from which you entered SmartWare, or the data path set in Global Preferences, becomes the current data path again.

There are several ways to select a directory from the prompter using either the keyboard or the mouse.
*** To change to a directory listed on the prompter, move the pointer to that directory and press Enter. Directories are listed after any files and are designated with the path symbol (\). For example, files\ indicates a subdirectory of the current directory named files. Any files and subdirectories in the directory you select will be displayed. Continue selecting directories until the path on the command line reflects the directory you want to change to. Point to the .\ symbol and press Enter. That directory becomes the current directory.
** To stay in the current directory, press Escape or move the pointer to the single period (.\) and press Enter.
** To change to the directory one level up the "directory tree" closer to the root, move the pointer to the two periods (..\) and press Enter.
** To change to the root directory, move the pointer to the backslash (\) and press Enter.
NOTE: You should use Tools Directory rather than Global Preferences to access a directory on a removable drive path (for example, a floppy diskette in Drive A or B).

If the directory you selected does not exist, the message Not a valid pathname appears, and the current directory is not changed.


Searching for a File

If the file you want is not displayed in the prompter, you can search for the file by pressing F4, entering the filename, and pressing Enter.

If you specify a path with the filename, SmartWare begins looking for the file in the directory specified, then searches through its subdirectories until the file is located. If you do not specify a path, SmartWare begins looking for the file in the current directory, then searches its subdirectories.

When the file is found, you are asked whether or not you want to continue the search. Enter y if you want to continue to search in another location. If the filename is not located in any other directories, the message End of search, press any key is displayed. Enter n if you do not want to search other directories for files with the same name. The name of the file that was found is displayed on the command line. You can press Enter to execute the current command on that file, or press F8 to clear the line.


Tools Directory Remove

Tools Directory Remove deletes a directory without exiting SmartWare. When prompted, type a directory name or select one from the prompter. Any files or subdirectories that exist within the directory must be erased first using Tools File Erase, or you will receive an error message when attempting to remove a directory.


Tools File

Tools File is used to copy, rename, move, erase, or print a file. After selecting one of the File commands listed below, type or select a filename when prompted then press Enter to execute the command. With most File commands, wild card characters can be used to specify a group of files to be acted upon. For example, *.doc means all files with a doc extension. Be careful when using wildcards to list files, especially when using permanent file operations like Erase.
IMPORTANT: When you perform file operations on a file stored on a floppy diskette, do not open the drive door while the file is being processed or remove the diskette until the file has been saved and unloaded. Usually a red warning light near the drive door is on while the drive is being accessed. Do not open the drive door and remove the diskette until the light is off and you have saved and unloaded the file, otherwise the files may be damaged and changes will be lost.


Using the File Prompter

The setting Display of filenames for file prompting: on the Global Preferences menu controls whether a prompter of directories or files within a directory is displayed. When using the Tools File commands, a prompter listing all files and subdirectories in the current directory is displayed, if the prompter has been enabled. You may use it to select a file, or you can type in filenames at any filename prompt.


Searching for Specific Files

When you need to search for a specific file but you don't know its path, press F4 and enter its name at the prompt Enter the file specification. If you do not specify a path, SmartWare first looks for the file in the current directory and then searches its subdirectories. If you specify a path, SmartWare looks first in that directory and then searches through its subdirectories until the file is found or there are no more subdirectories to search.

When the file is found, the message File was found in <location> - Continue searching? (y/n) is displayed. Enter n if you do not want to search other directories. The name of the file will appear on the command line. You can press Enter to execute the current command on the file, or press F8 to clear the command line.

Enter y if you want to continue searching other directories for the file. When the filename is not located in any other directory, the message End of search, press any key is displayed.


Displaying Directories Within a File List

In addition to listing files, file prompters also display subdirectories of the current directory. Directories are listed after files and are identified by the path symbol (\). For example files\ indicates a subdirectory of the current directory named files.

If you point to a directory and press Enter, the prompter displays files and subdirectories in the newly selected directory. The current path is identified on the Status Line. Continue selecting directories until you find the file you want.


Marking Files

Some commands allow you to use the F6 key to mark or unmark files displayed on the screen for copying and deleting. The F6 key toggles the mark on a file on and off.


Tools File Copy

Use Tools File Copy to copy files from one location to another. At the prompt Enter the source filename:, enter the name of the file you would like to copy, or select it from the prompter.

At the prompt Enter the destination path or filename, enter the full pathname of the location in which you would like to place the copy or copies. Typing .. at the prompt will place the files in the current directory. You can also use the prompter to specify the destination directory.
NOTE: The file being copied will overwrite a file of the same name at the destination. You must also be sure that the destination is a drive or directory. Otherwise the files being copied will be relocated one at a time at the same location, overwriting each other, and the only file saved will be the last file copied.

This command copies specified files from one disk to another or from one directory to another.


Tools File Erase

Tools File Erase deletes specified files. Wild cards may be used to specify a group of files, but they should be used with caution. The files are deleted when you press Enter. Use the F6 key to highlight multiple files to erase.


Tools File Move

Use Tools File Move to move files from one directory to another. This command copies the file to the new location and deletes the old copy. When you select Tools File Move, a prompter lists all available files in the current directory. You can select a file to move by pointing to it and pressing Enter or type in the name of the file. If the file you want is not in the current directory, enter the whole path, or use the file prompter to move through the directories until you find the right file.

To move several files at once, press F6 to highlight all the files you wish to move and then press Enter. You are then prompted for a new path for the files. Type in the pathname, or specify it in the prompter.
NOTE: The file being moved will overwrite a file of the same name at the destination. Also, if you are moving multiple files, they must be moved into a directory, not one file.


Tools File Rename

Tools File Rename changes the name of a file. After entering or selecting a file to rename, type in a new filename and press Enter. The filename is changed.


Tools File Print

Tools File Print prints everything within a file whether it is text or coded non-text information. You may use this command to quickly print text files from the Main Menu or when you have been performing other functions within Tools File.
NOTE: This command was intended for use with text files. Printing other file types with this command can give unexpected results such as ASCII characters in place of letters and numbers.


Tools Macros

Tools Macros allows you to redefine a key to perform a series of tasks. Any key except Escape, F1, F10, Enter, Ctrl-F10, Ctrl-C, Ctrl-M, Alt-F10, and Shift-F10 can be redefined. For more specific information on defining macros, refer to the Software System Manual.

You can suspend a macro definition for one keystroke by pressing Shift-F10. The key immediately following Shift-F10 will output what SmartWare originally interpreted for that key. After that, SmartWare will revert to the macro definition when that key is pressed unless Shift-F10 is pressed again or the macro is unloaded.


Macros Clear

To unload a macro from memory and use the original SmartWare interpretation of the key, use the Tools Macros Clear command. At the prompt One All, enter O or highlight One if you only want to unload one macro. Identify the key when prompted. Enter A or highlight All if you want all current macros removed from memory.

SmartWare will not ask Are you sure? y/n when you execute Tools Macro Clear.
NOTE: Tools Macro Clear does not delete macros from a saved file, it only removes them from memory. To delete a macro file, use Tools File Erase.


Tools Macros Load

To retrieve a macro file from disk, select Tools Macros Load and specify which file you want to load.

You can load any number of macro files concurrently. If you load several macro files that redefine the same key, the most recently loaded macro definition for that key is used.

You can either load the files as needed, or they can be automatically loaded when you enter a SmartWare module. To automatically load a file, enter the filename at the appropriate prompt on the Tools Preferences definition menu for that module. For more information, refer to the command reference chapters of each module manual.


Tools Macros Remember

Selecting Tools Macro Remember is the easiest way to create a macro. You manually step once through the process you want to automate. While Remember Mode is activated, SmartWare records every keystroke you make and saves it as part of a macro definition. After the macro is completed and saved, every time you press the macro key combination, SmartWare automatically executes all the remembered keystrokes for you.

To use Tools Macros Remember, enter the key you want to redefine at the prompt, Press key to define:. SmartWare invokes Remember Mode and records your keystrokes until you execute Tools Macro Finish. Remembering... appears in the lower right corner of the screen to indicate that SmartWare is in Remember Mode.

Some of the keystrokes you use in the definition may not execute properly if they depend on SmartWare being in a certain mode. For example, while in Remember Mode, it is better to use Alt-Y to change to Enter Mode and Alt-Z to change to Command Mode than to use Escape.
NOTE: It is a good idea to begin any macro definition with Alt-Y or Alt-Z depending on which mode your macro needs for proper execution.


Suspending Remember Mode

You can suspend Remember Mode by pressing Ctrl-F10 to keep specific keystrokes from being recorded in the macro. To reactivate Remember Mode, press Ctrl-F10 again.


Tools Macros Save

You may use a macro immediately after defining it by pressing the key you redefined. You can continue to use the macro as long as you don't leave the current module. The key's output reverts to its original definition once you leave the current module unless you save the macro definition prior to exiting.

Once the definition is saved in a macro file, the file can be loaded any time you are using SmartWare, and SmartWare will execute the macro definition when the key is pressed.

To save macro definitions, use the Tools Macros Save command. At the prompt, Enter a macro filename:, type the name of the macro file you want to save. Every key you redefined prior to saving is included in this macro file. Therefore, you should redefine the keys that are related to the same process and save them in one file. Likewise, you may want to save macro definitions that are unrelated in separate files.

You can load and use a SmartWare macro in any module, regardless of the module in which it was created. Of course, macro definitions may not necessarily make "sense" if they are used in another module.
NOTE: Macro files are stored as text files with the extension "MAC".


Tools Macros View

You can display a list of currently defined or loaded macros with Tools Macros View. A pop--up window appears listing all the macros currently being used and their definitions.


Macros Edit

Tools Macro Edit allows you to create or edit a macro by typing the definition on a screen. It is similar to using the Text Editor. When the prompt Press key to edit: appears, press the key you want to redefine. If a macro has not already been defined for that key, the prompt No macro defined for that key -- Continue? (y/n) appears. Enter y and the Macro Editor is displayed on the screen. Type the macro definition. When you are finished, press F10.

If a macro has already been defined for that key, the Macro Editor displays this definition. You may add or delete keystrokes and commands to correct or update the macro.

Use the following guidelines when creating or editing a macro definition in the Macro Editor:
*** Separate each term with a comma.
** Enclose text in quotes when it is not a keystroke or macro control term.
** End every line except the last line with a comma. The program recognizes a line with no comma at the end as the end of the macro definition. If you do not have a comma at the end of a line, the error message Unrecognizable character at line # column # appears when you press F10.

For example, in SmartWare Spreadsheet you want to use one keystroke (Alt-C) to change to Command Mode (Alt-Z) and execute the Layout Justify Right command ("ljrb") for the block three rows to the right (Repeat,#3,right) and three rows down (Repeat,#3,down). You would define Alt-C as follows:

     Alt-Z,"ljrb",Repeat,#3,Right,Repeat,#3,Down,Enter


Advanced Macro Terms

Besides keystrokes, a macro definition can contain character terms, activity control terms, and macro control terms. These terms can be used to create more sophisticated macro definitions. For more information, refer to the discussion of the Keys command in Project Processing.


Macros Finish

When you finish defining the macro, press Ctrl-F10 and select the Tools Macro Finish command. The macro definition is then saved in memory but it is not stored on disk until you save it using Tools Macros Save. You may correct or enhance your macro using Tools Macro Edit.


Tools New-Font

Tools New-Font enables you to manage the set of fonts you defined within your modules. With Tools-New Font you can prerasterize a set of fonts for faster printing. For information about font typed and how fonts are used, see the Software System Manual.

The fonts defined in modules may not print as quickly as expected if the fonts are not internal to your printer. If this is the case, SmartWare forces the printer to print the font as a filled-area font. A filled-area font creates a character by defining a set of coordinates to be filled in.

Tools New-Font allows you to prerasterize a set of fonts from the previously defined filled-area fonts. If you frequently use several filled-area fonts, you may want to prerasterized them to speed up printing. When you prerasterize a font, the filled-area font is drawn to a specific size and printer resolution. This font information is then stored in a file. When you print a file using this font, the predrawn font is used. This is much faster than having to scale each font individually. The following Tools New-Font commands are available:


Tools New-Font Normal

This command prerasterizes a set of fonts for normal (portrait) printing.


Tools New-Font Sideways

This command creates a set of fonts for landscape printing. Sideways fonts work only in graphics mode for most printers. You should prerasterize only 8- or 12-point standard fonts for sideways printing.

After choosing either New-Font Normal or New-Font Sideways, select from the following items:
*** Font Family. Identifies the font family. Press F6 for a prompter of available choices.
** Size. Identifies the font size in points.
** Width. Identifies the font width.
** Slant. Identifies normal or italicized characters.
** Weight. Identifies normal or bold face characters.


Tools OS

Pulldown Menus

After selecting OS, the SmartWare screen will be replaced with a blank screen and the operating system prompt. Type Exit to return to the SmartWare screen. Ctrl-O is the Quick Key for Tools OS. In Windows, this provides DOS access.

Command Lists

Tools OS temporarily accesses the operating system. You can then perform one command without exiting SmartWare. At the prompt, enter the operating system command you want to perform and press Enter. Press any key to return to the location in SmartWare at which you began the command.

You may also access the operating system from Tools OS by pressing Enter at the prompt. Your SmartWare screen will be replaced with a blank screen and the operating system prompt. Type Exit to return to the SmartWare screen. Ctrl-O is the Quick Key for Tools OS.


Tools Preferences

Tools Preferences is used to select default settings that determine how the program will operate. Using these commands, you determine the default settings for the entire system, each module, and applicable hardware. Under Windows, hardware settings such as the printer and screen drivers may be determined by Windows.


Tools Preferences Module

This command determines module specific default settings, such as Paragraph Format and Pagination in the Word Processor. For more information on individual module settings, refer to the appropriate module manual.


Tools Preferences Global

Tools Preferences Global determines default system settings for entry and for work within all the SmartWare modules. When you select Preferences Global, a definition menu appears. Each menu item is explained below.

NOTE: When creating a project file, do not use No-Debug if you are using the Quiet Execution or Single-Step project execution because these options require the text file commands during project execution. For more information on Single-step and Quiet Execution, Refer to Project Processing.

Date1 Format | dd month yy
Date2 Format | mm/dd/yyyy
Date3 Format | month dd, yyyy

The date formats you specify can be customized to display abbreviations and whole words as listed below.
mon | first three letters of month
mm | two-digit month
dd | two-digit day
yy | two-digit year
yyyy | four-digit year
day | day-of-the-week
month dd | month and two-digit day

For example, if you want a date displayed with text and numbers, you can customize a date format as day, month dd, yyy. This will display a date such as Thursday, August 16, 1990.
NOTE: Use lower case letters when setting date formats, otherwise date fields within imported databases may not be imported correctly.

** Project File On Entry. Specifies a project file to be automatically executed every time you enter SmartWare.
** Project File On Exit. Specifies a project file to be automatically executed every time you leave SmartWare.
** Look for Keyword File on entry to SmartWare. If this option is set to yes, SmartWare will search for and use a file called "smart.mnu" containing user-defined menu items for the keyword menu display. If the file is not found or if the option is set to no, the normal SmartWare menus are used.
** Look for Intro Display File on entry to SmartWare. If this option is set to yes, SmartWare will search for and use a file called "smart.msg" for the intro display screen. If the file is not found or the option is set to no, the normal SmartWare intro display screen is used.
** Closing Files. In DOS, this controls the drives on which Word Processor, Spreadsheet and Text Editor files will be kept closed during editing. Keeping files on removable media, such as a floppy disk, closed helps avoid housekeeping problems caused by removing the media while a file is still open. An asterisk at this prompt tells SmartWare to determine from DOS which drives have removable media. You can also enter one or more drive letters to tell SmartWare to always close files on those drives. In Unix, this is simply yes or no to close these files during editing. Any changes you make at this prompt will become effective after you exit and re-enter SmartWare.
** Character Comparison Tables. Sets the current table used to sort and compare text. Selecting the proper character comparison table for the language you are sorting ensures that SmartWare will properly sort special language characters. Press F6 to display a list of installed character comparison tables and select the table for the language you wish to sort. The new character comparison table becomes effective immediately. If you make no selection at this prompt, the internal American/English comparison table will be used. Changing character comparison tables may affect database indexes that were sorted under a different table, or projects and formulas that expect the greater than/less than operators to act on text in a specific manner.
** Use optimized screen refresh. This is a Unix only option. When the option is on, ANGOSS checks for any pending keystrokes before refreshing the screen waiting until the last keystroke is processed, thus saving needless screen repainting. For example, this would prevent waiting for the screen to catch up if you "lean" on a down arrow with a slow terminal. Optimized refresh does have some disadvantages. For instance, if the machine is busy, you may not see characters as you type them, causing a noticeable lag before being printed.
** Display Lead-in Keystrokes. This is a Unix only option. When on, this option displays lead-in characters on the lower right corner of the terminal. For example, to obtain an Alt L, the Esc key is pressed followed by the L key. The Esc key represents the lead-in character.
** Text-editor Expand Tabs Into Spaces. Tab characters can be converted into the number of spaces tab characters represent. Setting this option to Yes if you want the text-editor to work the same way as previous versions. If it is set to No, tabs will be preserved.
** Spaces Per Tab. The "number of spaces per tab character" determines the how many spaces a tab will represent when viewing, modifying, or printing a file in the text editor.
** Horizontal Scrolling. The text-editor optionally supports smooth horizontal scrolling. With smooth scrolling, the screen will shift one column at a time when moving the cursor off the edge of the screen.


Tools Preferences Hardware

Tools Preferences Hardware allows you to change the default settings for your hardware that were set through the Install program. On most items, F6 will provide a list of relevant installed drivers or descriptor files. For more information, refer to the Software System Manual. Each menu item is briefly explained below.

Text Screen. Determines the default screen driver that supports your display adapter. If left blank, the appropriate driver is automatically detected. Note that this field will not appear on DOS systems that have no drivers installed or on Windows or Unix systems.

Graphics Screen. Determines the default screen driver that supports your graphics adapter. If left blank, the appropriate driver is automatically detected. Note that this field will not appear on DOS systems that have no drivers installed or on Windows or Unix systems.

Printer. Determines the default configuration for your printer (for best results, use the configuration recommended by the printer manufacturer). F6 will display a list of installed printers. In Windows, printer configuration is determined by the Print Manager. As well, if the printer selection is left blank, the default printer set in the Print Manager is used.
*** Cartridge. Appears only when the default printer is one that uses font cartridges. This menu item is used to select cartridge descriptor files. F6 will display a list of installed cartridge descriptors.
** Paper Profile. Specifies paper size and paper path. This setting controls paper size and path when printing from within any editor, from within the Database (except reports), when executing Tools File Print, or when using LPRINT commands in a project file. Printing from the Word Processor, Spreadsheet, and Database reports, will be controlled through Paper Profile settings in each module. F6 will display a pop-up of paths and page sizes.
** Time-out (seconds). Specifies the number of seconds SmartWare should attempt to print before an error message is generated.
** Port. Specifies the computer port to which your printer is attached. Some port options will request further information.
** Justification. Activates one of two types of justification features if supported by your printer: Micro-Justify which makes minute adjustments in the horizontal placement of characters on a line, producing a more professional looking document; or Space-Justify, which adjusts the placement of characters using whole spaces. This last option processes more quickly than micro justification.

Plotter. Determines the configuration for your current plotter (for best results use the configuration recommended by your plotter manufacturer). This selection is not used in Windows.

Network. Specifies the network operating system you are using. Note that the generic setting should work on most networks. Unix systems will not have this option. In Windows, this is a Disable/Enable toggle.


Tools Preferences Pulldowns

Tools Preferences Terminate Pulldowns

These options switch between pulldown menus and command lists when in a graphical environment such as Windows. Power users may require the complete command set offered by the command lists.

In the wordprocessor and spreadsheet modules - the two modules with both Entry and Command modes - the Esc key toggles the command list on and off. If you use the command list but have not terminated the pulldown menus, it is possible for them to become temporarily inactive. For instance, if you enter the Text-Editor through the command list, the pulldown menu will not be cleared however, any commands selected from the pulldown menu will have no affect. This retains compatibility with existing macros.


Tools Preferences Font-Map

This maps the Standard font options (normal, condensed, compressed, and expanded) to specified fonts. Remapping the Standard font options allows you to specify the same sized fonts across different printers and platforms. For example, if a table report uses the Standard font with the compressed option, the report may work fine on one printer but not on another. To solve this problem, remap the compressed option for that printer.

Application programmers should note that, to ensure portability of applications, use only the Standard font in printable objects such as reports. In this way, when a different set of fonts is required, only the font-map will need adjustment.

Font-Map information is stored in the fontmap.def file. A record is entered for each printer that contains a font mapping. This means that you must first select the printer before mapping one or all of the Standard font options. If required, repeat this step for each printer on your system.

Note that this command can also be issued through SPL. In this case the keyword SET followed by the font string must be added. For instance, to set the Standard font's expanded option to 14 point Courier, the command looks like this:

     TOOLS PREFERENCES FONT-MAP EXPANDED SET "Courier 14Pt."


Tools Text-Editor

Activates the Text Editor so you can create or edit files. At the prompt or dialog box, enter the name of a file you wish to create or select a file from the prompter list and a pre-existing file is displayed for editing. This is a simple text editor without word processing features such as word wrap, margin control, etc.


Creating/Editing Text Files

Begin typing when the Text Editor appears. Each line in the Text Editor can include up to 255 characters. Press Enter to end a line and move to the next line.

Use the keys listed in the following table to move within the Text Editor and edit the file.

Key | Edit Operation
Delete | Deletes the character at the current cursor position and the rest of the line shifts left.
Backspace | The character to the left of the cursor is deleted, and the rest of the line shifts left.
Up-Arrow | Moves the cursor up one line.
Down-Arrow | Moves the cursor down one line.
Right-Arrow | Moves the cursor one space to the right.
Left-Arrow | Moves the cursor one space to the left.
Page-Up | Moves the cursor up one screen.
Page-Down | Moves the cursor down one screen.
Home | Moves the cursor to the beginning of the top line of the current screen.
End | Moves the cursor to the beginning of the last line of the current screen.
Tab | Moves the cursor five spaces to the right.
Shift-Tab | Moves the cursor five spaces to the left.
Ctrl-Right-Arrow | Moves the cursor to the end of the current line.
Ctrl-Left-Arrow | Moves the cursor to the beginning of the current line.
Ctrl-Home | Moves the cursor to the beginning of the file.
Ctrl-End | Moves the cursor to the end of the file.
Insert | Toggles between Insert On and Insert Off. When the Insert Mode is on, a character is inserted at the current cursor position, moving the rest of the information on the line and the cursor to the right. When the Insert Mode is off, a character entered overwrites the character at the current cursor position.

A list of Quick Keys that activate various commands is displayed at the bottom of the screen. These Quick Keys are listed in the following table.

Key | Action
F1 | Displays help information.
F2 | Toggles between two groups of Quick Keys in the Control Area of the screen.
F3 | Finds a string in the text file. When prompted, enter the string you want to locate and press Enter.
F4 | Searches for a string and replaces it with another string. When prompted, enter the string you want to locate and press Enter. Then enter the string you want to replace the first string with and press Enter.
F5 | Calculates a formula and displays the result at the bottom of the screen. A formula is the portion of the text file from the beginning of the file to the first tilde (~~), carriage return or non-formula text. Any valid formula can be entered. The result can be transferred to a worksheet, document, or text file by pressing Ctrl-C.
 | The result of the calculation is stored in the same location as the calculation results from the Project Editor, Macro Editor, SmartWare Calculator, and calculations made with the math functions in the Word Processor. Only one result from the last calculation made in any of these places is saved. Therefore, unless you use Ctrl-C immediately upon leaving the Text Editor, the result you get may or may not be the result of the last calculation made in the Text Editor.
F7 | Inserts the contents of the line buffer at the current cursor position.
F8 | Deletes the information from the current line and stores it in the line buffer.
F9 | Repeats the last Find, Goto, or Replace action performed.
F10 | Saves the text file and exits the Text Editor. To exit the Text Editor without saving the file, press Escape and answer y to the prompt Abandon (y/n)?.
Alt-F2 | Deletes the information from the Text Editor. The information is not stored in a buffer.
Alt-F3 | Reads information from a text file and inserts it in the Text Editor starting at the current cursor position. You must include the file extension with the filename.
Alt-C | Copies the information in a specified block area and stores it in the block buffer. While the block is marked, you may press Alt-P to print the information in the block or you may press Alt-W to write the block information to a disk file. Once you've pressed Enter or F10, you may use Alt-I to insert the information from the block buffer at the current cursor position.
Alt-D | Deletes the information in a specified block area and stores it in the block buffer. While the block is marked, you may press Alt-P to print the information in the block or you may press Alt-W to write the block information to a disk file. Once you've pressed Enter or F10, you may use Alt-I to insert the information from the block buffer at the current cursor position.
Alt-G | Moves the cursor to the line specified.
Alt-I | Inserts the contents of the block buffer at the current cursor position.
Alt-P | Prints the information in a specified block if a block is currently marked. Otherwise, it prints all the information in the text file.
Ctrl-Y | Deletes the information in the current line. The information is not stored in a buffer.
Escape | Exits the Text Editor without saving any changes. After you press Escape, answer y to the prompt Abandon (y/n).


User-Directory

Creates a user directory (usually for network use) and copies preference files into that directory.

In the User-Directory dialog box, enter both the user's directory name and the source directory. The source directory must contain the .def files that you want to place into the user's directory.


Tools Resource

Tools Resource commands allow you to manipulate the contents of the Resource Library. The Resource Library stores files such as drivers, descriptors and fonts and is created automatically when you install SmartWare. The file will have an .srl extension indicating that it is the system resource library. The file will be placed in your system directory under the name resource.srl. You can also create a local library, which will have an .lrl extension (resource.lrl).


Tools Resource Commands

Because descriptors, drivers, and fonts must sometimes be altered or copied individually, the library has commands that enable you to extract and modify one resource. Although they can be extracted out of the library, SmartWare cannot use a resource as an individual file. You must copy it back into the library before SmartWare can use the resource.

Three commands enable you to use the Resource Library.
*** Tools Resource View
** Tools Resource Extract
** Tools Resource Modify


Tools Resource Extract

Extract copies a resource to a specified location. Used alone, the command allows you to store a resource in a different directory or on a floppy. Used in combination with the Tools Resource Modify command, you can create a local library.

You may wish to copy a resource to a floppy so that another SmartWare user can access the resource and copy it into their Resource Library. If you and the other user are on the same network, you can copy the resource to a network directory so the other user can access it. To use the command in this way, follow these steps:

Step 1: Execute Select Tools Resource Extract.

Step 2: The options Local and System are displayed. Select the one you need. The contents of the library are displayed.

Step 3: Select a category by pointing to it and pressing Enter.

Step 4: Select a resource. Use the F6 key to highlight one or more files and press Enter or the F10 key.

Step 5: Enter the destination path for the extracted resources.

To copy the resources to a floppy for others' use, simply specify a:. If you and the other user are on a network, specify a common network directory.


Tools Resource Modify

This command allows you to add and delete files from the Resource Library.

To use the command:

Step 1: Execute Tools Resource Modify.

Step 2: The options Local and System are displayed. Select the library you need to modify. The contents of the library are then displayed.

Step 3: Select a category of resources by pointing to it and pressing Enter.

The following four Quick Keys are displayed:
*** F5 Cancel
** F7 Add
** F8 Delete
** F10 Finished

If you selected an empty category, only F7 and F10 are listed.

Step 4: To add a file, select F7 and enter the name of the file you wish to add.

If this file is not in your system directory, enter the complete path. You may wish to use the wild card character (*). The new file will appear in the list followed by [add]. If the file you added replaced a file with the identical name, the new file will appear in the list followed by [refresh].

Step 5: To delete a file, point to the file and select F8. The word [delete] is placed after the file. Press F10 to exit the screen.


Tools Resource View

This command displays the contents of the local or system library.

To use the command:

Step 1: Execute Tools Resource View.

Step 2: Select Local or System.

The categories of the library are displayed followed by the number of resources stored in each one.

Step 3: To view the resources within a category, point the arrow at a category and press Enter.


Tools Edit-Printer

The command Tools Edit-Printer gives you access to the Descriptor Editor. This command is available only on the Main Menu. The Descriptor Editor is used to modify printer descriptors, which are files that "describe" in a binary format the capabilities of a printer.

You should change the name of any descriptor you alter so the original will be preserved. To do this, simply change the name after Descriptor Name: before saving the file.

The Editor is divided into ten sections. Each section addresses an aspect of the printer's capabilities. For help information on any of these topics, point to the section in the list below and press Enter. If you need more general information about the Descriptor Editor, refer to the Software System Manual.

General Description
Paper Path(s)
Paper Size(s)
Font(s)
Proportional Space Table
Character Generation Table
Movement and Graphics Commands
Font Sequences
Printer Resolution
Color Sequences


General Description

The prompts in this section summarize the printer's behavior. In the case of a cartridge descriptor, this section lists the cartridge name only.

Cartridge Description lists the cartridge name.

Printer Description lists the descriptor name. When modifying descriptors for your own use, you can rename the file anyway you like.

Comments 1, 2, 3 should be used to supply helpful information about the descriptor. Each field can contain up to 255 characters.

Driver lists the names and descriptions of the currently available drivers. The correct driver for the currently loaded descriptor will be highlighted. To move from one printer driver to another, use Right-Arrow to move forward through the list and Left-Arrow to move backward through the list.

If you plan to create a new descriptor, you should choose the descriptor most like the one you are attempting to create and modify accordingly. Because drivers are so closely linked to descriptors, you will almost always select a descriptor that uses a printer driver appropriate for the descriptor you are creating.

If the descriptor operates a laser printer, the type of laser also will be highlighted.

Reset Sequences are sent at the beginning and end of a print job. It is recommended that you use them, particularly if you are working on a network where users may be using applications other than SmartWare. They restore a printer to its factory settings. In the case of laser printers, reset commands also move the print position to the left margin at the top of the next form.

Some reset sequences restore the printer to its factory settings after printing everything in the print buffer, while others execute immediately, deleting anything that may be in the buffer. Read your printer manual carefully for this information.

Start of Print Job Sequence prepares the printer for the beginning of a print job. The codes needed to prepare a printer for printing vary. Typical codes set the graphics resolution and emulation mode. Some printers do not require a start job sequence.

End of Print Job Sequence indicates when a print job is finished. Most printers do not require an end sequence.

Portrait Sequence is used to print a page in portrait orientation. Because portrait is the default orientation, many printers do not require a portrait command sequence. If, however, you plan to switch between portrait and landscape printing, the portrait sequence should be included.

SmartWare changes the orientation only when between pages. You cannot print part of a page in portrait and then switch to landscape to print the rest of the information. If your printer supports rotatable fonts, you cannot invoke a landscape font anywhere on a portrait page.

Landscape Sequence is needed for printing a page in landscape orientation for non-PostScript printers. If this prompt is empty, SmartWare will not change the printer to landscape mode.

Available Font Cartridge Slots should indicate how many cartridge descriptors are available on your printer, unless no cartridge descriptors were included in the Resource Library, in which case you should enter 0. If cartridge descriptors were included for your printer, enter the number of slots available on your printer. The Left-Arrow and Right-Arrow keys move the highlighter through the list.

If you select one or more cartridge slots, Font cartridges (*.ccd) is displayed. This field lists a name template that generically represents all of the cartridge descriptors associated with that particular printer.

Bottom of Page Before End-of-Page Actions are usually a form feed (FF). Some printers may combine a form feed with a move to the left-hand margin. Most printers do not need the print position to be at the bottom of the page in order to execute a form feed. In general, if your printer was manufactured after 1985, this setting will almost always be No. Some of the printers that would require the print position to be at the bottom of the page include:
*** Generic IBM Graphics/Proprinter
** Generic Epson FX-80, draft and near letter quality
** Okidata ML-84 Step 2, low resolution graphics, high resolution graphics, and in character mode
** Diablo 630 Daisy Wheel
** Primage 90 Daisy Wheel
** NEC Spinwriter 8800, prop bold PS8 print wheel

Page Start Sequence sends a command to the printer indicating a new page. Most printers do not require a page start command.

Page End Sequence sends a command to the printer indicating the end of a page. All printers need such a command. For most printers, the sequence includes a carriage return and a form feed (CR, FF).

Default Paper Path lists the default mechanism by which paper is sent to the printer. The default is usually determined by the factory switch setting.

Default Paper Size lists the default paper size. The default is usually determined by the factory switch setting. In the United States, the default is usually Letter. In Europe, the standard is A4. The default paper size must be represented in one of the Paper Size sections.

Portrait Duplex Set/Reset Sequence allows for printing text and graphics on both sides of the paper. If your printer supports duplex printing, enter the control codes that set and reset this feature.

Landscape Duplex Set/Reset Sequence allows for printing text and graphics on both sides of the paper. If your printer supports duplex printing in landscape orientation, enter the control codes that set and reset this feature.


Paper Path

This section specifies the mechanism by which paper is sent to the printer. There can be as many paper path groups as there are valid paper paths.

Quick Keys F7 and F8 are displayed when pointing to any line within a paper path group. F7 creates a new path group. The new group will be empty except for the path setting Paper Tray, which is displayed automatically. F8 deletes the group to which you are pointing.

Using Right-Arrow you can cycle forward through the possible paths. The Left-Arrow key moves backwards through the options.

Path Prefix initiates the path command, informing the printer driver of which path to use to print the job. Your printer may or may not use a paper prefix command.

Include Paper Size Sequence indicates whether the printer driver will use the size information it finds in the corresponding Paper Size group (discussed in the next section). If you respond No, the paper size information is not needed to set the path.

Path Suffix ends the use of this paper path. Your printer may or may not require a suffix sequence.


Paper Size

This section supplies the printer with size information, hard margins, and portrait and landscape margins and sequences. There can be as many paper size groups as there are valid paper sizes.

Quick Keys F7 and F8 are displayed when you are pointing to any line within a paper size group. F7 creates a new size group. The new group will be empty except for the size setting US Letter, which is displayed automatically. F8 deletes the group to which you are pointing.

Using Right-Arrow you can cycle forward through the paper size choices. The Left-Arrow key moves backwards through the list.

Valid Paths indicate available paths for the paper size described. If you have added or deleted a feed mechanism or tray, use F6 to select or deselect the appropriate paths.

Portrait/Landscape Hard Margins are preset boundaries outside of which no text or graphics can be printed. Laser printers commonly have hard margins, whereas dot matrix printers rarely do. If your printer supports landscape as well as portrait printing, margins must be set for both orientations. The margin directions (top, left, bottom, and right) are absolute.

Portrait Size Sequence contains the paper size information for portrait orientation. It is used only if a Paper Path group calls it, which is indicated in the second prompt of the Paper Path group, Include paper size sequence:.

Landscape Size Sequence contains the paper size information for landscape orientation. It is used only if a Paper Path group calls it, which is indicated in the second prompt of the Paper Path group, Include paper size sequence:. Whether the size sequence is used varies from printer to printer. Some printers such as the HP Series II use the same size sequence for both portrait and landscape orientation. Other printers such as the Canon Series II use a different sequence for each orientation.


Fonts

The fonts described in the Descriptor Editor are available to the printer and are reflected in the Font Prompter within SmartWare. Each font is represented by a group of information beginning with the identification number and ending with the font attribute information.

There are cases where one font group describes more than one font attribute, e.g., italics and bold. Generally, this is based on whether separate space tables, which specify the width of each character in a font, are needed to accommodate different attributes. That is, if a bold "a" is no wider than a normal weight "a," then separate font groups are not needed to describe the bold font and the normal font.

The number that follows Font is an identification number between 0 and 65356. This number must be unique within the printer descriptor and any associated cartridge descriptors. This number is used to relate the valid proportional spacing tables and character generation tables to the font group.

Availability refers to the font's orientation: Portrait, Landscape, and Both.
*** Portrait text prints parallel to the short side of the paper.
** Landscape text prints parallel to the long side of the paper.
** Both prints both ways.

Source refers to the storage location of a font. Three options are possible: Internal, PostScript, Cartridge.
*** Internal fonts reside within the printer ("native fonts")
** PostScript fonts are available only with PostScript laser printers. To select PostScript, you must have a psft*.* file in your Resource Library.
** Cartridge fonts are supplied in a cartridge that plugs into a printer.

Name refers to the name of the font. There are two options.
*** Standard font is the default internal font that is mapped to the Smart Character Set.
** Other fonts are any that are not the standard font, as defined above. There are no syntax rules for enter an "other" name.

Height is the size of the font in points. The Descriptor Editor requires that a font's height be entered as an integer. Because fonts frequently are sized at a more precise level than a whole number, the point size must be entered in decipoints. For example, if you have an 8.5 point font, you would enter 85.

Start Sequence initiates the use of this font and must be sent to the printer before any characters can be printed.

End Sequence ends use of the current font. Two cases might require one: laser printers that store or "cache" fonts that must be discarded before invoking a new font and dot matrix printers that must return to a default state before invoking a new font.

Character Set is a collection of letters, numbers, punctuation marks, and symbols. The Smart Character Set is fully supported only by filled-area fonts. The other sets are mapped to the Smart Character Set and will use as much of the Smart set as possible. If the Smart set defines a symbol that is not available in these sets, a space will be substituted.

If you choose an internal character set, your printer will use one of its native character sets. Your printer manual should list the printer's internal character sets. Remember that if you use one of your printer's internal character sets, the results will be reflected only in your output. The characters displayed on your screen may or may not match the set depending on the type of screen driver you have installed.

Underscore Thickness is measured in pixels. Underscores are drawn either by SmartWare or automatically by the printer. This setting needs to be filled in only if the underscore is being drawn by a SmartWare graphics command. While most printers support underscore capabilities, if any of the following are true, SmartWare is responsible for drawing the underscore:
*** You are using a daisy wheel printer (d_wheel.pdv).
** An Underscore set sequence is not set in the Font Sequences section.
** You have underscores in a microjustified paragraph.

Underscore Thickness (Landscape) is measured in pixels. If nothing is entered in this field, SmartWare uses the line thickness for portrait printing.
*** Offset from baseline is the number of pixels that are placed between the underscore and the baseline.

Double Underscore Thickness is measured in pixels. Double underscores can be printed by SmartWare or automatically by the printer. In order for SmartWare to be able to draw a double underscore the descriptor must contain a graphics command and a thickness setting. If your printer can draw double underscores, the Double Underscores set and reset sequences must be set in the Font Sequences section.
*** Offset from baseline (upper) determines how many pixels are placed between the baseline and the first of the two underscores.
*** Offset from baseline (lower) determines the number of pixels between the baseline and the second of the two underscores.

Strikeout Line Thickness is measured in pixels. The strikeout attribute can be drawn automatically by the printer or by SmartWare. Most printers do not support automatic strikeout capability.
*** Offset from baseline determines how many pixels are placed between the baseline and the strikeout line.

Landscape Offset Adjustment is used for non-PostScript printer. This value is needed to make the underscores, double underscores, and strikeouts drawn by SmartWare achieve the same alignment as the underscores, double underscores, and strikeouts drawn automatically by non-PostScript printers.

Average/Maximum Character Width is measured in pixels and is determined by the font and the horizontal printer resolution.

Monospaced fonts allocate the same amount of horizontal space for every character, regardless of its width or shape. That is, an "i" uses the same amount of space as a "w." Each character in a proportionally spaced font is allocated a width proportional to its shape and width. An "i" would require much less space than a "w."

To determine the width of a monospaced font, divide the resolution of the printer by the characters per inch (cpi) measurement of the font. For example, assume you are printing a 10 cpi font at 300 dots per horizontal inch (dpi). This means the printer prints 300 pixels per horizontal inch. If you divide the horizontal resolution by cpi, the result will be the average and maximum character width.

To determine the width of a proportional font, average all of the characters in the font to determine the average width. Using the information in the Proportional Spacing Table, you can enter the widths for characters 32 through 255 into a worksheet and write a formula that averages the numbers. (Use F9 to move directly to the Proportional Spacing Table category.) The maximum character will be the character with the largest width.

Character Up is used by dot matrix printers to determine where to move the print head. The formula is:

vertical movement value - character up = destination

Dot matrix printers use this value to determine the location of strikeouts also.

Normal/Condensed/Compressed/Expanded Font Exists A normal font is not condensed, compressed, or expanded. Normal should be selected if the font is proportionally spaced or if the font is a 10 cpi monospaced font. Condensed, compressed, and expanded fonts are always monospaced fonts. A condensed font is 12 cpi. A compressed font is usually 15 to 17 cpi. An expanded font is usually 5 to 6 cpi.

Attribute Combinations. Attribute combinations define the possible characteristics of the current font. The attributes are divided into the following categories:
*** Slant: normal, italic
** Weight: normal, light, bold, extra bold
** Modifications: strikeout, underscore, double underscore, outline

The number of attributes you can select in the slant and weight categories depends on the font. If the font's characters do not vary in width when their weight or slant is changed, then you may select every valid attribute. For example, if the group describes a 10 point monospaced font in which the bold characters require no more horizontal space than the normal weight characters, you could highlight both normal and bold in the weight category.

If the font's characters do vary in width when their weight or slant is changed, then you may select only one attribute from each category. For example, if the group describes a 12 point proportionally spaced bold font, you should highlight only normal slant and bold weight in the first group. In this case the bold characters will require more horizontal space than the normal weight because the font group describes a proportionally spaced font.

The modifications category is independent of character width issues. You can select as many modifications as are supported by your printer or printer descriptor file.


Proportional Space Tables

This section lists the width in horizontal resolution units of each character of a proportional font. Space tables are not needed for monospaced fonts.

The field immediately following the prompt contains the font identification number. It is possible, though rare, that one proportional space table could describe more than one font. When you enter a number into this field, the table is displayed. Cells are available for ASCII characters 0-255.


Character Generation Tables

A character generation table allows you to create characters that are not available in your current character set. The numbers that follow the prompt Character Generation Table for fonts: are the identifier numbers of the fonts that will use the "generated" character. To display a table, assign a font identifier number. More than one font number can be used.

The table provides cells for ASCII characters 0-255. The Enter, Tab, and Shift-Tab move the cursor position from one cell to the next or, in the case of Shift-Tab, to the previous cell. The Up-Arrow and Down-Arrow keys will move the pointer vertically through the table.

The following syntax conventions should be used if you need to build a character from existing characters:

\\ = insert backslash
\- = move back to the beginning of the character cell
\+ = move forward one horizontal resolution unit

If you are creating a character that will be used as part of a proportional font, you will need to consider whether the character width needs to be adjusted. If you have built a character that is wider than the original character, alter the width in the proportional space table to accommodate the new character.


Movement and Graphics Commands

A printer's movement can be absolute or relative. A printer that uses absolute movement determines the distance of a movement by referencing the original print position (either the top of the physical page or the top of the printable area). A printer that uses relative movement determines the distance of a movement by referencing the last print position. Your printer manual will specify which kind of movement is supported by your printer.

The direction of movement can be vertical and horizontal. These movements can be used together to move the print position within the printable area. Laser and other page-oriented printers use absolute movement to move in both directions. Dot matrix printers usually use relative movement for vertical commands and absolute movement for horizontal commands.

Vertical Positioning. Vertical positioning controls any movement on the y axis. The value that indicates where to move on the y axis must be translated into a new format before it can be used by the printer. The prompts that translate the value are:
*** Command Prefix:
** Format:
** Data Flag:
** Offset Value:
** Maximum Size Value:
** Command Suffix:

Command Prefix. The command prefix informs your printer that a move command is being sent.

Format. Your printer uses one of the following formats to translate the information:
*** ASCII
** LSB/MSB (least significant byte/most significant byte)
** MSB/LSB (most significant byte/least significant byte)
** AMT Type
** Toshiba (available only for relative movement)

To determine the format used by your printer, look in your printer manual under the appropriate command, in this case the vertical movement command. An ASCII format is indicated if the documentation refers to digits or the examples show values enclosed in quotes or that begin with zeros. A binary format (LSB/MSB and MSB/LSB) is indicated if the documentation refers to binary values. Many printer manuals use the BASIC language to illustrate control codes. If CHR$ followed by a value in parentheses (e.g., CHR$(34)) is used, the format is binary. If you are using an AMT or Toshiba printer, you should choose the AMT or Toshiba format respectively.

Data Flag. The data flag indicates how many bytes make up the data portion of the command. In the case of vertical positioning, the data portion of the command tells the printer driver where or how far to move the print position. The value you enter depends on the format you selected in the previous prompt.
*** ASCII. Refer to the printer manual to find out how many digits are required by the printer driver for that particular command. If any number of digits may be sent, enter a 0. If a specific number of digits must be sent, enter that number.
** LSB/MSB. Enter 0 or 1. A 0 equals one byte and sends the least significant byte only. A 1 equals two bytes and sends the least significant byte first, followed by the most significant byte.

To determine whether to enter a 0 or a 1, look in the printer manual for this command and see whether the range a value can have is greater than 255. If it is, two bytes must be sent, in which case you would enter a 1. If a value's range is less than 255, one byte will be sent, in which case you should enter a 0.
** MSB/LSB. Enter a 0 or 1. A 0 equals one byte, sending the most significant byte only. A 1 equals two bytes and sends the most significant byte followed by the least significant byte.

To determine whether to enter a 0 or a 1, look in the printer manual for this command and see whether the range a value can have is greater than 255. If it is, two bytes must be sent, in which case you would enter a 1. If a value's range is less than 255, one byte will be sent, in which case you should enter a 0.

There may be some cases when the printer expects two bytes even though the value fits in one byte. These cases will usually be indicated in your printer manual.
** AMT Type. Enter either 0 or 1. Just as with the LSB/MSB format, entering 0 sends the least significant byte and entering 1 sends the least significant byte first followed by the most significant byte. The difference between the two formats is in the information sent as a result of your choice. AMT Type uses the following formulas:

0 sends x % 128
1 sends x % 128 followed by x / 128
** Toshiba. This field is ignored. Toshiba printers break the value into three 4-bit groups and convert each part into an ASCII character ranging between @ and O.

Offset Value. Some printers may require that another value be added to the movement increments before the number is converted. If your printer does, enter that value in this field. Otherwise, leave it at 0.

Maximum Size Value. Some printers have a limit on the size of vertical movement that can be made in one command. If the distance exceeds the maximum, two or more commands will be sent until the distance is achieved. Your printer manual will indicate if this is the case and list the maximum value.

Command Suffix. The command suffix ends the movement command. It may or may not be required by your printer; refer to your printer manual.

Vertical Movement Command Causes Return to Left Margin. This command is used for older printers that move the print head to the left margin each time a vertical move is made.

Horizontal Motion Index. This command is used only for daisy wheel printers.

Horizontal Positioning. Horizontal positioning controls any movement on the x axis. The values that determine where or how far the print position moves must be translated into a new format before the printer can use them. The prompts that allow you to specify the format will appear when you select either absolute or relative vertical positioning. The prompts are:
*** Command Prefix:
** Format:
** Data Flag:
** Offset Value:
** Maximum Size Value:
** Command Suffix:

Command Prefix. The command prefix informs your printer that a move command is being sent.

Format. Your printer uses one of the following formats to translate the information:
*** ASCII
** LSB/MSB (least significant byte/most significant byte)
** MSB/LSB (most significant byte/least significant byte)
** AMT Type
** Toshiba (available for relative movement only)

To determine the format used by your printer, look in your printer manual under the appropriate command, in this case the vertical movement command. An ASCII format is indicated if the documentation refers to digits or the examples show values enclosed in quotes or that begin with zeros. A binary format (LSB/MSB and MSB/LSB) is indicated if the documentation refers to binary values. Many printer manuals use the BASIC language to illustrate control codes. If CHR$ followed by a value in parentheses (e.g., CHR$(34)) is used, the format is binary. If you are using an AMT or Toshiba printer, you should choose the AMT or Toshiba format respectively.

Data Flag. The data flag indicates how many bytes make up the data portion of the command. In the case of vertical positioning, the data portion of the command tells the printer driver where or how far to move the print position. The value you enter depends on the format you selected in the previous prompt.
*** ASCII. Refer to the printer manual to find out how many digits are required by the printer driver for that particular command. If any number of digits may be sent, enter a 0. If a specific number of digits must be sent, enter that number.
** LSB/MSB. Enter 0 or 1. A 0 equals one byte and sends the least significant byte only. A 1 equals two bytes and sends the least significant byte first, followed by the most significant byte.

To determine whether to enter a 0 or a 1, look in the printer manual for this command and see whether the range a value can have is greater than 255. If it is, two bytes must be sent, in which case you would enter a 1. If a value's range is less than 255, one byte will be sent, in which case you should enter a 0.
** MSB/LSB. Enter a 0 or 1. A 0 equals one byte, sending the most significant byte only. A 1 equals two bytes and sends the most significant byte followed by the least significant byte.

To determine whether to enter a 0 or a 1, look in the printer manual for this command and see whether the range a value can have is greater than 255. If it is, two bytes must be sent, in which case you would enter a 1. If a value's range is less than 255, one byte will be sent, in which case you should enter a 0.

There may be some cases when the printer expects two bytes even though the value fits in one byte. These cases will usually be indicated in your printer manual.
** AMT Type. Enter either 0 or 1. Just as with the LSB/MSB format, entering 0 sends the least significant byte and entering 1 sends the least significant byte first followed by the most significant byte. The difference between the two formats is in the information sent as a result of your choice. AMT Type uses the following formulas:

0 sends x % 128
1 sends x % 128 followed by x / 128
** Toshiba. This field is ignored. Toshiba printers break the value into three 4-bit groups and convert each part into an ASCII character ranging between @ and O.

Offset Value. Some printers may require that another value be added to the movement increments before the number is converted. If your printer does, enter that value in this field. Otherwise, leave it at 0.

Maximum Size Value. Some printers have a limit on the size of vertical movement that can be made in one command. If the distance exceeds the maximum, two or more commands will be sent until the distance is achieved. Your printer manual will indicate if this is the case and list the maximum value.

Command Suffix. The command suffix ends the movement command. It may or may not be required by your printer; refer to your printer manual.

Graphics Prelude sends all of the necessary information at the beginning of a graphics command.

Graphics Command Start signals to the printer that graphic data is going to be sent. If your printer does not use specific movement commands, you may need to set the graphics commands. If you use a daisy wheel printer, which does not print graphics, the graphics commands should be set to No.

If you set the graphics commands to Yes a set of prompts appears that is identical to the positioning prompts, except for two options: Double Three and Tandy. This information serves the same purpose: to translate the values into the appropriate format before they are sent to the printer.
*** Double Three. An option used for printers that do not send the number of graphic bytes in the begin graphics sequence. Instead, these printers send a unique combination of data to signal the end of the graphics data. Usually a "3" or "3,2" is used. When a single byte of graphics data with the value of "3" is being sent, a double three sequence "3,3" is sent. Early Okidata printers use double three.
** Tandy. Valid only for dot matrix begin graphic commands. If you select Tandy, you can specify a 0, 1, or 2 in the Data Flag field. A 0 does nothing to the byte. 1 turns on bit 1. 2 turns on bit 2.

Graphics Command End signals to the printer the end of the graphic data. Many printers do not require this command because the graphics start command includes the number of graphic bytes being sent, implying the end of the graphic data.

Form Length Set sets the length of the page being used by the print job. This field is not used by laser or PostScript printers because they usually embed this information in the page size sequence command. But dot matrix printers must have a form length sequence in order to print. You will also need to use this command when specifying a custom paper size.

The Form length multiplier: is usually set to 6. This number is multiplied by the number of inches in the form to determine the actual length of the form. It is a good idea to include in the Start of print job sequence a control code that indicates that line feeds are 1/6 of an inch. Even if line feeds are 1/8 of an inch, SmartWare translates them as 1/6.

Font Resets. These prompts are used for older printers that require the default printer font to be re-invoked after certain characters or commands are executed. Daisy wheel printers usually need most of the prompts in this section set to Yes.


Font Sequences

These sequences define set and reset commands for a variety of font attributes. Some of these attributes can be achieved either automatically by the printer or using SmartWare graphics commands. Font sequences should be completed only if the printer can automatically generate the attribute.

Normal Width Set/Reset Sequence. Normal fonts are not condensed, compressed, or expanded.

Condensed Set/Reset Sequence. Condensed fonts are monospaced, usually 5/6 the width of a normal font (12 cpi). If this is not the case, these prompts should be empty.

Compressed Set/Reset Sequences. Compressed fonts are monospaced, usually 5/8 the width of a normal font (15 to 17 cpi).

Because printer manuals specify character width in characters per inch (cpi), rather than inches per character (ipc), you must convert characters per inch to width. See the Software System Manual more more information.

You must enter these values as integers. So, if the normal font is 10 cpi and the compressed font is 16.66, you would enter 1000 as the nominator and 1666 as the denominator.

Expanded Set/Reset Sequence. Expanded fonts are monospaced, usually 5 to 6 cpi.

Because printer manuals specify character width in characters per inch (cpi), rather than inches per character (ipc), you must convert characters per inch to width using the formula on page 196 in Software System Manual.

Underscore Set/Reset Sequence. This sequence must be set in order for the printer to automatically draw an underscore. While most printers have single underscore capability, the following circumstances require that SmartWare print underscores.
*** When there are underscores in the last line of microjustified text
** When using a daisy wheel printer

If you are going to use SmartWare to generate all underscores, this font sequence should be empty, a graphics command should be set, and a width should be specified for underscore thickness in the font groups.

Outline Set/Reset Sequence. This sequence allows use of outline fonts. If your printer supports them, this sequence needs to be completed.

Double Underscore Set/Reset Sequence. This field is usually empty because most printers cannot automatically generate double underscores. If you wish to use double underscores you must have a graphics command and a double underscore thickness specified.

Light Set/Reset Sequence. Light fonts are lighter in weight than normal fonts.

Bold Set/Reset Sequence. Bold fonts have a heavier stroke weight than the normal font.

Extra Bold Set/Reset Sequence. Extra bold fonts have a stroke weight that is heavier than the bold font.

Strikeout Set/Reset Sequence. Strikeout fonts have a continuous horizontal line drawn through the middle of text characters.

Normal Weight Set/Reset Sequence. Normal weight fonts have a regular stroke weight. Most printers do not require that these sequences be set.

Italics Set/Reset Sequence. An italic font slants to some degree to the right. The degree to which the characters slant depends on the typeface.

Normal Set/Reset Sequence. A normal font has a upright posture. Most printers do not require that these sequences be set.

Transparent Print Set/Reset Sequence. This sequence prints characters usually interpreted as control codes by your printer. The command is used only by fonts that use one of your printer's native character sets.

For example, low ASCII characters, 0 to 31, are usually treated as unprintable characters; they instead cause a printer action such as a form feed or carriage return. The Transparent command will treat these characters as printable characters in files that use a native character set.

Lowest/Highest Character. These prompts allow you to specify the range of ASCII characters defined by your printer as unprintable.


Printer Resolution

Printer resolution is measured in dots per inch (dpi) and requires a vertical and horizontal value. The horizontal and vertical values are independent of each other. Dot matrix printers frequently have different values for each measurement. Lasers usually use the same value for both measurements.

Printer resolution controls not only the number of dots used to print text and graphics, but where printing begins and in what order data is sent to the printer. Several of these prompts apply only to dot matrix printers.

Vertical Resolution. This value determines the number of pixels (dots) printed per vertical inch. The scale used for vertical resolution does not have to match that of the horizontal resolution. This is common in dot matrix printers.

Horizontal Resolution. This value determines the number of pixels (dots) printed per horizontal inch.

Vertical Dot Size Ratio Numerator/Denominator. This ratio expresses the spatial relationship between the vertical resolution and the diameter of the dot. Based on this information the printer driver determines the number of dots to print to achieve varying gray scales. Without this information, some printers would create so much overlap between dots in a column that fill areas would be overly dense from excess ink.

To calculate the ratio, divide the vertical resolution by the dot diameter. For example, for a 9-pin printer with a vertical resolution of 1/216 in. and a pin diameter of 1/72 in., the formula would be:

     216 / 72 = 3 or 3/1

The result is entered as follows:

Vertical pinsize ratio numerator: 3
Vertical pinsize ratio denominator: 1
NOTE: Laser descriptors will always require these values to be 1.

Horizontal Dot Size Ratio Numerator/Denominator. This ratio expresses the spatial relationship between the horizontal resolution and the diameter of the dots. Based on this information the printer driver determines the number of dots to print to achieve varying gray scales. Without this information, some printers would create so much overlap between dots in a column that fill areas would be overly dense from excess ink.

To calculate the ratio, divide the horizontal resolution by the pin diameter. For example, for a printer with 1/240 vertical resolution and a pin diameter of 1/72, the formula would be:

     240 / 72 = 3.33 or 10/3

The result is entered as follows:

Horizontal pinsize ratio numerator: 10
Horizontal pinsize ratio denominator: 3
NOTE: Laser descriptors will always require these values to be 1.

Vertical/Horizontal Movement Resolution. These commands provide an alternative measurement for printers that cannot use the graphic resolution to move the print position. For example, the original HP LaserJet prints graphics at 300 dpi, but the vertical movement commands are measured in decipoints. In this case, Vertical movement resolution (increments/inch): would need to list 720.

These values should be zero if the printer uses the vertical and horizontal resolution for movement commands as well as graphics commands.

Number of Passes to Achieve Vertical Resolution. This value determines the number of passes needed to achieve the printer's vertical resolution. Some dot matrix printers require the print head to make more than one pass because the vertical resolution is a much finer increment than the space between the center of one dot to the center of the next dot.

To determine the number of passes needed, divide the vertical resolution by the dot center to dot center spacing.

This number should be 1 for most printers that support graphics except dot matrix printers.

X/Y Origin. The x/y origin is located at the top left-hand corner of either the physical page or the printable area. The physical page is defined by the edges of the paper. The orientation (portrait vs. landscape) of the paper determines which edges are used to locate the x\y origin of the physical page. The printable area is defined by the "hard margins," which are preset boundaries outside of which text and graphics will not print. The orientation of the paper affects which boundaries are used to locate the x/y origin.

Generally, the x/y origin is at the top of the printable area for laser printers and at the top of the physical page for dot matrix printers.

Top Pin that Fires in Graphics Mode. This prompt indicates which pin strikes the paper first. In many dot matrix printers the first pin does not fire in graphics mode. For example, a 24-pin printer may use 18 of its pins in graphics mode. These 18 pins may be centered among the 24 pins, leaving several unused pins on each end of the print head.

The top pin equals 0, the second pin should be 1, and so on. This field is ignored for laser printers.

Graphics Data Bits Sent to Printer. This number indicates to the printer how many bits in each byte contain graphics data. If all eight bits contain data, they can be sent to the printer in their natural order. However, if fewer than eight contain graphics data, the following prompt appears:
*** Bit justification: LSB MSB

This second prompt determines whether the data bits are moved to the leftmost position, which is the least significant bit (LSB), or moved to rightmost position (most significant bit (MSB).

Bit Controlling Top Pin. This prompt determines which end of the graphics byte is sent to the printer first. If you select LSB, the least significant bit is sent to the topmost pin. If you select MSB, the most significant bit is sent to the topmost pin.

Number of Dot Positions in a Graphic Column. This value represents the number of dot positions in a column. Two factors determine this number: the number of pins in the print head and the graphics mode.

A dot column can have as many potential dot positions as there are pins in the print head. Each position represents one data bit; each group of eight represents one byte of graphic data.

Two Adjacent Horizontal/Vertical Dots Can Print in One Pass. Some printers are limited mechanically from printing two dots in succession. This is commonly caused by the pins' inability to fire rapidly enough or the print head overheating from firing too rapidly.

Database Report Line Thickness. This prompt should list the number of vertical and horizontal pixels that are used when SmartWare creates any lines in a database report, such as the lines that you can select to enclose a report.


Color Sequences

This section determines the color palette for text and graphics.

Color On/Off Sequences (A, B, C, D). The on and off sequences are responsible for turning on or off each of the three or four colors that comprise a color ribbon. The colors vary depending on the kind of ribbon used by your printer. Process ribbons (yellow, magenta, cyan, black) and RGB ribbons (red, green, blue, black) are the most common.

Colors A, B, C, and D do not represent specific colors. They represent an absolute order in which the four ribbon colors are printed. SmartWare prints color A first, color B second, and so on. You determine which colors will be represented by A, B, C, and D by entering the appropriate control sequence in that field.

In most cases, it is best to print the lightest ribbon colors first and move progressively to the darker ribbons; this prevents the lighter ribbons from getting contaminated with ink from the darker ribbons. However, if you want a darker ribbon to print before a lighter ribbon, assign the darker ribbon to Color A.

Off sequences turn off a ribbon color. Not all printers use off sequences; instead they simply turn on black to turn off a color. Check your printer manual.

Color Text. The table following the on/off sequences defines the colors used to print text. The colors used to print text are defined by selecting different ribbon combinations to form the 16 SmartWare colors.

The color represented by each column is determined by the control sequence you entered in the on/off fields for each color. The Up-Arrow and Down-Arrow or Tab and Shift-Tab keys move the pointer from one color to the next. The Right-Arrow and Left-Arrow keys move the selector from one column to the next. The Quick Key F6 selects and deselects the color.

To create a color, highlight the color or combination of colors that create the desired color. For example, assume your printer uses a process ribbon and you have established that Color A is yellow, Color B is magenta, Color C is cyan, and Color D is black. For SmartWare color green you would highlight Color A and Color C. On the other hand, if your printer used an RGB ribbon and you have established that Color A is red, Color B is green, Color C is blue, and Color D is black, you would highlight Color B only.

Color Graphics. The second table defines the colors used to create graphics. The colors used for graphics are formed by the 16 possible combinations of ribbons A, B, C, and D.

Each column corresponds to one of three color spectra: red, green, and blue. Each column lists values that specify the percentage of light reflected by the color that results from the ribbon combination. The red column specifies the percentage of red light reflected by each ribbon combination. The green column specifies the percentage of green light reflected by each ribbon combination. The blue column specifies the percentage of blue light reflected by each ribbon combination.

Valid percentages range from 0 to 100. Zero indicates that the combination reflects 0% of the light in that spectrum; 100 indicates that it reflects 100% of the light in that spectrum.
NOTE: If there are ribbon combinations that you do not want your printer to use, assign them the same percentages as the first entry in the table. This first entry, labeled None, will usually list percentages of 100% in each column, describing white. White, which is the most common color of paper, produces white on white. If you are using a different color of paper, the percentages in the None category will have to reflect that color.


Quit Commands

The Quit commands allow you to transfer from one module to another module, go to the Main Menu, or return to the operating system. The Quit options vary depending upon which module you are leaving. Notice that the module you are leaving does not appear among the Quit options on the screen, but does appear on the following option list.


 Options for Quit include the following:

Quit. Returns to the operating system.
Main-Menu. Returns to SmartWare's Main Menu.
Communications. Leaves the current module and enters SmartWare Communications.
Database. Leaves the current module and enters SmartWare Database.
Spreadsheet. Leaves the current module and enters SmartWare Spreadsheet.
Wordprocessor. Leaves the current module and enters SmartWare Wordprocessor.

If you decide that you do not want to leave the current module after you have selected Quit, press Escape.


 On pulldown menus, the File menu provides access to the open file, change module, and exit commands. The Tools menu provides access to the Calculator, directory commands, the Text-Editor, and the preference editors. The Remember menu allows you to run SPL programs.


 On pulldown menus, Open loads a file and starts the appropriate module. For example, if you open a document file, the Word Processor module will be started.


 On pulldown menus, Exit leaves SmartWare and returns you to the operating system.


 Communications. Access the Communications module.


 Database. Access the Database module.


 Spreadsheet. Access the Spreadsheet module.


 Word Processor. Access the Word Processor module.


If you encounter a protection violation, an error screen is generated and the following choices appear:

Select Quit to DOS to immediately exit ANGOSS and return to DOS. This is the recommended procedure.

Select Resume ANGOSS to attempt to return to the module you were in and give you an opportunity to save your files. Note that you may or may not be successful at saving. Exit ANGOSS as soon as possible.


Introduction to Formulas

A formula is a method of expressing instructions that describe how your computer should perform a specific calculation. When you write formulas in SmartWare, you express these instructions in a language that SmartWare understands. Each of the elements that you can use in this language is explained in detail in the following sections.

SmartWare features powerful, advanced software technology for executing commands and calculating formulas. When you run SmartWare, a complete calculation system is placed in your computer's memory, ready to accept and translate your commands and instructions. Because this system is memory resident, SmartWare is exceptionally quick and responsive to your instructions. Also, because the calculation system is used by all modules, you can use the same formula language for all your applications.

You can use formulas in many ways in SmartWare. These are some of the most important uses for formulas:
*** Calculating and displaying results in Spreadsheet cells.
** Calculating formulas with the SmartWare Calculator.
** Calculating formulas in the Text Editor and the Project Editor.
** Defining calculated fields in Database views.
** Defining query selection criteria in the Database Query Editor.
** Computing formulas typed in Word Processor documents.
** Calculating values and constructing expressions in SmartWare's Project Development Language.

However you use SmartWare, you will find that working with formulas increases your power and productivity.


Types of Formulas

Arithmetic and other mathematical calculations involving numbers are important applications for SmartWare's formulas. However, formulas can also be used to instruct SmartWare to perform a variety of other operations. Formulas can be classified in five categories, according to the type of data used in the calculation and the kind of operation performed in the calculation.

Formula Type | Type of data | Example
Numeric | Numbers, values, amounts | 2 + 2
Text | Text, words, alphanumeric data | "cat"|"entate"
Date | Dates | DAYNAME("7/6/89")
Time | Dates and times | ADDMINUTES ("16:13:02", 4)
Logical | All types of data | IF Amount > 0 THEN Amount ELSE "Error"

Numeric. Numeric formulas specify calculations involving mathematical operations on numbers. SmartWare provides a broad range of special functions for numeric formulas, including statistical, financial, and trigonometric. These functions enhance SmartWare's ability to realize sophisticated engineering, business, and scientific applications quickly and easily.

Text. Text formulas allow you to process and control textual information. You can use text formulas to combine, split, alter, and manipulate words, phrases, and other strings of text data into useful forms.

Date and Time. SmartWare can perform calculations on date and time information. Date and Time formulas use specially-formatted text and numeric data that represent specific dates and times. With SmartWare's date and time functions you can calculate elapsed time and durations in minutes, hours, days, months, or years. You can also derive the day name of a particular date, add or subtract increments of time, and much more.

Logical. A logical formula is an instruction to examine items of data and render a decision. Logical formulas usually cause the system to choose among alternatives based on a specified set of conditions. These conditions are expressed as statements, called logical expressions, which are either true or false. Thus, a logical formula allows you to create "intelligent" applications that can provide for different responses to various situations.


The Elements of Formulas

Formulas are made up of operators and expressions. An operator specifies a particular operation that is to be performed on data. Expressions provide the data to be operated on. When combined into a properly written formula these two elements provide a complete description of how a calculation is to be performed.


Operators

An operator specifies either a relationship between two expressions or an operation to be performed upon some data. In SmartWare formulas operators are represented by symbols. There are four categories of operators: numeric, text, relational, and logical.


Numeric Operators

Numeric operators perform mathematical operations on numeric expressions. These operators are used only with numeric expressions or expressions returning numeric data. The SmartWare numeric operators are summarized in the following table.

Operator | Meaning | Example
+ | Addition | 1 + 1
-- | Subtraction | 2 -- 1
* | Multiplication | 2 * 2
/ | Division | 4 / 2
^ | Exponentiation | 2 ^ 3


Text Operators

Text operators perform an operation called text concatenation. Text concatenation is the combination of two text expressions into one. You can concatenate with or without a space between the two original expressions. The SmartWare text operators are summarized in the following table.

Operator | Meaning | Example | Result
& | Concatenates text with a space separator. | "in"&"to" | "in to"
| | Concatenates text without a space separator. | "in"|"to" | "into"


Relational Operators

Relational operators express a relationship between two numeric or text items. When you use a relational operator to describe such a relationship you are creating a logical expression. The SmartWare relational operators are summarized in the following table.

Operator | Meaning | Example
= | Equal | 1 = 1
<> | Not equal | 1 <> 0
> | Greater than | 1 > 0
< | Less than | 0 < 1
>= | Greater than or equal to | 1 >= 0
<= | Less than or equal to | 1 <= 1

In this table the meaning of the relational operators is illustrated with numbers. In each example the operator causes the two values to be compared. All these examples are true. When you use relational operators with numeric expressions, SmartWare determines equivalency to a precision of 14 significant digits.

These relational operators can also be used to form logical expressions with text. Text comparisons refer to the ASCII values of the characters.

Examples |  |
"z" <> "Z" | "a" < "z" | "ab"|"cde" = "abcde"

You can use three additional relational operators with text. The operators ! and !! search the first expression for the set of characters in the second expression. The operator == converts all text to lower case for the purpose of comparing text without reference to case. The following examples are true.

Operator | Meaning | Example
! | Contains | "Hello" ! "lo"
!! | Does not contain | "Hello" !! "Hi"
== | Compare ignoring case | "HELLO" == "hello"


Logical Operators

Logical operators are used to connect logical expressions. A logical operator causes each of a pair of logical expressions to be evaluated and results in a value of TRUE (non-zero) or FALSE (zero) for the combination. The following table summarizes SmartWare's logical operators (the examples are true).

Operator | Meaning | Example
AND | True if both logical expressions are true. | "abc" ! "b" AND 1 > 0
OR | True if either logical expression is true. | "abc" ! "d" OR 1 > 0


Member Operator

The member operator is used to access a method (function) or property of either an ActiveX object or a SmartWare object. SmartWare objects such as views and fields have properties and methods. You can create ActiveX controls when designing your view and you can use the CREATE_OBJECT function to create ActiveX automation objects. The following table summarizes SmartWare's member operator.

Operator | Meaning | Example
. | Get a property value. | is_visible = obj.Visible
. | Set a property value. | obj.Visible = True
. | Call an object method (function). | obj.AboutBox()


Operators and Priority

Formulas are generally evaluated from left to right. The order of evaluation of a formula may be different, however, depending on the priority of the operators and the use of parentheses.

An intrinsic priority is attributed to every operator by SmartWare. Expressions are evaluated in an order of precedence according to the priority of the operators they contain. The following list shows the operators in order of priority.

Priority | Operator
1 | . (The member operator)
2 | ^ (Exponentiation)
3 | * (Multiplication) / (Division)
4 | + (Addition) -- (Subtraction)
5 | & | (Text concatenation)
6 | All relational operators
7 | All logical operators

You can use parentheses to control the order of evaluation of a formula. Placing parentheses around an expression indicates that it is to be evaluated before other expressions in the formula.
NOTE: If parentheses are used within other parentheses (i.e., nested), the innermost level receives the highest priority.

For example, the formula 100 * 2 + 3 instructs SmartWare to multiply 100 by 2 and then add 3. By inserting parentheses, you can change the formula so that the addition is performed before the multiplication: 100 * (2 + 3). The result of the first formula is 203; the second yields 500. The use of parentheses in this example alters the normal left-to-right evaluation of the formula.


Expressions

An expression is an item of data in a form suitable for processing or calculating in SmartWare. There are three general categories of expressions: numeric, text, and logical. Two additional categories of expressions, date and time, are specialized forms of the numeric and text expressions.

When calculated, most SmartWare formulas return information as one of these types of expressions. Thus, formulas can serve as expressions within other formulas.


Numeric Expressions

A numeric expression is a form in which you must specify a number or a term that is to be interpreted as having a numeric value. A numeric expression can be in either decimal or hexadecimal notation.

Decimal. Decimal numbers are numbers expressed in base ten. You can express decimal numbers in either normal or exponential notation. The following characters are valid in decimal numeric expressions.

NOTE: The minus symbol used as a negative "operator" indicates that a numeric value is negative. The plus symbol indicates that a number is positive. In SmartWare, numbers are assumed to be positive so the plus symbol is optional. When these operators might be confused with the numeric operators represented by the same symbols, you should place parentheses around the expression to clarify its meaning (see Operators and Priority) .
Character | Meaning | Example
Numerals: 0-9 | Digits (numeric constants) | 123
. or , | Decimal | 123.00
E | Exponent | 1.23E+02
-- | Negative | --123
+ | Positive | +123

Hexadecimal. Hexadecimal notation expresses numbers in base sixteen. Hexadecimal numbers do not include decimal fractions and cannot be expressed in exponential notation. In SmartWare, hexadecimal numbers must be preceded by the characters 0x. The following characters are valid in hexadecimal numeric expressions.

Character | Meaning | Example
Numerals: 0-9 | Digits (dec. values 0-9) | 0x10
Letters: A-F | Digits (dec. values 10-15) | 0x1B

When working with numbers, you must distinguish between the form in which you express the number in a formula and the form in which you want the number to be displayed. Numeric expressions used in formulas must be expressed as a basic number or a formula that returns such a number. SmartWare can interpret and display numbers as currency, percentages, dates, or times. Numbers can also be displayed with or without thousands separators or to a specified decimal precision. A variety of negative number formats is also available in the Spreadsheet. To have numbers interpreted or displayed in special formats, you will use the appropriate SmartWare functions or format display features to control their appearance. The following examples show some typical display formats.

Comment: Although you can choose to display a number with a comma or another thousands separator, do not type the comma when entering the number.
Numeric exp. | Display format | Appears as
100 | Normal, precision 0 | 100
1000 | Currency, precision 2 | $1000.00
.5 | Percent, precision 1 | 50.0%
--10 * 100 | E-Notation, precision 0 | --1.E+03


Text Expressions

A text expression is one or more characters used literally as textual information. Text expressions are sometimes referred to as strings. Each character in a text expression represents itself, not a value, date, or other quantity. For example, the "D" character in the expression "James D. Kempton" represents the letter D (an initial in a name), not the value 0xD hexadecimal (13 decimal).
NOTE: If text expression is used in a numeric formula it is treated as having the value 0.
Comment: Text expressions are sorted alphabetically; numeric expressions are sorted in numeric order.

Unless you are specifically prompted for text information, you must surround a text expression with quotation marks when you enter it. Quotation marks distinguish text from other types of expressions that may employ some of the same set of characters. For example, when a number is surrounded by quotation marks, it is treated as a string of numerals, not as a numeric value. Characters valid in text expressions include (but are not limited to) the following.
*** The lower case and upper case letters of the alphabet.
** The numerals 0-9.
** Common punctuation and graphic symbols.

Text expressions are commonly used to store and process names, addresses, serial numbers and codes, zip codes, and telephone numbers. Here are some examples of text expressions.

NOTE: The quotation marks in these examples are not included in the text expressions. Rather, they delimit the expressions. To display quotation marks as part of a text expression, you must use double quotation marks at both the beginning and the end of the characters you want quoted. The double quotation marks are displayed as a single set of double quotation marks. For example, the expression "I said,""Eureka!""" results in a text expression that looks like I said, "Eureka!".
"66215" "Ad astra per aspera" "$895.00"


Logical Expressions

A logical expression makes a statement comparing two or more things. A logical expression consists of two expressions joined by a relational operator. The two expressions are compared according to the rules of the operator involved (see Relational Operators).

This kind of statement is evaluated as either true or false---that is, the comparison of the two expressions designated by the relational operator is either correct or incorrect. When a logical expression is calculated in a formula, it returns a non-zero (usually 1) numeric value if it is true. If it is false, it takes the numeric value zero. The following examples show simple logical expressions and their truth values.

10 > 9.9 | TRUE
"Z" <> "z" | TRUE
10 * 10 = 100 | TRUE
(1 >= 2) = 1 | FALSE

Logical expressions can be joined with logical operators. The resulting compound logical expression is also either true or false, depending on the truth values of its parts and the rules of the operator used (see Logical Operators).

10 > 9.9 AND 9.9 > 9.8 | TRUE
"Z" <> "z" OR "Z" = "z" | TRUE
(1 >= 2) = 1 AND (2 > 1) | FALSE
(2 < 1 OR "5" = 5) AND 1 + 1 = 2 | FALSE


Date Expressions

A date expression is a form in which you must specify a date so that it can be interpreted and calculated in a date formula. SmartWare allows you the freedom to enter dates in virtually any form you prefer. These date expression forms are categorized into three types.
Comment: A number used as a date is interpreted to mean the number of days before or after December 31, 1899.

Type 1. Type 1 is a text expression in any form recognizable as a date. You can punctuate and abbreviate month and day names however you wish. If you specify a series of three numbers as a date, the Date style setting in the Global Preferences menu determines the order of day, month, and year. If you use only two-digits for the year, the twentieth century is assumed; to work with dates in other centuries, you must specify all four digits for the year.

Examples |  |
"September 15, 1989" | "Sep 15 89" | "Sept. 15th, 1989"
"07 06 52" | "07/06/52" | "7--6--1952"

Type 2. Type 2 is a single numeric expression representing a quantity of days before or after the base date, Dec 31, 1899. Positive numbers refer to dates after the base date; negative numbers refer to dates before. The following examples compare dates expressed as types 1 and 2.

Comment: SmartWare allows you to use dates ranging from Jan. 1, 100 to Dec. 31, 9999 in formulas.
Type 2 | Type 1
32765 | "September 15, 1989"
--3759 | "September 15, 1889"
55705 | "July 6, 2052"
0 | "December 31, 1899"

Type 3. Type 3 is a set of three numeric expressions separated by commas in the form: yyyy, mm, dd. If you use only two digits for the year, the twentieth century is assumed; to work with dates in other centuries, you must specify all four digits for the year. The following examples compare dates expressed as types 1 and 3.

Type 3 | Type 1
89, 9, 15 | "September 15, 1989"
2089, 9, 15 | "September 15, 2089"
0, 12, 31 | "December 31, 1900"


Time Expressions

A time expression is a form in which you must specify a time of day so that it can be used in a formula involving time calculations. A time expression is a text expression consisting of three two-digit numbers separated by colons in the form HH:MM:SS. The digits representing seconds are optional. If you want to express time according to a 24-hour clock, the hours digits can range from 00 to 24. If you prefer to work with a 12-hour clock, you can restrict the hours digits to the range 00 to 12 and include the letters "A" or "P" as the last characters in the expression to indicate AM or PM, respectively.

Examples |  |  |
"06:00:21" | "06:00:21A" | "4:30P" | "16:30"


Functions

A function is a special keyword that instructs the formula calculation system to perform a particular operation on data. You may think of functions as "prefabricated" formulas that perform useful activities with data. Functions can enhance your fluency in SmartWare's formula language.

Pi, for example, is a value frequently used in geometrical calculations. It represents the ratio of the circumference of a circle to its diameter and is roughly equivalent to 3.14159265359. In SmartWare formulas, you can use the function PI to replace this long string of numbers when you want to use pi in a formula (e.g., PI * radius ^ 2).

SmartWare offers over 200 built-in formula functions. In addition, you can create your own functions through Project Processing. You can use your functions much like SmartWare's built-in functions. First you must create a project file that names and defines your function. Then, whenever you want to perform a calculation that requires your function, you can load the project file that defines it (see Project Processing).


Function Formats

To use a function in a formula you must follow its required "format" or syntax. Formula Reference provides a complete reference for the specific formats required by the SmartWare functions. You may type a function name in either upper or lower case letters. Many functions require arguments. Arguments are independent data that determine the value functions return when calculated.

Suppose you want to determine the average of several numbers. First you must add all these numbers. Then you must count how many numbers you have added and divide the sum by that count. The formula might look like this:

     (57 + 62 + 8 + 21 + 10 + 13) / 6

A more efficient way to perform this calculation is to use SmartWare's AVERAGE function. Your formula now looks like this:

     AVERAGE(57,62,8,21,10,13)

The six numbers in parentheses are the AVERAGE function's argument. Unlike PI, a function that always returns the same value, AVERAGE assumes different values depending on its argument. AVERAGE performs three operations on its argument. First, it counts the items and then it sums them. Finally, it divides the sum by the count.

If a function is to operate properly it must have the correct number of arguments in the proper order and of the appropriate type. An argument is usually placed in parentheses following the function name. If a function requires multiple arguments they are usually separated by commas (see the note regarding comma decimal separators following Item Lists).


Expressions and Arguments

Function formats vary according to the data and the operations involved. Most functions accept one or more of the expression types as arguments. These expression types are represented in the function reference in Formula Reference by the following abbreviations.

Abbreviation | Meaning
numeric | Numeric expression
text | Text expression
logical | Logical expression
date | Date expression
time | Time expression
expression | More than one type of expression

Optional Arguments. Some functions have optional arguments. In the function reference these arguments are placed within angle brackets (e.g., <text> ). If an argument is optional, it is not required for the function to work properly, although it may alter the results returned by the function if it is supplied.

Item Lists. Some functions can take a set of one or more expressions as a single argument. This type of argument is called an item list and is represented in the function reference like this: item list. The number of expressions or items in an item list can vary according to the data involved. Items are separated by commas.

The argument to the AVERAGE function in the previous example is an item list consisting of six numeric expressions. However, AVERAGE can calculate the average of varying quantities of items, not just sets of six. Functions, like AVERAGE, that use item lists automatically adjust to the number of items in their argument.
NOTE: In the Spreadsheet, when an item list includes a block of cells, blank cells within that block are ignored. However, if the item list includes an item that is a reference to a single cell and that cell is blank, it is interpreted as having a value of zero.
NOTE: If you use a comma as a decimal separator, you must use the combination of characters, space-comma-space, to separate multiple items or arguments. For example, in AVERAGE(87, 3) the system would recognize only one item, treating 87,3 as eighty-seven and three tenths. To enter the first item as 87, followed by 3 as a second item, you must enter the formula like this: AVERAGE(87  ,  3) .


Data References

Data references are terms that indicate the locations or addresses of specific data items. Data references in formulas allow you to perform calculations using information that you have entered and stored in a SmartWare module's data files. When you include a data reference in a formula, it points to the "object" containing the data that you want used in the calculation. Using data references effectively is the key to utilizing formulas in your SmartWare applications.

Suppose that you have already entered the numbers you want averaged in some cells in a worksheet. The numbers are located in columns 10 through 15 of row 5. Instead of retyping these numbers in an item list argument to the AVERAGE function, you can refer to them with a data reference. Your formula would look like this:

     AVERAGE(r5c10:15)

The data reference r5c10:15 replaces the list of specific numbers in the argument. The formula now instructs SmartWare to calculate the average of the values that it finds in the referenced cells. The data reference connects the formula to that particular set of cells. Thus, the formula no longer includes specific values (constants), which can yield only one result. Instead, it depends on the data stored in cells.

In a typical Spreadsheet "what if" application, the numbers involved in a calculation change often. Initially, you might place estimated values into the referenced cells. Then, as real data becomes available, you might enter new figures and recalculate to obtain a more precise or current result. The formula itself remains the same. You simply update the data stored in the referenced cells and recalculate. The referenced cells might actually contain other formulas depending on yet another set of data. By using data references to build relationships between your data you can create powerful applications.


 Cell Reference. A reference to a single worksheet cell is a cell reference. A cell reference consists of the row and column coordinates of the cell in the form rxcy, where x is the row number and y is the column number. For example, r3c20 refers to the cell at row 3 column 20. An alternative way to reference a cell is to assign it a name with the Sheet Name commands.

You can refer to cells in active worksheets other than the current worksheet. Called an external worksheet reference, this kind of cell reference consists of the name of the other worksheet, followed by a period, followed by the cell reference or name. For example wrksht2.r50c1 refers to the cell at row 50 column 1 in the worksheet named "wrksht2."

When using cell references in formulas, make sure that the cells contain data of the appropriate expression type for your formula. Worksheet cells can contain text, numeric, date, and time data. Remember that date and time cells really contain numeric data but display it in date or time format. Date cells, for example, contain a number that represents a quantity of days before or after December 31, 1899. Cells can also contain formulas returning all these types of data.


 Field Reference. A reference to a single view field is a field reference. A field reference consists of the number or title of a field surrounded by brackets (e.g., [Last name]).

You can refer to cells in active views other than the current view. Called an external view reference, this kind of field reference consists of the name of the view, followed by a period, followed by the field reference (e.g., [mailst.Last name]).

When using field references in formulas, make sure that the fields contain data of the appropriate expression type for your formula. SmartWare Database allows you to create alphanumeric (text), inverted alphanumeric (text), numeric, date, and time fields. Remember that date and time fields really contain numeric data but display it in a date or time display format. Time fields, for example, contain a decimal fraction representing a time of day as a fraction of the whole day (0.5 is displayed as "12:00:00P").


 Block Reference. A block reference is a reference to one or more view fields or contiguous worksheet cells. The reference to row 5, columns 10 through 15 in the AVERAGE example formula discussed previously is a worksheet block reference. It identifies six neighboring cells in a worksheet.

A worksheet block reference is similar to a cell reference, except that it includes the first and last row and/or column numbers separated by colons. For example, r2:4c1:9 indicates the cells in rows 2 through 4 of columns 1 through 9. You can use names to reference blocks of cells, as well as single cells. External worksheet references to blocks are also possible.

Some Spreadsheet functions require blocks as arguments, even though the calculation involves only a single cell, the upper left or "home" cell of the block. For these functions, SmartWare interprets a single cell reference as a block reference if you precede the reference with an exclamation point (e.g., !r5c10).

A Database block reference, called a field list, is similar to a field reference, except that it includes multiple field titles or numbers separated by semicolons. Field numbers indicate the input order sequence for the current view. For example, [Name; Address; City; State] refers to the fields titled Name, Address, City, and State and [1;3;5] denotes fields occurring first, third, and fifth in input order in the current view. You can use both titles and numbers in the same field list. External block references are also possible.

To indicate a sequence of consecutively numbered fields, you can use references to the first and last fields separated by a vertical bar. For example, [Name|Zip] identifies the fields Name and Zip and all fields ranging between them in input order.


 Variable. A variable is a keyword that identifies a memory location you can use for temporary data storage. A variable can have virtually any name (up to 31 characters long) that uniquely identifies it. A variable can store either text or numeric data.
Comment: In SmartWare's Project Development Language you must declare a variable before you can use it.

Variables are an important part of SmartWare's Project Development Language (see Project Processing Manual) and have a variety of uses in application development. However, you can also create and use them in calculations while working interactively with the SmartWare modules.

To "assign" or store data in a variable, you must calculate a formula using the LET function. You can use variables created in this way, as well as variables created through Project Processing, as terms in formulas, much like any other data reference. Variables created through LET formulas remain available in memory until the module is exited. You can give a variable a constant value (e.g., LET #rate = 0.25) or allow its value to be determined by the result of formulas (e.g., LET #commission = #sales * .25).
NOTE: SmartWare provides a special type of notation for referencing specific characters stored in a text variable. An expression in the form V[N] denotes the Nth character in the variable V. This type of notation yields a numeric value, the SmartWare Character Set (SCS) value of the specified character. For example, if the variable $name contains "Washington", then $name[2] returns 97, the SCS value of the second character, "a". You can use the function CHR to obtain the text character from its SCS value.


 Array. An array is a list or table of data identified by the name of a variable. Arrays are like variables that contain multiple items of data. Each data item in an array is called an element and is identified by one or a combination of numbers, called a subscript. An array element can be used as an expression in formulas. However, an array can only be created by executing a project that defines it. Refer to Project Processing for information on defining and using arrays.

A reference to an array element is an expression in the form A[S], where A is the array's name and S is the subscript. The quantity of dimensions in the array determines the quantity of numbers in the subscript. Multiple numbers are separated by commas. For example, #distance[2,3] refers to the element located in the second position in the first dimension and the third position in the second dimension of the array #distance.

The notation mentioned in the previous note for referencing characters within text can also be used with array elements containing text. For example, $address[2,1][2] refers to the second character in the text expression located in the second position in the first dimension and the first position in the second dimension of the array $address.


Function Reference

This section contains an alphabetical listing of SmartWare functions. Each function is accompanied by a description and an explanation of its syntax or format. For many functions, examples are provided to show usage in a formula and what result that formula generates.

The scope of a function indicates the modules in which the function is available. Most functions are available in all the SmartWare modules. A few functions are useful in only one of the modules. Returns designates the type of data (e.g., text, numeric) that results when the function is calculated. Some functions return different types of data depending on their arguments; these functions are identified as returning "Conditional."

Some functions have optional arguments. In the function reference these arguments are placed within angle brackets (e.g., <text> ).

Unlike Lotus 1-2-3, SmartWare allows but does not require an "@" prefix with many function names. Numerous SmartWare functions have names matching (except for the @ sign) their equivalent 1-2-3 functions. For like-named functions that differ in result between SmartWare and 1-2-3, the @ preceding the name distinguishes the two functions. Refer to Appendix C of Formula Reference Manual for a comparison of SmartWare and Lotus 1-2-3 functions.

Some functions, such as a number of the SmartWare Spreadsheet Statistical Database functions, require the @ sign.

Before the alphabetical list of functions, there is also a section about the special Statistical Database (SDb) functions for use in the Spreadsheet and Database programs.


Statistical Database Functions

Statistical Database (SDb) functions for the Spreadsheet (designed for use with worksheet data organized in "database" format) and for the Database are included in this chapter. Application examples and additional information on using these functions are provided in Formula Reference Manual.


Spreadsheet SDb Functions

The Spreadsheet SDb functions complement other statistical functions, such as AVERAGE and VAR, but are designed for use with worksheet data organized in a database format.


Spreadsheet SDb Arguments

All Spreadsheet SDb functions employ arguments in the same way, as follows:

     @DAVERAGE( Database block, column offset, criteria block )

Database Block. The database block argument identifies the area of the worksheet containing the source data, i.e., the "data base."

Column Offset. The column offset argument specifies the column within the database block upon which the statistical calculation is to be performed.

Criteria Block. The criteria block argument identifies an area of the worksheet containing criteria for selecting the records to be included in the statistical calculation. The first row of the criteria block must contain the exact headings of the database columns to be selected. Remaining rows contain specific selection requirements. If two criteria are in the same row, a record must meet both criteria to be selected. If the criteria are in separate rows, a record may fit either one to be selected. Blank cells in the criteria block are treated as if they match all entries. Thus, a criteria block containing headings but no selection criteria returns information from all records.

The following wild card characters can be used to match multiple items in the same criteria.
*** ? matches any single character.
** * matches all remaining characters from the point the asterisk is inserted.
** ~~ (tilde) at the beginning of the criterion instructs SmartWare to accept any record entry except the one preceded by the tilde character.

If the criterion is a formula, it must be written as a test of the first record in the database. If the formula returns TRUE, the record is selected. If the formula returns FALSE, the record is not included. SmartWare sequentially replaces the cell reference in the formula with the appropriate cell reference from each record.

If the criterion is a number, the number in the corresponding database block record must match exactly to be selected.

For illustrations and additional information, refer to the Formula Reference Manual.


Database File SDb Functions

The Database File SDb functions complement other statistical functions, such as AVERAGE and VAR, but are designed for performing calculations on a specific field for every (logical) record in a data-file. The function FILEAVERAGE, for example, returns the average value in a field from among all the records in a data-file. All File SDb functions use arguments in the same way, as follows:

     FILEAVERAGE( return field <, optional selection criterion>)

The return field identifies the field containing the data to be used in the calculation. The optional selection criterion is a logical expression specifying conditions under which a record should be included in the calculation. If no selection expression is included, the result is returned from all records.
NOTE: When calculating a formula containing a File SDb function, SmartWare accesses every record in a file. The following paragraphs describe some restrictions that apply to the use of these functions.

File SDb functions cannot be calculated when you are entering or updating a record. If you are using these functions with very large files, the calculation may take a significant amount of time. File SDb functions, as well as FILELOOKUP, cannot be "nested" (made directly dependent on results returned from other File SDb functions) in formulas.

If the return field is within a table, the File SDb functions process all table records associated with all view records in the file, not just the table records in the current view record. In contrast, Table SDb functions operate only on the table records in the current view record.

You can use FILECOUNT, FILEMAX, and FILEMIN to perform calculations on text type fields (i.e., alpha, inverted). FILECOUNT counts text as well as numeric data. FILEMAX and FILEMIN compare text items according to the SmartWare Character Set values of their characters.


Database Table SDb Functions

The Database Table SDb functions are designed for performing calculations on data displayed in tables (repeating areas) in Database custom views. The function TABLEAVERAGE, for example, returns the average value in a field from among the records displayed in a table in a single view record. All Table SDb functions use arguments in the same way, as follows:

     TABLEAVERAGE( return field <, optional selection criterion>)

The return field identifies the field containing the data to be used in the calculation. The field must be within a table in the view in which it is referenced. The optional selection criterion is a logical expression specifying conditions under which a table record should be included in the calculation. If no selection expression is included, the result is returned from all table records.
NOTE: When creating views, do not include a field in a table if it is a calculated field using a Table SDb function in its formula. Under such circumstances, the calculation will fail. It is also important to know that Table SDb functions and TABLELOOKUP cannot be nested.

You can use TABLECOUNT, TABLEMAX, and TABLEMIN to perform calculations on text type fields (i.e., alpha, inverted). TABLECOUNT counts text as well as numeric data. TABLEMAX and TABLEMIN compare text items according to the SmartWare Character Set values of their characters.

Refer to Figure 3-4 in Formula Reference Manual for an example of a common application for tables and Table SDb functions.


Alphabetical Listing of Functions

The following section is an alphabetical listing, with input and usage information, of the functions available in SmartWare.


ABS

Format: ABS( numeric )
Scope: All
Returns: Numeric

ABS calculates the absolute value of the numeric expression.

ABS(11) | 11.0
ABS(--3.3) | 3.3


ACOS

Format: ACOS( numeric )
Scope: All
Returns: Numeric

ACOS calculates the arccosine of the numeric expression. The numeric expression must have a value between --1 and 1, inclusively. The result is a value expressed in radians between 0 and pi.

ACOS(.11) 1.460573


ACTXERROR

Format: ACTXERROR
Scope: All
Returns: Numeric

ACTXERROR returns the numeric code of the last ActiveX error that occurred, or 0 if no error has occurred during the current session. Some numbers are general ActiveX errors and some are specific to the individual ActiveX object. Consult the ActiveX object's help file for error descriptons. The Clearerror project command resets ACTXERROR to 0. Use ACTXERRORTEXT for a textual description of the error.

You are alerted that there is an ACTXERROR when LERROR returns 465.

Example:
     if LERROR = 465
        message str(ACTXERROR)
        message ACTXERRORTEXT
     end if

ACTXERRORTEXT
LERROR


ACTXERRORTEXT

Format: ACTXERRORTEXT
Scope: All
Returns: Numeric

ACTXERRORTEXT returns a textual description of the last ActiveX error that occurred, or blank if no error has occurred during the current session. The Clearerror project command resets ACTXERRORTEXT to a blank string. Use ACTXERROR for a numerical identifier of the error.

You are alerted that there is an ACTXERRORTEXT when LERROR returns 465.

Example:
     if LERROR = 465
        message str(ACTXERROR)
        message ACTXERRORTEXT
     end if

ACTXERROR
LERROR


ADATE

Format: ADATE( date )
Scope: All
Returns: Text formatted as a date

ADATE converts the date expression into a text expression of the form "month dd, yyyy." If the year is represented by two digits, the twentieth century is assumed.

ADATE("07-06-88") | July 6, 1988
ADATE("09/15/3888") | September 15, 3888

Date Expressions


ADDDAYS

Format: ADDDAYS( date, numeric )
Scope: All
Returns: Text formatted as a date

ADDDAYS returns a date representing the date expression plus the number of days in the numeric expression. If the numeric expression is negative, the result is that number of days subtracted from the date expression.

The first argument must be a date expression type 1 or 2. Type 1 is a text expression representing a date. Type 2 is a numeric expression representing a number of days before or after the beginning of the current century.

Date Expressions

ADDDAYS("07-06-52",14) | 07-20-52
ADDDAYS("Sept 15, 1984",--28) | 18 Aug 84

The date returned will be in the setting defined for the Date1 format in Tools Preferences Global.


ADDHOURS

Format: ADDHOURS( date or time, numeric )
Scope: All
Returns: Text formatted as a date or time

ADDHOURS adds the number of hours represented by the numeric expression to the time or date indicated by the time or date expression. If the numeric expression is negative, the result is that number of hours subtracted from the date or time.

The first argument for ADDHOURS may be either a date or a time expression. When a date expression is used, ADDHOURS returns a date; the argument must be a date expression type 1 (text) or type 2 (numeric). When a time expression is used as the first argument, a time expression is returned.

ADDHOURS("12/24/84",36) | 12/25/84
ADDHOURS("06:13:21P",4) | 10:13:21P


ADDMINUTES

Format: ADDMINUTES( date or time, numeric )
Scope: All
Returns: Text formatted as a date or time

ADDMINUTES adds the number of minutes represented by the numeric expression to the time or date indicated by the time or date expression. If the numeric expression is negative, the result is that number of minutes subtracted from the date or time.

The first argument for ADDMINUTES may be either a date expression or a time expression. When a date expression is used, ADDMINUTES returns a date; the argument must be a date expression type 1 (text) or type 2 (numeric). When a time expression is used as the first argument, a time expression is returned.

ADDMINUTES("16:13:21",41) | 16:54:21
ADDMINUTES("Sept 15, 84",21220) | 29 Sep 84


ADDMONTHS

Format: ADDMONTHS( date, numeric )
Scope: All
Returns: Text formatted as a date

ADDMONTHS returns a date representing the date expression plus the number of months in the numeric expression. If the numeric expression is negative, the result will be that number of months subtracted from the date expression. The argument must be a date expression type 1 (text) or type 2 (numeric).

ADDMONTHS("12-24-84",16) | 04-24-86
ADDMONTHS("08/24/57",--7) | 01-24-57

Date Expressions


ADDSECONDS

Format: ADDSECONDS( date or time, numeric )
Scope: All
Returns: Text formatted as a date or time

ADDSECONDS adds the number of seconds represented by the numeric expression to the time or date indicated by the time or date expression. If the numeric expression is negative, the result will be that number of seconds subtracted from the date or time.

The first argument for ADDSECONDS may be either a date expression or a time expression. When a date expression is used, ADDSECONDS returns a date; the argument must be a date expression type 1 (text) or type 2 (numeric). When a time expression is used, a time expression is returned.

ADDSECONDS("09/15/84",100350) | 09/16/84
ADDSECONDS("06:13:59A",221) | 06:17:40A


ADDYEARS

Format: ADDYEARS( date, numeric )
Scope: All
Returns: Text formatted as a date

ADDYEARS returns a date representing the date expression plus the number of years in the numeric expression. If the numeric expression is negative, the result will be that number of years subtracted from the date expression. The argument must be a date expression type 1 (text) or type 2 (numeric).

Date Expressions

ADDYEARS("July 6, 1952",36) | 06 Jul 88
ADDYEARS("06/02/88", --74) | 06/02/14


APINFO

Format: APINFO(numeric)
Scope: All
Returns: Conditional

APINFO returns a variety of information about the current application, based upon the named constant specified in the argument. Valid argument entries and their return values are as follows:

Name | Returns
ap_zoom | 1 (TRUE) if the current window is zoomed; 0 (FALSE) if the current window is not zoomed
ap_border | 1 (TRUE) if the current window has a border; 0 (FALSE) if the current window has no border
ap_window | The current window number
ap_file | The name of the file displayed in the current window; no extension or path is included
ap_filex | The name, including extension, of the file in the current window; path is not included
ap_filep | The name, including path and extension, of the file in the current window
ap_paper | The name of the currently selected paper profile

In the following examples, APINFO first returned the name of the currently displayed file with no extension. In the second example, APINFO returned the file name and extension.

APINFO(AP_FILE) | cust
APINFO(AP_FILEP) | cust.vw


ARRAYFIND

Format: ARRAYFIND( pointer, num/txt, numeric <,numeric> <,numeric> <,numeric> )
Scope: All
Returns: Conditional

ARRAYFIND searches the elements of an array for specific data. The search may be binary or sequential. If a match is found, an array index position is returned otherwise, zero is returned.

ARRAYFIND( AR_ptr, data, type, dim, index1, index2 )

The parameters in the above example are:

AR_ptr - Pointer to the searched array. Refer to the function ARRAYPTR.

data - Numeric or string value to search for.

type - Search type. To use a binary search, pass 0. To use a sequential search, pass the element starting position.

dim - The dimension to be searched. Used only when the array has more than one dimension. An index position along this dimension is returned when a match is found.

index1 - Index position of the dimension not being searched (i.e., a dimension other than dim). Used only when the array has more than one dimension. Its maximum value is the number of elements along this dimension. For example, in array[10,20] where the search dimension is 1, index1 cannot be greater than 20.

index2 - Index position of the second dimension not being searched. Used only when the array has three dimension. Note that the dimension referred to by index2 is greater than that of index1. For instance, if dim equals 2, then index1 refers to the first dimension and index2 refers to the third.


ARRAYPTR

Format: ARRAYPTR( array )
Scope: All
Returns: Address

This function returns the address of an array. The passed argument must be a declared array however, the element(s) chosen is irrelevant. The following example gets the address of a two-dimensional array:

AP_ptr = ARRAYPTR( #array[1,1] )


ARRAYRESIZE

Format: ARRAYRESIZE( pointer, numeric <,numeric> <,numeric> )
Scope: All
Returns: Nothing

This redimensions an array. Unlike REDIMENSION, if the array size is enlarged, data already in the array will not be destroyed. The first parameter is a pointer to an array (refer to the function ARRAYPTR). The second parameter specifies the size of the first dimension. If required, the third and fourth parameters specify the size of the second and third parameters respectively.

NOTE: the number of dimensions cannot not be changed.


ARRAYSIZE

Format: ARRAYSIZE( pointer, numeric )
Scope: All
Returns: Numeric

This returns the size of an array. The first parameter is a pointer to an array (refer to the function ARRAYPTR). The second parameter specifies the dimension.


ARRAYSORT

Format: ARRAYSORT( pointer, numeric <,numeric> <,numeric> <,numeric> )
Scope: All
Returns: Nothing

This function sorts the contents of an array.

ARRAYSORT( AR_ptr, dir, dim, index1, index2 )

The parameters in the above example are:

AR_ptr - Pointer to the sorted array. Refer to the function ARRAYPTR.

dir - The direction of the sort where 1 equals ascending and -1 equals descending.

dim - The dimension to be sorted. Used only when the array has more than one dimension.

index1 - Index position of the dimension not being sorted (i.e., on a dimension other than dim). Used only when the array has more than one dimension. Its maximum value is the number of elements along this dimension. For example, in array[10,20] where the sort dimension is 1, index1 cannot be greater than 20.

index2 - Index position of the second dimension not being sorted. Used only when the array has three dimension. The dimension referred to by index2 is greater than that of index1. For instance, if dim equals 2, then index1 refers to first dimension and index2 refers to the third.


ASC

Format: ASC( text )
Scope: All
Returns: Numeric

ASC returns the SmartWare Character Set value of the first character in the text expression. Refer to Appendix B in Software System Manual for a table of SmartWare Character Set values.

The second example assumes that the variable $var contains the text "[".

ASC("A") | 65
ASC($var) | 91


ASIN

Format: ASIN( numeric )
Scope: All
Returns: Numeric

ASIN calculates the arcsine of the numeric expression. The numeric expression must have a value between --1 and 1, inclusive. The result is a value expressed in radians between --pi/2 and pi/2.

ASIN(.17) 0.1708296


ASK

Format: ASK( text )
Scope: All
Returns: Text

ASK causes the text expression to appear as a prompt on the screen just beneath the window. The program pauses for input from the keyboard. The data entered becomes the text string result returned by ASK.

ASK("Enter greeting:") | "Hello World!"
ASK("Enter Value:") | "2"
VAL(ASK("Enter value:")) * 2 | 4

When the first formula is calculated, the prompt Enter greeting: is displayed. You enter Hello World! and this is the result returned.

When the second formula is calculated, the prompt Enter value: appears below the window. You enter 2, and the text expression "2" is returned.

When the third formula is calculated, you are prompted to enter the value. Because the VAL function converts text to a numeric value, the 2 entered in response to the prompt is multiplied by 2 to obtain the result, 4.


ATAN

Format: ATAN( numeric )
Scope: All
Returns: Numeric

ATAN calculates the arctangent of the numeric expression. The result is a value expressed in radians in the range --pi/2 to pi/2.

ATAN(3.23) 1.270558


ATAN2

Format: ATAN2( numeric , numeric )
Scope: All
Returns: Numeric

ATAN2 returns an angle whose value is the arctangent of the second argument (the sine, or y component of the angle) divided by the first argument (the cosine, or x component of the angle). The value returned is in radians between -pi and pi and correctly reflects the quadrant in which the angle lies.

ATAN2(2,2) | 0.785398
ATAN2(15,3) | 0.197396


ATIME

Format: ATIME( numeric )
Scope: All
Returns: Text formatted as a time

ATIME returns a time in AM/PM format by evaluating the numeric expression as a number of minutes elapsed since the beginning of the day (12:00:00A).

ATIME(121) | 02:01:00A
ATIME(1022) | 05:02:00P


ATIME24

Format: ATIME24( numeric )
Scope: All
Returns: Text formatted as a time

ATIME24 returns a time in 24-hour format by evaluating the numeric expression as a number of minutes elapsed since the beginning of the day (00:00:00).

ATIME24(13.5*60) | 13:30:00
ATIME24(1022) | 17:02:00


AVERAGE

Format: AVERAGE( item list )
Scope: All
Returns: Numeric

AVERAGE calculates the average of the numeric items in the item list, including numeric items with a value of 0. AVERAGE does not include text, null or blank items. AVERAGE is equivalent to:

     SUM( item list ) / COUNT( item list ).

AVERAGE(4.5,6.0,27.3,0) | 9.45
AVERAGE(4.5,6.0,27.3,"0") | 12.6


AVG

Format: AVG( item list )
Scope: All
Returns: Numeric

AVG calculates the average of the items in the item list. AVG does not include null or blank items but does include text items, attributing a value of 0 to them. AVG is equivalent to:

     SUM( item list ) / @COUNT( item list ).

AVG(4.5,6.0,27.3,0) | 9.45
AVG(4.5,6.0,27.3,"0") | 9.45


BGBACKGROUND BGDIMPLEASING BGEDITING BGERROR BGHIPLEASING

BGINVPLEASING BGINVSTANDARD BGPLEASING BGSTANDARD

Format: BGBACKGROUND
Scope: All
Returns: Numeric

These functions return the color numbers of standard background colors used in SmartWare screen displays. The values returned by these functions vary according to the screen driver currently in use. Using these functions for the color entries in SCREEN command statements guarantees acceptable foreground/background contrast regardless of the screen driver or display type that you are using. This practice also allows you to display text in colors consistent with various elements of SmartWare's display.

The following table shows the SmartWare display element whose background color is represented by each function.

Function | Use in SmartWare Display
BGBACKGROUND | Background of labels on the status line
BGDIMPLEASING | Background of unavailable items on the paper profile menu
BGEDITING | Background of SmartWare editors and the highlighted portion of the Status Line
BGERROR | Background of an error message
BGHIPLEASING | Background of valid items on the paper profile menu
BGINVPLEASING | Background of selected items in definition menus
BGINVSTANDARD | Background of the highlighted item in a SmartWare module menu
BGPLEASING | Background of definition menus
BGSTANDARD | Background of a SmartWare module menu

FGBACKGROUND


BITAND BITOR BITXOR

Format: BITAND( numeric, numeric )
Scope: All
Returns: Numeric

These functions return a number that is the result of a binary operation on the respective bits of the two arguments, evaluated as 32-bit integers. Any fractional part of an argument is discarded.

The following table explains the result of the operation performed on the corresponding bits of the arguments. Examples below are shown in hexadecimal representation for clarity.

Function | Operation
BITAND | Result bit is 1 only if both bits are 1. Using BITAND to compare any bit with 0 produces 0; comparing any bit with 1 retains the value of the bit.
BITOR | Result bit is 1 if either bit is 1. Using BITOR to compare any bit with 0 retains the value of the bit; comparing any bit with 1 produces 1.
BITXOR | Result bit is 1 if either of the bits is 1, but not both. Using BITXOR to compare any bit with 0 retains the value of the bit. Comparing any bit with 1 complements (swaps) the original bit.

HEX(BITAND(0x00FF, 0x1234)) | 0x34
HEX(BITAND(0xFF00, 0x1234)) | 0x1200
HEX(BITOR(0x00FF, 0x1234)) | 0x12FF
HEX(BITOR(0xFF00, 0x1234)) | 0xFF34
HEX(BITXOR(0x00FF, 0x1234)) | 0x12CB
HEX(BITXOR(0xFF00, 0x1234)) | 0xED34


BLANK

Format: BLANK
Scope: All
Returns: Blank

BLANK returns the blank status. When a formula returning BLANK is stored in a cell, field, or variable, any data in that object is discarded and it assumes a blank status.
NOTE: You must use the Edit Blank command in the Spreadsheet to blank a cell. You can assign BLANK status to a variable, but the original status of variables is zero (0), not blank.


BMPINFO

Format: BMPINFO( constant, bmp_var )
Scope: All
Returns: Numeric

This function returns information about a bitmap. Note that the bitmap variable bmp_var is created by GRAPHICS BITMAP SAVE or READ.

0 bmp_height in pixels
1 bmp_width


CALL

Format: CALL( text <,txt/num> <,txt/num> <,...> )
Scope: All
Returns: Conditional

CALL executes an SPL public function. This function's name is specified in the first parameter. The remaining parameters are actually the parameters passed to the public function - note that these must match the number of parameters expected by that function. Failure to do so will cause a run-time error.

     CALL( "FunctionName", "parameter1", ... )

As an alternative, INDIRECT can be used to execute SPL public functions. Additionally, INDIRECT executes SmartWare functions - CALL does not. CALL's advantages, however, are: the "function call" is not built as a string and, pointers can be used in its parameters. Compare the follow lines of code:

     INDIRECT( "Msg(" & CHR(34)|"Hello World"|CHR(34) & ")" )

     CALL( "Msg", "Hello World" )

If CALL fails, 0 is returned (e.g., an invalid number of parameters was passed). Otherwise, output from the public function is returned.

Example:

This simple example requires two programs. The first program, containing the public function, is loaded in memory. The second program, when executed, calls the public function and passes it a string and a number. Msg() then prints both values on the screen and returns "OK".

     '****** LOADED PROGRAM ******

     PUBLIC Msg()

     FUNCTION Msg( $string, #number )
          MESSAGE $string & STR(#number)
          RETURN "OK"
     END FUNCTION

     '****** CALLING PROGRAM *****

     MAIN
     LOCAL $return
          $return = CALL( "Msg", "Hello World", 1234 )
          MESSAGE "Msg return:" & $return
     END MAIN


CALLBACK_CREATE

Format: CALLBACK_CREATE( string, numeric, numeric )
Scope: All - Windows (Win32S), Windows95, NT
Returns: Numeric

DLL callbacks are set up in SPL programs with the CALLBACK_CREATE function before calling a DLL function. This creates a stub and "announces" that a named public function can be accessed by the DLL.

Note that callback functions must have one and only one parameter. This parameter is a buffer variable which is UNPACKed and read within the callback. In this way, multiple parameters are passed to the callback.

NOTE: The named callback function must be an existing public function.

The second parameter is the number of items placed on the stack. In the example used in DLL Callback Functions, there is only one item, message, placed on the stack.

The third parameter is the number of items popped off the stack by the callback. In some cases, it is up to the DLL function to pop items, in others, it's the callback's job.

CALLBACK_CREATE returns zero if unsuccessful or a handle which is later used by the CALLBACK_DELETE function.

DLL
DLL Callback Functions
CALLBACK_DELETE


CALLBACK_DELETE

Format: CALLBACK_DELETE( handle )
Scope: All - Windows (Win32S), Windows95, NT
Returns: Numeric

Callbacks created with CALLBACK_CREATE are removed with the CALLBACK_DELETE function.

The handle parameter indicates the callback to remove. This value is returned by CALLBACK_CREATE.

NOTE: Unpredictable results may occur if CALLBACK_DELETE is issued for a function that is not a callback or has already been removed.

DLL
DLL Callback Functions
CALLBACK_CREATE


CASE

Format: CASE expression case list < ELSE expression >
Scope: All
Returns: Conditional

CASE creates a special type of logical formula which provides for a set of possible responses to a list of specified conditions.

CASE examines the first expression and compares it with the case list. The case list consists of pairs of expressions separated by a comma and enclosed in parentheses. Each pair contains an item to be compared with the first expression and an item to be returned if the comparison results in a match. You may include an ELSE statement in the formula to provide a response when no match is found. If none of the items in the case list is found to be equivalent to the first expression and no ELSE statement is included, the formula returns an Error 14.

This example assumes that the variable #FORM equals 1.

Formula | Result
CASE #FORM (1,"a")(2,"b")(3,"c")(4,"d") ELSE "No match" | "a"

A CASE formula is a specialized IF-THEN-ELSE statement. The following example shows how the CASE formula would look if written as an IF-THEN-ELSE formula:

     IF #FORM = 1 THEN "a"
          ELSE IF #FORM = 2 THEN "b"
          ELSE IF #FORM = 3 THEN "c"
          ELSE IF #FORM = 4 THEN "d"
          ELSE "No match"

NOTE: If the first expression contains a function or is composed of multiple expressions, enclose it within parentheses to avoid ambiguity.


CELL

Format: CELL( text , block )
Scope: Spreadsheet
Returns: Conditional

CELL returns a text or numeric item that provides specific information about the "home" cell referenced in the block argument. Although CELL returns information about a single cell, the second argument specified must be in the form of a block reference. The information returned pertains to the cell in the upper left corner (home) of the block.
NOTE: You may reference a single cell by using the format !r1c1. The ! preceding the cell reference tells SmartWare to treat the single cell reference as a block reference.

The first argument determines the kind of information requested. The following table describes the results possible for each type of data. If the result is not dependent upon the data in the cell, the right column is blank.

First Argument | Result Returned | Cell Contains
address | Absolute reference of the specified cell |
col | Column number of the cell |
contents | Value in the cell |
format | F0 to F15 | 0 to 15 decimal places in fixed decimal format
format | P0 to P15 | 0 to 15 decimal places in percent format
format | C0 to C15 | 0 to 15 decimal places in currency format
format | S0 to S15 | 0 to 15 decimal places in scientific format
format | (space character) | General format
format | D1 to D3 | Date formats 1 through 3
format | T1 or T2 | Time formats 12 or 24 hour
prefix | ' | Left-justified text
prefix | " | Right-justified text
prefix | ^ | Centered text
prefix | (space character) | Blank cell
protect | 1 if the cell is locked, 0 if the cell is not locked |
row | Row number of the cell |
type | b | Blank (empty)
type | v | Number or numeric formula
type | l | Text or text formula
width | Column width of the specified cell |

The second example assumes that r3c20 contains a numeric value. The third example assumes that r1c1 contains left-justified text.

CELL("row",r3:4c20:21) | 3
CELL("type",r3:4c20:21) | v
CELL("prefix",!r1c1) | '


CELLPOINTER

Format: CELLPOINTER( cell )
Scope: Spreadsheet
Returns: Numeric

CELLPOINTER is similar to CELL. While CELL yields information concerning the cell whose location or block name you indicate, CELLPOINTER yields information about the currently highlighted cell. The result returned by this function changes according to the location of the current cell when recalculation occurs.

In these examples, the current cell is r10c7:

CELLPOINTER("row") | 10
CELLPOINTER("col") | 7


CELLTEXT

Format: CELLTEXT( text )
Scope: Spreadsheet
Returns: Text

CELLTEXT returns a text expression that exactly matches the screen display of the text or text-equivalent contents of one or more specified cells in a row. The argument for this function must be a text expression in the form of a cell or a (horizontal) block reference. The text returned includes leading and/or trailing spaces, if necessary to represent the full cell width; text exceeding the cell width is truncated.

The following examples refer to the worksheet in Figure 3-2 of Formula Reference Manual.

CELLTEXT("r5c3") | $0.20
CELLTEXT("r5c4:6") | "USA $0.45 400"


CERROR

Format: CERROR
Scope: All
Returns: Numeric

CERROR returns the number of any error resulting from the execution of the immediately preceding command. CERROR returns 0 if no error occurred during the execution of the preceding command. You can use CERROR in a logical formula to identify any errors that may occur during the execution of a project and provide for recovery.
NOTE: CERROR returns the number of the "Current" error; LERROR returns the number of the "Last" or most recent error.

The following fragment of a Database project file illustrates how CERROR can be used to test for the failure of a Data Find command preceding it. When the Database cannot locate the search data, CERROR assumes the value 3716. The If statement calls a function called REDO_FIND that provides the necessary recovery information.

     Data Find "[Last name]" Equal "Kempton" Options "g"
     If CERROR = 3716
          REDO_FIND()
     End if

Refer to Project Processing for a list of the error numbers assumed by this function.

LERROR


CHARINFO

Format: CHARINFO( constant <,param> )
Scope: All
Returns: Conditional

The CHARINFO function is used to relate the row column coordinates of the character based features to the xy coordinates of the GRAPHICS commands. This is useful if you want to write programs that mix the two components.

Informative and conversional calls can be made. The following is a list of accepted constants:

0 char_x | Combined with char_y, this is the upper left corner of row1 col1 in graphics screen.
1 char_y | See char_x.
2 char_h | Font height in pixels.
3 char_w | Font width in pixels.
4 char_x_to_col | Converts x to column.
5 char_y_to_row | Converts y to row.
6 char_col_to_x | Converts column to x.
7 char_row_to_y | Converts row to y.
8 char_x_to_nextrow | Converts xy to rc. Ensures data to left or above does not get overwritten. If x is the first pixel of a character then the conversion is exact, otherwise it selects the next column (or row).
9 char_y_to_nextcol | See char_x_to_nextrow.

Note:
0 - 4 One parameter only, conversion not allowed.
5 - 9 Second parameter is value to convert.

Example:

The following code segment sets up a series of buttons and draws boxes around them. Buttons use row column coordinates, lines use xy graphics coordinates.

     function draw_com_boxes(#x,#y)
     local #x1 #y1 #x2 #y2
     local #ct #row
     local b$settings
        graphics set save b$settings
        #top_com_row = charinfo(char_y_to_nextrow,#y)
        #left_com_col = charinfo(char_x_to_nextcol,#x)
        graphics set line-width 1
        graphics set foreground c_black
        for #ct = 1 to #num_com
           #row = #com_row_offset[#ct] + #top_com_row
           button create at #row #left_com_col #row \
           #left_com_col+#max_len-1 #com_keys[#ct] $com_names[#ct]
           #x1 = charinfo(char_col_to_x,#left_com_col)-#com_margin
           #y1 = charinfo(char_row_to_y,#row)-#com_margin
           #x2 = charinfo(char_col_to_x,#left_com_col+#max_len) \
              +#com_margin
           #y2 = charinfo(char_row_to_y,#row)+charinfo(char_h) \
              +#com_margin
           graphics draw rectangle #x1 #y1 #x2 #y2
        end for
        button draw all
        graphics set restore b$settings
     end function


CHOOSE

Format: CHOOSE( numeric, item list )
Scope: All
Returns: Conditional

CHOOSE creates a logical formula in which the value of the numeric expression determines which item in the item list is returned.

CHOOSE counts the sequence of items in the list and returns the item whose place in the list corresponds to the value of the numeric expression. The count begins with 0. If the numeric expression is equal to 0, the first item in the list is returned. If the value of the numeric expression is less than 0 or greater than the number of items in the list minus 1, the formula returns Error 24 (CHOOSE Failed).

Assume in the following examples that r10c4 contains 2 and that #amt contains 8.

CHOOSE(r10c4,"Zero","One","Two", "Three","Four") | "Two"
CHOOSE(#amt, 10,9,8,7,6,5,4,3,2,1) | 2

CHOOSE is similar to an IF-THEN-ELSE formula. If the first example were approximated in IF-THEN-ELSE form, it would look like this:

     IF r10c4 = 0 THEN "Zero"
          ELSE IF r10c4 = 1 THEN "One"
          ELSE IF r10c4 = 2 THEN "Two"
          ELSE IF r10c4 = 3 THEN "Three"
          ELSE IF r10c4 = 4 THEN "Four"
          ELSE ERRORTEXT(24)


CHR

Format: CHR( numeric )
Scope: All
Returns: Text

CHR returns the text character corresponding to the SmartWare Character Set decimal value of the numeric expression.

CHR(65) | A
CHR(91) | [


CLICKINFO

Format: CLICKINFO( constant )
Scope: All
Returns: Numeric

Identical to EVENTINFO

Returns information about the last event. Typically, it is used after a {mouse} keystroke has been found in the keyboard buffer. The following named constants can be used with the CLICKINFO function:

# Constant | Description
1 m_leftup | Indicates the left button was released.
2 m_leftdown | Indicates the left button was down.
3 m_rightup | Indicates the right button was released.
4 m_rightdown | Indicates the right button was down.
5 m_middleup | Indicates the middle button was released.
6 m_middledown | Indicates the middle button was down.
7 m_row | Row of pointer.
8 m_col | Column of pointer.
9 m_x | x coordinate pixel of pointer.
10 m_y | y coordinate pixel of pointer
11 m_double | Indicates a double click was last up event.
16 m_mnu_id | Indicates the last menu handle an event took place on.
17 m_dde_channel | Indicates the channel number bound to a {DdeRequest} event.
18 m_dde_item | Indicates the item name bound to a {DdeRequest} event.

Example:

     #key = INCHAR
     IF #key = {mouse}
        IF CLICKINFO(m_leftup)
           MESSAGE "The left button was lifted at row"& \
             STR(CLICKINFO(m_row)) & "column" & \
             STR(CLICKINFO(m_col))
        END IF
     END IF

CLICKINFO
MOUSEINFO


COLLATE

Format: COLLATE( text, text )
Scope: All
Returns: Numeric

This function compares two text expressions according to a collation table. A collation table is a sorting sequence used when sorting or merging alphabetic characters. Unlike the ASCII sequence, collation table comparisons treat upper and lower case versions and accented and non-accented versions of the same character as equivalent. Punctuation symbols are also treated as equal.

If the first expression is greater than the second, COLLATE returns 1. If the expressions are equal, COLLATE returns 0. If the first expression is less than the second, COLLATE returns -1.

COLLATE("a","b") | --1
COLLATE("?","&") | 0
COLLATE("A","a") | 0
COLLATE("B","A") | 1


COLS

Format: COLS( block )
Scope: Spreadsheet
Returns: Numeric

COLS returns a numeric value equivalent to the number of columns in the worksheet block.

COLS(r23:109c12:64) | 53
COLS(!r1c1) | 1

ROWS


COLUMN

Format: COLUMN
Scope: Spreadsheet
Returns: Numeric

If entered in a formula in a cell, COLUMN returns the number of the worksheet column in which the formula containing it is located. Otherwise, COLUMN returns the number of the column where the cell highlighter is located.

ROW


COS

Format: COS( numeric )
Scope: All
Returns: Numeric

COS calculates the cosine for the value of the numeric expression. The argument is expressed in radians.

COS(1.1) 0.453596121426


COSH

Format: COSH( numeric )
Scope: All
Returns: Numeric

COSH calculates the hyperbolic cosine for the value of the numeric expression.

COSH(.24) 1.028938505694


COUNT

Format: COUNT( item list )
Scope: All
Returns: Numeric

COUNT returns the number of numeric expressions in the item list. Text expressions and blank or empty items in the list are not counted; items with the value 0 are counted.

COUNT(1,2,3,4) | 4
COUNT(1,"a",3,4,3+2) | 4


@COUNT

Format: @COUNT( item list )
Scope: All
Returns: Numeric

@COUNT returns the number of expressions in the item list. Text expression items with the value 0 are counted. Blank or empty items in the list are not counted.

@COUNT(1,2,3,4) | 4
@COUNT(1,"a",3,4,3+2) | 5


CRYPT

Format: CRYPT( text, text )
Scope: All
Returns: Text

The first parameter is the password to encrypt, the second parameter is a two character "salt" string which changes the encryption algorithm. The CRYPT function returns a garbled string.


CREATE_OBJECT

Format: CREATE_OBJECT( text )
Scope: All
Returns: Object

CREATE_OBJECT creates and returns a reference to an ActiveX object.

For example, the following function will start a Windows Internet browser from an SPL program. Since standard ActiveX Application objects are hidden by default, it will set the object's Visible property to True to show the object, then it will navigate to a specific web site.

     main
        local obj
        obj = create_object("InternetExplorer.Application")
        obj.Visible = True
        obj.Navigate2("http://www.yahoo.com")
     end main

If the function is successful, CREATE_OBJECT will return an object otherwise, 0 is returned.

PROCESS_CREATE


CTERM

Format: CTERM( numeric , numeric , numeric )
Scope: All
Returns: Numeric

CTERM returns a value equal to the number of compounding periods of an investment, based upon the arguments of the formula:

     CTERM ( interest rate, future value, present value )

The CTERM function is used to determine how long it will take the present value of an investment to reach the future value amount, based on a specified compounding period interest rate.

CTERM(.12/12,25000,5000) 161.747

Example:

Suppose you deposited $5000 in an account that pays 12% annual interest, compounded monthly. To determine how long it will be before the $5000 you invested yields $25,000, use the formula CTERM(.12/12,25000,5000). A result of 161.7 months (13.5 years) is returned. The 12% annual interest rate has been divided by 12 months to indicate the interest is compounded monthly.

CTERM uses the following formula to compute the term:

     (LN ((future value) / (present value)) /  LN (1 + (interest rate))


CURRENCY

Format: CURRENCY( numeric )
Scope: All
Returns: Text

CURRENCY converts the numeric expression into a text expression representing the number as a currency value. The resulting text expression has a currency symbol and two decimal places.

CURRENCY(41.446) | "$41.45"
CURRENCY(275+15) | "Rs. 290.00"

In the first example, the currency symbol specified is $ (dollar). In the second example, Rs. (Rupees) is used. Refer to the Tools Preferences Global command in Software System Manual for information on setting a currency symbol.


CurrentRecord

Format: Function name_CurrentRecord( ref Cancel )
Scope: Database

When SmartWare changes records, it will call the CurrentRecord event function with the name of the view as a prefix. Spaces in the view name will be converted into underscores. The CurrentRecord can be in a project file that is attached to the view, or it can be in any project file that is currently loaded.

The ViewUnload event can be used to perform any actions that need to occur whenever the current record changes.

Example (cal is the name of the view):
     Function cal_CurrentRecord()
        ShowRelatedInfo()
     End Function

ViewLoad
ViewUnload


CURRFILES

Format: CURRFILES( numeric )
Scope: All
Returns: Text

CURRFILES returns a text expression consisting of the names of active (loaded) files separated by spaces. The argument must be 0, 1, or 2. The 0 argument causes CURRFILES to return only the file names. A single name appears in the text for active Database views and data-files having identical names. The 1 argument returns the filenames and extensions. The 2 argument returns the complete pathnames of all active files.

CURRFILES(0) | "week1 week2 week3"
CURRFILES(1) | "week1.ws week2.ws week3.ws"
CURRFILES(2) | "\weekly\week1.ws \weekly\week2.ws \weekly\week3.ws"

FILE
GETFNAMES


DATE

Format: DATE( numeric, numeric, numeric )
     DATE( date expression  )
Scope: All
Returns: Numeric

DATE returns the number of days between December 31, 1899, and the day of the date expression. The argument can be a date entered as text, using either an alphabetic or numeric format. If three numeric values separated by commas are entered, SmartWare assumes the date to be a Type 3 date. DATE is functionally equivalent to DAYS.

DATE("9/15/84") | 30939
DATE(57,8,24) -- DAYS("July 6, 1952") | 1875

Date Expressions


DATE1 DATE2 DATE3

Format: DATE1( date ) etc.
Scope: All
Returns: Text formatted as a date

Each of these functions returns the date expression in the corresponding user-definable date format. For example, DATE1 produces a date in Date1 format. Date1 format is one of three formats you can use to control the appearance of date information. The Date Format settings in the Tools Preferences Global menu define these formats.

DATE1("09 15 88") | "15-Sep-88"
DATE2("9/15/88") | "September 15, 1988"
DATE3("September 15, 1988") | "Thursday"

The first example assumes that you have specified the format string "dd-Mon-yy" for the Date1 Format setting. The second assumes you have defined Date2 format as "Month dd, yyyy". The third assumes that Date3 is simply "Day".

Date Expressions


DATEVALUE

Format: DATEVALUE( date )
Scope: All
Returns: Numeric

DATEVALUE returns a decimal number representing a unique date. The number returned is the number of days that have passed between Dec. 31, 1899, and the day of the date expression. The argument must be a date expression type 1 (text) or type 2 (numeric).

DATEVALUE("09/15/84") | 30939
DATEVALUE("12/30/1899") | -1


@DAVERAGE

Format: @DAVERAGE( block, numeric , block )
Scope: Spreadsheet
Returns: Numeric

@DAVERAGE returns the average value in the specified field/column of selected records in a worksheet data base. @DAVERAGE ignores blank and text cells.

All Spreadsheet SDb functions use arguments as follows:

     FUNCTION( database block, column offset, criteria block )

Spreadsheet SDb Arguments


@DAVG

Format: @DAVG( block, numeric, block )
Scope: Spreadsheet
Returns: Numeric

@DAVG returns the average value in the specified field/column of selected records. @DAVG ignores blank cells and treats text cells as having a value of 0.

All Spreadsheet SDb functions use arguments as follows:

     FUNCTION( database block, column offset, criteria block )

Spreadsheet SDb Arguments


DAY

Format: DAY( date )
Scope: All
Returns: Numeric

DAY returns a number corresponding to the day of the month in the date expression.

DAY("July 6, 1988") 6

Date Expressions


DAYNAME

Format: DAYNAME( date )
Scope: All
Returns: Text

DAYNAME returns the name of the day of the week specified in the date expression.

DAYNAME("07-06-52") "Sunday"

Date Expressions


DAYS

Format: DAYS( date )
Scope: All
Returns: Numeric

DAYS returns a decimal number representing a unique date. The number returned is the number of days that have passed between December 31, 1899, and the day of the date expression. Dates prior to December 31, 1899, are returned as negative numbers.

DAYS("24 Aug 57") | 21055
DAYS("09/15/84") | 30939
DAYS(57,08,24) | 21055
DAYS("12/30/1899") | -1

Date Expressions


DAYS2

Format: DAYS2( numeric, numeric, numeric )
Scope: All
Returns: Numeric

DAYS2 returns the number of days between December 31, 1899, and the day of the date expression. The argument must be a date expression type 3.

DAYS2(84,3*3,15) | 30939
DAYS2(57,8,24) -- DAYS("July 6, 1952") | 1875

Date Expressions


DBC_CLOSE

Format: DBC_CLOSE( handle )
OS: DOS and Unix
Scope: All
Returns: Nothing

DBC_CLOSE closes the "cursor" on the indicated database.

     DBC_CLOSE( #cursor_hnd )


DBC_CONNECT

Format: DBC_CONNECT( numeric, numeric, text )
OS: DOS and Unix
Scope: All
Returns: Handle

DBC_CONNECT makes a connection to the specified database and returns a database handle. In order, the parameters are: connect method, number of "cursors", and the connect string.

     #db_handle = DBC_CONNECT( #method, #cursors, dbname )

The connect method is always 1 (MTH_CHANNEL). The number of cursors to obtain has a minimum of 16 however, this amount is ensured.


DBC_COL_INFO

Format: DBC_COL_INFO( handle, numeric, constant )
OS: DOS and Unix
Scope: All
Returns: Numeric

The DBC_COL_INFO function returns information on a specified column in a "list". In order, the parameters are: the "cursor" handle, the column number, and the information constant.

     DBC_COL_INFO( #cursor_hnd, #column, #code )

The information constants are:

dbc_colname | column name
dbc_coltype | column type (returns an integer, see below)
dbc_colwidth | column width

The list below shows the values returned by DBC_COL_INFO when column type is specified. These integers match the data type parameter constants for the DBC_SQL_EXEC.

1 dbc_i1 | one-byte integer
2 dbc_i2 | two-byte integer
3 dbc_i4 | four-byte integer
4 dbc_string | string
5 dbc_f4 | four-byte float
6 dbc_f8 | eight-byte float
7 dbc_date | date
8 dbc_time | time


DBC_CURRENT

Formats:
DBC_CURRENT( handle, text )
DBC_CURRENT( handle, numeric )
DBC_CURRENT( handle, pointer, pointer, ... )
DBC_CURRENT( handle, array_pointer )
OS: DOS and Unix
Scope: All
Returns: Conditional

All formats of the DBC_CURRENT function require a cursor handle returned by a DBC_SELECT function.

The first two forms of the function return the contents of the column specified by the second parameter. This parameter may be either the column name or number.

DBC_CURRENT( #cursor_hnd, "column name")
DBC_CURRENT( #cursor_hnd, #column_number )

The last two forms do not return the contents of a column. Instead, the contents of columns read sequentially from the current "cursor" position are placed into either the variable(s) specified by variable pointer(s) or the array elements specified by the array pointer.

     DBC_CURRENT( #cursor_hnd, VP_1, VP_2, ... VP_n )
     DBC_CURRENT( #cursor_hnd, AP_array )

DBC_CURRENT is similar to the DBC_FETCH and DBC_FETCHP functions.


DBC_DBTYPE

Format: DBC_DBTYPE( handle )
OS: DOS and Unix
Scope: All
Returns: Text

DBC_DBTYPE returns a string indicating the type of database. Its single parameter specifies a database currently connected.

     IF DBC_DBTYPE( #connect_hnd ) = "Informix"

Possible return values are:

Return | Vendor
Not Connect |
Oracle | Oracle
Rdb | DEC
Sybase | Sybase
Informix | Informix
Allbase | HP
DB2/2 | IBM
Ingres | ASK/Ingres
Adabas | Software AG
SQLDB | Software AG
ODBC | Various


DBC_EOF

Formats: DBC_EOF( handle )
OS: DOS and Unix
Scope: All
Returns: Boolean

DBC_EOF is used to determine whether the "cursor" position is outside the boundaries of the "list" specified by the handle parameter. That position may be after the last row or before the first one.

In effect, DBC_EOF returns 1 when the previous DBC_FETCH or DBC_FETCHP functions do not return meaningful data.

In the following example note that the data ($column1) is not operated on until after the DBC_EOF test.

     WHILE TRUE
         $column1 = DBC_FETCH( #cursor_hnd, 1 )
         IF DBC_EOF
            EXIT WHILE
         END IF
         message $column1
     END WHILE


DBC_FETCH

Formats:
DBC_FETCH( handle, text )
DBC_FETCH( handle, numeric )
DBC_FETCH( handle, pointer, pointer, ... )
DBC_FETCH( handle, array pointer )
OS: DOS and Unix
Scope: All
Returns: Conditional

All formats of the DBC_FETCH function require a cursor handle returned by a DBC_SELECT function. Before obtaining any values, DBC_FETCH advances the "cursor" to the next row.

The first two forms of the function return the contents of the column specified by the second parameter. This parameter may be either the column name or number.

     DBC_FETCH( #cursor_hnd, "column name")
     DBC_FETCH( #cursor_hnd,  #column_number )

The last two forms do not return the contents of a column. Instead, the contents of columns read sequentially from the "cursor" position are placed into either the variable(s) specified by variable pointer(s) or the array elements specified by the array pointer.

     DBC_FETCH( #cursor_hnd, VP_1, VP_2, ... VP_n )
     DBC_FETCH( #cursor_hnd, AP_array )

DBC_FETCH is similar to the DBC_FETCHP and DBC_CURRENT
functions.

DBC_CURRENT
DBC_FETCHP


DBC_FETCHP

Formats:
DBC_FETCHP( handle, text )
DBC_FETCHP( handle, numeric )
DBC_FETCHP( handle, pointer, pointer, ... )
DBC_FETCHP( handle, array pointer )
OS: DOS and Unix
Scope: All
Returns: Conditional

All formats of the DBC_FETCHP function require a cursor handle returned by a DBC_SELECT function. Before obtaining any values, DBC_FETCHP moves the "cursor" to the previous row.

Note that not all relational database systems can perform this function.

The first two forms of the function return the contents of the column specified by the second parameter. This parameter may be either the column name or number.

     DBC_FETCHP( #cursor_hnd, "column name")
     DBC_FETCHP( #cursor_hnd,  #column_number )

The last two forms do not return the contents of a column. Instead, the contents of columns read sequentially from the "cursor" position are placed into either the variable(s) specified by variable pointer(s) or the array elements specified by the array pointer.

     DBC_FETCHP( #cursor_hnd, VP_1, VP_2, ... VP_n )
     DBC_FETCHP( #cursor_hnd, AP_array )

DBC_FETCH is similar to the DBC_FETCHP and DBC_CURRENT functions.

DBC_CURRENT
DBC_FETCH


DBC_GET_COLNAMES

Format: DBC_GET_COLNAMES( handle, pointer )
OS: DOS and Unix
Scope: All
Returns: Nothing

This function places the column names of a "list" into an array. The first parameter is the "cursor" handle and the second is a pointer to an array.

     DBC_GET_COLNAMES( #cursor_hnd, ARRAYPTR($columns[1]) )


DBC_NUM_COLS

Format: DBC_NUM_COLS( handle )
OS: DOS and Unix
Scope: All
Returns: Numeric

This function returns the number of columns in a "list".

     #columns = DBC_NUM_COLS( #cursor_hnd )


DBC_RELEASE

Format: DBC_RELEASE( handle )
OS: DOS and Unix
Scope: All
Returns: Nothing

DBC_RELEASE closes the connection to the indicated database. A value of -1 closes all connections.


DBC_SELECT

Format: DBC_SELECT( handle, string <,hostvar, constant> <, hostvar, constant...> )
OS: DOS and Unix
Scope: All
Returns: Handle

DBC_SELECT performs an SQL SELECT statement, creates a "list", and returns a "cursor" handle. The first parameter is the database connect handle and the second parameter is the SQL SELECT statement.

The remaining parameters must be paired as host variable and type constant. The host variables are substituted into the SQL SELECT statement where the first host variable substitutes ":1" in the SQL SELECT statement, the second host variable substitutes ":2", and so on.

     DBC_SELECT( #db_hnd, "select * from "|$dbname, "data", dbc_string )

The following table describes the type constants. These constants match the values returned by the DBC_COL_INFO function when inquiring about the column type.

1 dbc_i1 | one-byte integer
2 dbc_i2 | two-byte integer
3 dbc_i4 | four-byte integer
4 dbc_string | string
5 dbc_f4 | four-byte float
6 dbc_f8 | eight-byte float


DBC_SQL_ERROR

Format: DBC_SQL_ERROR( numeric )
OS: DOS and Unix
Scope: All
Returns: Conditional

DBC_SQL_ERROR returns the message of the last SQL error that has occurred. When LERROR or CERROR is set to 452 ("DBC: SQL Error"), DBC_SQL_ERROR can be used to determine the actual SQL error. If the return type argument is 1, DBC_SQL_ERROR returns the SQL message, otherwise the SQL error code is returned.

     DBC_SQL_ERROR( #returntype )


DBC_SQL_EXEC

Format: DBC_SQL_EXEC( handle, string <, hostvar, constant> <, hostvar, constant...> )
OS: DOS and Unix
Scope: All
Returns: Nothing

DBC_SQL_EXEC executes SQL statements. The first parameter is the database connect handle and the second parameter is the SQL statement.

The remaining parameters must be paired as host variable and type constant. The host variables are substituted into the SQL statement where the first host variable substitutes ":1" in the SQL statement, the second host variable substitutes ":2", and so on.

     DBC_SQL_EXEC( #db_hnd, "SQL statement :1", "data", dbc_string )

The following table describes the type constants. These constants match the values returned by the DBC_COL_INFO function when inquiring about the column type.

1 dbc_i1 | one-byte integer
2 dbc_i2 | two-byte integer
3 dbc_i4 | four-byte integer
4 dbc_string | string
5 dbc_f4 | four-byte float
6 dbc_f8 | eight-byte float

NOTE: DBC_SQL_EXEC cannot be used as a replacement for the DBC_SQL_SELECT function because it does not return a "cursor".


DBC_TRANS_START, DBC_TRANS_COMMIT, and

DBC_TRANS_ABORT

Formats:
DBC_TRANS_START( handle )
DBC_TRANS_COMMIT( handle )
DBC_TRANS_ABORT( handle )
OS: DOS and Unix
Scope: All
Returns: Nothing

These functions are somewhat analogous to the LOCK-RECORD, WRITE-RECORD, and CANCEL-RECORD commands. Data is written to the database with an SQL statement issued through the DBC_SQL_EXEC function.


DBFLDAT

Format: DBFLDAT( numeric, numeric )
Scope: Database
Returns: Text

DBFLDAT returns the field name at the location specified. If the coordinates do not match any field position, null is returned. The arguments are as follows:

DBFLDAT( row, column )


DBFLDINFO

Format: DBFLDINFO( field, flag )
Scope: Database
Returns: Conditional

DBFLDINFO returns information about a database field. The first argument, field, is either a numeric value representing the field number or a string representing a field name in the current view. The second argument is a flag or constant that specifies the type of data to be returned, as follows:

# Constant | Returns
0 dbf_name | View field name.
1 dbf_type | Field type: 1 (inverted), 2 (alpha), 3 (numeric), 4 (counter), 5 (date), 6 (time).
2 dbf_dbwidth | Field storage width.
3 dbf_scrwidth | Field screen width.
4 dbf_iskey | Key field: 0 (no) 1 (yes).
5 dbf_ontable | On table: 0 (no) 1 (yes).
6 dbf_table | Table name.
7 dbf_startrow | Start row. Returns -1 if not on the screen.
8 dbf_startcol | Start column. Returns -1 if not on the screen.
9 dbf_endrow | End row. If the file is in browse mode or the field is on a table, this is the row location of its bottom right corner.
10 dbf_endcol | End column. If the file is in browse mode or the field is on a table, this is the column location of its bottom right corner.
11 dbf_filenum | Data file number of the field (or view only field): 0 (driver data file) 1-127 (driven data file) 128 (view only field). To find the actual name of the file, see the DBINFO function.
12 dbf_attrib | Field attribute: 0 (read/write) 1 (read only) 2 (mandatory entry) 3 (project write).
13 dbf_dbname | Data file field name.
14 dbf_relstartrow | Combined with the following three constants, this refers to the position of a field relative to the view's top left corner (not the screen coordinates). A position is returned even if the field is not currently displayed.
15 dbf_relstartcol | See dbf_relstartrow.
16 dbf_relendrow | See dbf_relstartrow.
17 dbf_relendcol | See dbf_relstartrow.
18 dbf_dispform | Display format.
19 dbf_inpmask | Input mask.
20 dbf_message | Data entry message.
21 dbf_default | Default equation.
22 dbf_menutype | Menu type: 0 (none) 1 (bar menu) 2 (pop-up) 3 (data file).
23 dbf_menuchoices | String of menu choices. If the menu is a data file type, field names are returned.
24 dbf_calctype | Calculation type: 0 (none) 1 (immediate) 2 (wait) 3 (manual).
25 dbf_calculation | Calculation.
26 dbf_autoadv | Automatic advance field 0 (no) 1 (yes).
27 dbf_titleplace | Location of field title 0 (none) 1 (above) 2 (left).
28 dbf_datafg | Data foreground color.
29 dbf_databg | Data background color.
30 dbf_titlefg | Title foreground color.
31 dbf_titlebg | Title background color.
32 dbf_popupdb | Pop-up menu data file name.
33 dbf_popupreturn | Field returned in pop-up menu.

In the following examples, DBFLDINFO first returns an alpha field type for the field [name]. The second example returns the field name for field 1.

DBFLDINFO("[name]",1) | 2
DBFLDINFO(1,0) | name

APINFO
DBINFO


DBGET

Format: DBGET( text)
Scope: Database
Returns: Conditional

DBGET returns the contents of a field. The argument is a text expression in the form of a field reference. The view name may be included, if you are referring to an active view other than the current view.

The following examples assume that the field [amt] contains 1000, and [ytd.tax] contains 362.00.

DBGET("[amt]") | 1000
DBGET("[ytd.tax]") | 362.00


DBINFO

Format: DBINFO(named constant)
Scope: Database
Returns: Conditional

DBINFO returns a variety of information about the current view, depending upon the named constant specified in the argument. Valid arguments and their return values are as follows:

Name | Return Value
0 db_browse | 1 (TRUE) if SmartWare is in Browse Mode; 0 (FALSE) if SmartWare is not in Browse Mode.
1 db_fields | The total number of fields on the current view.
2 db_order | A number representing the current view order: 0 = physical, 1 = key, 2 = index.
3 db_orderfld | A string containing the name of the key field by which the view is currently ordered. If the view is not in key order, an empty string ("") is returned.
4 db_orderidx | A string containing the name of the index by which the view is currently ordered. If the view is not in index order, an empty string ("") is returned.
5 db_tables | A string containing the names of the tables on the current view. The table names are enclosed in angle brackets, <>, and separated by spaces. If the view contains no tables, an empty string ("") is returned.
6 db_curtable | A string containing the name of the current table. If no table is present, an empty string ("") is returned.
7 db_enter | 1 (TRUE) if SmartWare is in Enter/Update Mode; 0 (FALSE) if SmartWare is not in Enter/Update Mode.
8 db_recalc | 1 (TRUE) if the recalculation being called is the recalculation performed when a record is saved; 0 (FALSE) if the recalculation being called is not the recalculation performed when a record is saved (i.e., the recalculation performed when the cursor passes through a calculated field, or when no calculation at all is being executed.)
9 db_orderidxpfe | A string that contains the full name, including path and extension, of the current index.
10 db_top | The db_top constant combined with db_left, db_bottom, and db_right refer to the current position of a view within its window (not the screen coordinates). For instance, on a multi-paged view that has been scrolled down two lines, DBINFO(db_top) would return 3 regardless of the view's screen coordinates. Since these returned values are relative, they can also be used to determine the size of the window.
11 db_left | See db_top.
12 db_bottom | See db_top.
13 db_right | See db_top.
14 db_height | The height of a view regardless of screen size.
15 db_width | The width of a view regardless of screen size.
16 db_row | The top row on the screen. Border on/off can affect this value.
17 db_col | The leftmost column on the screen. Border on/off can affect this value.
18 db_files | The number of data files on a view.
19 db_text_items | The number of text items on a view.
20 db_num_tables | The number of table items on a view.
1000 db_driver | A string containing the name of the driver data file. The value of this constant is 1000.
1001+ db_driven | A string containing the name of the first driven data file. The value of this constant is 1001. Though there are no constants for the remaining driven files, these names can be returned by passing a numeric value to DBINFO rather than a constant. Add one to db_driven (maximum of 1127) for each subsequent file. See Example 2.
2001+ db_paths | The path of the data files. Like the db_driver + db_driven constants combined, each number added to it refers to the next file. If same as view path, null is returned.
3001+ db_pathexps | The path expression of the data files. With a value of 3000, it behaves similarly to db_path. If no expression is used, null is returned.
4000 db_dvrlinks | The driver link fields (names on view). While its value is 4000, it actually returns nothing unless a value is added to it.
5000 db_dvnlinks | The driven link fields (names on data file - key fields). Similar to db_dvrlinks.
6000 db_types | The type of the data files. Behaves similarly to db_paths. The return value is DB_TYPE_SW4, DB_TYPE_SW5_LOC, or DB_TYPE_SW5_CS.
7000 db_servers | If the db_type is DB_TYPE_SW5_CS, then the return value is the name of the server this data-file is on.
8000 db_userids | If the db_type is DB_TYPE_SW5_CS, then the return value is the User ID of this data-file.
9000 db_typeexps | The data-file type expression of the data files. With a value of 9000, it behaves similarly to db_types. If no expression is used, null is returned.
10000 db_serverexps | The server expression of the data files. With a value of 10000, it behaves similarly to db_servers. If no expression is used, null is returned.
11000 db_useridexps | The user id expression of the data files. With a value of 11000, it behaves similarly to db_userids. If no expression is used, null is returned.

For example, you might use DBINFO(db_recalc) to control the execution of the ASK function.

Example 1:

     IF DBINFO(db_recalc) <> TRUE
        THEN ASK("Enter amount")
     ELSE NOCHANGE

Example 2:

     'Display the name of each driven data file
     #filesdriven = DBINFO(db_files)-1 'driver not included
     FOR #ct = 1 TO #filesdriven
        #driven = db_driven + #ct - 1  'db_driven+0 is 1st file
        $file = DBINFO( #driven )
        MESSAGE "Driven file" & str(#driven) & "is:" & $file
     END FOR

DBFLDINFO
APINFO


DBKEY, SSKEY and WPKEY

Format: DBKEY( numeric )
Scope: Database, Spreadsheet, Word Processor
Returns: Numeric

DBKEY, SSKEY and WPKEY are used by project processing programs to control cursor movement. They are good alternatives to SUSPEND/KEYS statements since unnecessary screen flashing does not occur and performance is improved.

All three functions pass a given keystroke to the underlying module. If a cursor movement keystroke was processed, 1 is returned, otherwise, the keystroke was not a cursor movement key and 0 is returned.

DBKEY, SSKEY and WPKEY handle all movement keys and mouse activity.

Example 1:

     WPKEY({down})  'Move the cursor down one line

Example 2:

     'Control navigation by cursor keys, mouse clicks and scroll bar
     WHILE #key<>{esc}
        #key = INCHAR
        IF WPKEY(#key)    'Key was cursor movement
           '(process command)
        ELSE              'Key was NOT cursor movement
           '(process command)
        END IF
     END WHILE

KEYS


DBPUT

Format: DBPUT( text, expression )
Scope: Database
Returns: Numeric

DBPUT places data into a specific field, returning TRUE (1) if the procedure is successful, or FALSE (0) if the procedure is not successful. The first argument must be a text expression in the form of a field reference. The second argument is the data being placed in the field.

The procedure fails if the target field is defined as read only. If the target field is defined as mandatory entry and you attempt to place BLANK into it, failure also occurs. Finally, DBPUT fails when the data does not conform to rules defined for the field contents in the view definition. When failure occurs, data previously in the field is retained.

The following examples indicate that the DBPUT function executed successfully. In the first example, 2 was put into field [exemp]. In the second example, the sum of [ytd] and [curr] was put into [tot.tax].

DBPUT("[exemp]",2) | 1
DBPUT("[tot.tax]",[ytd]+[curr]) | 1


DCOUNT

Format: DCOUNT( block, numeric, block )
Scope: Spreadsheet
Returns: Numeric

DCOUNT returns the number of value entries in the specified field/column of selected records. DCOUNT ignores blank and text cells.

All Spreadsheet SDb functions use arguments as follows:

     FUNCTION( database block, column offset, criteria block )

Spreadsheet SDb Arguments


@DCOUNT

Format: @DCOUNT( block, numeric, block )
Scope: Spreadsheet
Returns: Numeric

@DCOUNT returns the number of value and text entries in the specified field/column of selected records. @DCOUNT ignores blank cells.

All Spreadsheet SDb functions use arguments as follows:

     FUNCTION( database block, column offset, criteria block )

Spreadsheet SDb Arguments


DDB

Format: DDB( numeric, numeric, numeric, numeric )
Scope: All
Returns: Numeric

DDB returns a double declining balance depreciation value, which is determined by the following arguments:

     DDB ( cost value, salvage value, useful life, term )

DDB accelerates the rate of depreciation so that a greater depreciation expense occurs early in the term. When the book value of the asset reaches the salvage value, depreciation stops. The book value in any period is defined as the total cost of the asset minus the total depreciation over all prior periods.

The double-declining balance depreciation in any period is computed as:

     (Book value) * 2 / (life of asset)

The result of the formula is adjusted as necessary to ensure that total depreciation for the life of the asset equals the asset's cost minus its salvage value.

DDB(15000,2000,7,1) | 4285.71
DDB(15000,2000,7,3) | 2186.59
DDB(15000,2000,7,6) | 789.02

Example:

Suppose you purchase a $15,000 automobile which has a useful life of seven years and a salvage value of $2000 at the end of the seven years. The first formula listed above is used to determine what the depreciation rate would be for the first year of the car's useful life and returns a result of $4285.71. The second formula computes the depreciation rate for the third year of the car's useful life and returns a result of $2186.59. The third formula returns a result of $789.02, indicating the depreciation rate for the sixth year of the car's useful life.

SLN
SYD


DDE_ACCEPT

Format: DDE_ACCEPT( text, text )
Scope: All (Windows)
Returns: Numeric

ANGOSS DDE servers are set up with the DDE_ACCEPT function. It announces to the rest of the computer the given server and topic names.

     #channel = DDE_ACCEPT( "server_name", "topic" )


DDE_ADVISE

Format: DDE_ADVISE( channel, text )
Scope: All (Windows)
Returns: Numeric

DDE_ADVISE performs two functions depending on whether the ANGOSS application is a DDE client or server. When the application is a client, DDE_ADVISE tells the server to notify it when a specified item is changed. When the application is an ANGOSS server, DDE_ADVISE announces that a specified item is available for "warm link" processing. Assuming the server is an ANGOSS application, a client may only request notification of change on those available items. In either case, any number of DDE_ADVISE calls can be made.

     DDE_ADVISE( #channel, "item" )

If a client requests it, the server will be given a {DdeAdvise} event.


DDE_CHANNEL

Format: DDE_CHANNEL
Scope: All (Windows)
Returns: Numeric

This function returns a channel number when the DDE server has received a {DdeRequest} event. An alternative is to use EVENTINFO with the m_dde_handle constant.

     #channel = DDE_CHANNEL


DDE_DATA

Format: DDE_DATA( channel, text, text )
Scope: All (Windows)
Returns: Numeric

DDE_DATA is used by a server to respond to a client's request by sending new data back. The channel and item can be determined with the DDE_CHANNEL and DDE_ITEM functions.

     DDE_DATA( #channel, $item, "send data" )


DDE_ERROR

Format: DDE_ERROR( channel )
Scope: All (Windows)
Returns: Numeric

DDE_ERROR is used by a server to respond to a client's request when the server cannot provide a value for the requested item. The channel can be determined with the DDE_CHANNEL function.

     DDE_ERROR( #channel )


DDE_EXECUTE

Format: DDE_EXECUTE( channel, text )
Scope: All (Windows)
Returns: Numeric

DDE_EXECUTE sends a command string to the server for "execution". Whether or not this string uses acceptable syntax is determined by the server.

     DDE_EXECUTE( #channel, "command string" )


DDE_INITIATE

Format: DDE_INITIATE( text, text )
Scope: All (Windows)
Returns: Numeric

DDE_INITIATE starts a conversation with the named server about the given topic. The returned integer is the channel number used in subsequent exchanges. A returned value of zero indicates that the server does not exist or that it cannot converse on the topic.

     #channel = DDE_INITIATE( "server_name", "topic" )

Note that the PROCESS_CREATE function can be used to start a server.

PROCESS_CREATE


DDE_ITEM

Format: DDE_ITEM
Scope: All (Windows)
Returns: Text

This function returns an item name when the DDE server has received a {DdeRequest} event. An alternative is to use EVENTINFO with the m_dde_item constant.

     $item = DDE_ITEM


DDE_POKE

Format: DDE_POKE( channel, text, text )
Scope: All (Windows)
Returns: Numeric

DDE_POKE attempts to poke a new value into the server - that is, it tries to assign a new value to the given item. Note that not all servers will accept these requests.

     DDE_POKE( #channel, "item", "new value" )


DDE_REQUEST

Format: DDE_REQUEST( channel, text )
Scope: All (Windows)
Returns: Text

DDE_REQUEST sends a request to the server for the value of a specified item. If successful, a string value corresponding to the value of the "item" is returned.

     DDE_REQUEST( #channel, "item" )


DDE_TERMINATE

Format: DDE_TERMINATE( channel )
Scope: All (Windows)
Returns: Numeric

This terminates the link to the server.

     DDE_TERMINATE( #channel )


DDE_TIMEOUT

Format: DDE_TIMEOUT( channel, numeric )
Scope: All (Windows)
Returns: Numeric

This sets the time-out value used by the DDE client.

     DDE_TIMEOUT( #channel, #timeout )


DDE_UNADVISE

Format: DDE_UNADVISE( channel, text )
Scope: All (Windows)
Returns: Numeric

DDE_UNADVISE removes a DDE_ADVISE item.

     DDE_UNADVISE( #channel, "item" )


DELETED

Format: DELETED
Scope: Database
Returns: Numeric

DELETED returns TRUE (1) if the current record is deleted and FALSE (0) if the current record is not deleted.


DICTCOMP

Format: DICTCOMP(text,text)
Scope: All
Returns: Numeric

This function compares two text expressions with a true dictionary comparison. The case and accent of a letter will be taken into consideration if the comparison is otherwise equal. Results returned by DICTCOMP are affected by the currently selected character comparison table. If you will be comparing foreign language characters, it is important that you select the proper character comparison table for that language. The character comparison table is specified on the Global Preferences menu.

If the first expression is greater than the second, DICTCOMP returns 1. If the expressions are equal, DICTCOMP returns 0. If the first expression is less than the second, DICTCOMP returns -1.


DIRPROMPT

Format: DIRPROMPT
Scope: All
Returns: Text

DIRPROMPT calls the ANGOSS file prompter in directory mode. A single directory may be selected. No parameters are required.

FILEPROMPT


@DMAX

Format: @DMAX( block, numeric, block )
Scope: Spreadsheet
Returns: Numeric

@DMAX returns the maximum value among the value entries in the specified field/column of selected records.

All Spreadsheet SDb functions use arguments as follows:

     FUNCTION( database block, column offset, criteria block )

Spreadsheet SDb Arguments


@DMIN

Format: @DMIN( block, numeric, block )
Scope: Spreadsheet
Returns: Numeric

@DMIN returns the minimum value among the value entries in the specified field/column of selected records.

All Spreadsheet SDb functions use arguments as follows:

     FUNCTION( database block, column offset, criteria block )

Spreadsheet SDb Arguments


DOSOFFSET

Format: DOSOFFSET( text )
Scope: All
Returns: Numeric

DOSOFFSET returns the offset (lower two bytes) of the memory address of the data referenced by a variable. The argument is the name of an existing variable. The variable must contain text or a buffer. For more information, see the discussion of the Buffer command in the Project Processing manual.
NOTE: This function was designed for use in a DOS environment.


DOSPTR

Format: DOSPTR( text )
Scope: All
Returns: Numeric

The DOSPTR function returns segment and offset (four bytes) of the memory address of the data referenced by a variable. The argument is the name of an existing variable. The variable must contain text or a buffer. For more information, see the discussion of the Buffer command in the Project Processing manual.
NOTE: If the variable contains a low memory buffer and a real mode address is necessary for use with PEEK or POKE, REAL FARCALL, or REAL INTERRUPT, use the REALPTR function.


DOSSEG

Format: DOSSEG( text )
Scope: All
Returns: Numeric

DOSSEG returns the segment (upper two bytes) of the memory address of the data referenced by a variable. The argument is the name of an existing variable. The variable must contain text or a buffer. For more information, see the discussion of the Buffer command in the Project Processing manual.
NOTE: If the variable contains a low memory buffer and a real mode address is necessary for use with PEEK or POKE, REAL FARCALL, or REAL INTERRUPT, use the REALSEG function.


@DSTD

Format: @DSTD( block , numeric, block )
Scope: Spreadsheet
Returns: Numeric

@DSTD returns the standard deviation of a population for the values in the specified field/column of selected records. See STD for further information.

All Spreadsheet SDb functions use arguments as follows:

     FUNCTION( database block, column offset, criteria block )

Spreadsheet SDb Arguments
STD


@DSTDEV

Format: @DSTDEV( block, numeric, block )
Scope: Spreadsheet
Returns: Numeric

@DSTDEV returns the standard deviation of a sample for the values in the specified field/column of selected records. See STDEV for further information.

All Spreadsheet SDb functions use arguments as follows:

     FUNCTION( database block, column offset, criteria block )

Spreadsheet SDb Arguments


@DSUM

Format: @DSUM( block, numeric, block )
Scope: Spreadsheet
Returns: Numeric

@DSUM returns the sum of values in the specified field/column of selected records.

All Spreadsheet SDb functions use arguments as follows:

     FUNCTION( database block, column offset, criteria block )

Spreadsheet SDb Arguments


@DSUMSQ

Format: @DSUMSQ( block, numeric, block )
Scope: Spreadsheet
Returns: Numeric

@DSUMSQ returns the sum of the square of the values in the specified field/column of selected records.

All Spreadsheet SDb functions use arguments as follows:

     FUNCTION( database block, column offset, criteria block )

Spreadsheet SDb Arguments


DVAR

Format: DVAR( block, numeric, block )
Scope: Spreadsheet
Returns: Numeric

DVAR returns the sample variance of the values in the specified field/column of selected records.

All Spreadsheet SDb functions use arguments as follows:

     FUNCTION( database block, column offset, criteria block )

Spreadsheet SDb Arguments


@DVAR

Format: @DVAR( block, numeric, block )
Scope: Spreadsheet
Returns: Numeric

@DVAR returns the population variance of the values in the specified field/column of selected records.

All Spreadsheet SDb functions use arguments as follows:

     FUNCTION( database block, column offset, criteria block )

Spreadsheet SDb Arguments


EOF

Format: EOF( numeric )
Scope: All
Returns: Numeric

EOF returns TRUE (1) when SmartWare detects the end of the file during processing with the Fread and Fseek project commands. Otherwise, EOF returns FALSE (0). The argument is the file number assigned to the file when it is opened with the Fopen command.

When Fread's Length option is specified, EOF returns TRUE upon encountering the end of the file. When Fread's Length option is not specified, EOF returns TRUE when detecting the actual end of the file or an end-of-file character (ASCII 26). Consult Project Processing for more information on processing data files with these commands.


ERROR

Format: ERROR
Scope: All
Returns: Error

ERROR returns Error 35 (User error). ERROR is used in a logical formula to indicate a condition that you want to identify as an error but that would not otherwise be treated as an error by SmartWare.

IF #SCORE <= 100 THEN #SCORE ELSE ERROR | Error 35
IF r1c1 > 1 THEN ERROR ELSE r1c1 * sales | 100

The first example assumes #SCORE to be greater than 100.

The second example illustrates the use of ERROR to check cell entries in the Spreadsheet. In this example the named cell "sales" contains a dollar amount of sales. Cell r1c1 contains a value that is a percentage of sales for an item. You are using ERROR to determine that the percentage of sales figures is not over 1 (100%). If r1c1 is greater than 1 (100%) "Error 35" will be displayed in the formula cell.


ERRORTEXT

Format: ERRORTEXT( numeric )
Scope: All
Returns: Text

The ERRORTEXT function returns the error message of the error specified (by number) in the argument. See Project Processing for a list of error numbers and messages used by SmartWare.

ERRORTEXT(35) | "User error"
ERRORTEXT(4) | "Bad syntax"


EVENTINFO

Format: EVENTINFO( constant )
Scope: All
Returns: Numeric

Identical to CLICKINFO. This is a more descriptive name because it is used for more than mouse click events (notably after the {MouseMoved} function). In future releases it may return information on scroll bars, resizing events, etc.

Returns information about the last event. Typically, it is used after a {mouse} keystroke has been found in the keyboard buffer. The following named constants can be used with the CLICKINFO function:

# Constant | Description
1 m_leftup | Indicates the left button was released.
2 m_leftdown | Indicates the left button was down.
3 m_rightup | Indicates the right button was released.
4 m_rightdown | Indicates the right button was down.
5 m_middleup | Indicates the middle button was released.
6 m_middledown | Indicates the middle button was down.
7 m_row | Row of pointer.
8 m_col | Column of pointer.
9 m_x | x coordinate pixel of pointer.
10 m_y | y coordinate pixel of pointer
11 m_double | Indicates a double click was last up event.
16 m_mnu_id | Indicates the last menu handle an event took place on.
17 m_dde_channel | Indicates the channel number bound to a {DdeRequest} event.
18 m_dde_item | Indicates the item name bound to a {DdeRequest} event.

Example:

     #key = INCHAR
     IF #key = {mouse}
        IF CLICKINFO(m_leftup)
           MESSAGE "The left button was lifted at row"& \
             STR(CLICKINFO(m_row)) & "column" & \
             STR(CLICKINFO(m_col))
        END IF
     END IF

MOUSEINFO


EXACT

Format: EXACT( text, text )
Scope: All
Returns: Numeric

The EXACT function can be used as an alternative to the = operator in a formula, to test whether two text strings contain exactly the same characters. EXACT returns TRUE (1) if the two text strings are identical and FALSE (0) if they are not.

The second example assumes that r6c12 contains "Toronto".

EXACT("John","john") | 0
EXACT(r6c12,"Toronto") | 1
EXACT("1234","12345") | 0

Logical Operators


EXP

Format: EXP( numeric )
Scope: All
Returns: Numeric

EXP calculates the value of "e" (the natural logarithm base: 2.7182818 . . .) taken to the power of the numeric expression.

EXP(1.1) 3.00416602395


EXPONENTIAL

Format: EXPONENTIAL( numeric )
Scope: All
Returns: Numeric

EXPONENTIAL returns a number randomly selected from an exponential distribution. The value of the numeric expression specifies the standard deviation of the distribution.

NORMAL
RAND
UNIFORM


FACTORIAL

Format: FACTORIAL( numeric )
Scope: All
Returns: Numeric

FACTORIAL converts the argument to an integer and returns the value according to the following equation. The argument must be a positive number. A negative number returns a value of 1.

     FACTORIAL(n) = n*(n-1)*(n-2) . . . *(2)*(1)

For example, FACTORIAL(5) is the same as 5 * 4 * 3 * 2 * 1.

FACTORIAL(5) 120


FACTUAL

Format: FACTUAL
Scope: All
Returns: Numeric

FACTUAL returns the number of bytes read in the most recent Fread project command. Consult the Project Processing manual for more information on processing data files with this command.


FALSE

Format: FALSE
Scope: All
Returns: Numeric

FALSE returns the value 0. FALSE can be used in logical formulas to signal that a condition does not exist.

TRUE


FETCHFIELD

Format: FETCHFIELD( field )
Scope: Database
Returns: Conditional

FETCHFIELD returns the contents of the specified field in the last record accessed. The field must be a data-file field. FETCHFIELD offers the ability to accomplish in a formula a result similar to that produced by pressing F9 in Enter/Update mode.
NOTE: FETCHFIELD returns the NA status for the first record accessed. However, if FETCHFIELD returns the contents for a record other than record 1 and then you move the cursor to record 1, the other record becomes the last record accessed. At that point, a FETCHFIELD on record 1 will return the contents, not the NA status. Note, also, that reordering the file, with the Order Change command, for example, resets the last record accessed.


FGBACKGROUND FGDIMPLEASING FGEDITING FGERROR FGHIPLEASING

FGINVPLEASING FGINVSTANDARD FGPLEASING FGSTANDARD

Format: FGBACKGROUND
Scope: All
Returns: Numeric

These functions return the color numbers of standard foreground colors used in SmartWare screen displays. The values returned by these functions vary according to the screen driver currently in use. Using these functions for the color entries in Screen command statements guarantees acceptable foreground/background contrast regardless of the screen driver or display type that you are using. This practice also allows you to display text in colors consistent with various elements of SmartWare's display.

The following table shows the SmartWare display element whose foreground color is represented by each function.

Function | Use in SmartWare Display
FGBACKGROUND | Foreground of labels on the status line
FGDIMPLEASING | Foreground of the unavailable items on the paper profile menu
FGEDITING | Foreground of SmartWare editors and the highlighted portion of the Status Line
FGERROR | Foreground of an error message
FHIPLEASING | Foreground of valid items on the paper profile menu
FGINVPLEASING | Foreground of selected items in definition menus
FGINVSTANDARD | Foreground of the highlighted item in a SmartWare module menu
FGPLEASING | Foreground of definition menus
FGSTANDARD | Foreground of a SmartWare module menu

BGBACKGROUND


FIELDTEXT

Format: FIELDTEXT( text )
Scope: Database
Returns: Text

FIELDTEXT returns a text expression that represents the exact displayed content of a SmartWare Database field. The argument for this function must be a text expression in the form of a field name.

Any special formatting attached to the field will be included. This function is similar to the CELLTEXT function in SmartWare Spreadsheet.

The following example is derived from Figure 3-6 in Chapter 3 of the Formula Reference Manual.

FIELDTEXT([Stone]) Agate

Notice that if your data is displayed in Browse format, the text returned is the content of the highlighted field. If your data is displayed in standard format, the text returned is the content of the currently displayed field.


FILE

Format: FILE( text )
Scope: All
Returns: Numeric

FILE returns TRUE (1) if a file named by the argument exists in the directory. Otherwise, FILE returns FALSE (0). The argument must include the filename and extension and may include a pathname appropriate for the operating system you are using.

FILE("letter.doc") | 1
FILE("\mydir\data\income.ws") | 0
FILE("d:\skram.pf2") | 1

The above examples indicate that letter.doc and d:\skram.pf2 were found; \mydir\data\income.ws was not found.


FILEAVERAGE

Format: FILEAVERAGE(field <, logical>)
Scope: Database
Returns: Numeric

FILEAVERAGE computes the average value in the specified field for all records in a view. Only nonblank fields are included in the calculation.
NOTE: Refer to Chapter 3 of the Formula Reference Manual for more information on using Statistical Database (SDb) functions in the Database.

You can enter a logical expression as an optional second argument. Each record is evaluated to determine if it fits the condition specified in the logical expression. If the expression is true for a record, the record is included in the calculation. If the expression is false, the record is not included.

     FILEAVERAGE([ytd])
     FILEAVERAGE([ytd],[yr]>1987)

The first example computes the average of all non-blank values in the [ytd] field. The second example computes the average of all [ytd] values in records where [yr] is greater than 1987.


FILECOUNT

Format: FILECOUNT(field <, logical>)
Scope: Database
Returns: Numeric

FILECOUNT counts the number of non-blank entries in the specified field for all records in a view.

You can enter a logical expression as an optional second argument. Each record is evaluated to determine if it fits the condition specified in the logical expression. If the expression is true for a record, the record is included in the calculation. If the expression is false, the record is not included.

     FILECOUNT([ytd])
     FILECOUNT([ytd],[yr]>1987)

The first example counts the number of records having entries (non-blank) in [ytd]. The second example counts [ytd] entries in records where [yr] is greater than 1987.


FILEINFO

Format: FILEINFO(filename, named constant)
Scope: All
Returns: Numeric

FILEINFO returns system information regarding the specified file or directory. The table below lists the constants that indicate the type of information returned:

# Constant | Return Value
0 f_type | 0=file does not exist, 1=file, 2 = directory
1 f_datetime | Integer=date, Fraction=time (Like the NOW function)
2 f_size | File size in bytes
3 f_uid | Integer representing user id owning file (DOS = 0)
4 f_gid | Integer representing group id owning file (DOS = 0)
5 f_writable | 1 for writable, otherwise 0
6 f_readable | 1 for readable, otherwise 0

Example:

     IF FILEINFO("C:\DOS",f_type)=2
        MESSAGE "Directory C:\DOS exists."
     END IF
     #age = NOW - FILEINFO("C:\B.BAT",1)
     MESSAGE "B.BAT modified" & str(seconds(#age)) & "seconds ago."

APINFO


FILELIST_CLOSE

Format: FILELIST_CLOSE
Scope: All
Returns: 0

This closes an open file list. For every successful call to FILELIST_OPEN, a close must be issued. Failure to do so will cause errors and SmartWare will not be able to find files.

For details on using file lists, refer to the FILELIST_OPEN function.

FILELIST_OPEN


FILELIST_OPEN

Format: FILELIST_OPEN( text, numeric )
Scope: All
Returns: text

This initiates a file list and returns the first file matching the file spec.

     FILELIST_OPEN( $filespec, #directories )

The first parameter indicates the file spec. Path and wild card characters can be included. For example, when "*.txt" is passed, this function opens a file list on the current directory and filters out any file that does not have a "txt" extension.

Directories are included in the file list when the second parameter is set to TRUE (1).

If no files or directories are found, a null string ("") is returned. Otherwise, the first matching file or directory name is returned.

To get the next name, use FILELIST_NEXT.

Except when a null string is returned (no files or directories found), the SPL program must eventually close the list with the FILELIST_CLOSE function.

Example:

The example code opens a file list and returns the first file matching the "*.txt" file spec in the current directory. A WHILE loop is then started. If no files or directories are found, the loop is aborted. If a file is found, its name is displayed, a close flag is set, and the next file is returned. This continues until FILELIST_NEXT returns a null string (no more files found). Finally, if the close flag is set, FILELIST_CLOSE is called.

     MAIN
     LOCAL $file #close

         $file = FILELIST_OPEN( "*.txt", 2 )
         WHILE TRUE
            if $file = ""
               EXIT WHILE
            end if
            MESSAGE $file
            #close = 1
            $file = FILELIST_NEXT
         END WHILE

         IF #close
            FILELIST_CLOSE
         END IF

     END MAIN

Notes:

Multiple file lists can be opened. Because FILELIST_OPEN uses a stack, it can be called again before a FILELIST_CLOSE is issued. This has the effect of leaving the previous list open and making the new list current - useful when climbing up and down directory structures. When the new list is closed, the previous list becomes active and FILELIST_NEXT continues to operate where it left off. The maximum number of open lists is 100.

Lists must eventually be closed. If repeatedly left open, errors will occur and SmartWare will not be able to find files.

If FILELIST_OPEN does not return a file or directory name, FILELIST_CLOSE should not be called. In this case, no list is actually opened and FILELIST_CLOSE may, inadvertently, close the current list.

The file list functions do not employ a user interface. Use FILEPROMPT for that task.

See also FILELIST_NEXT and FILELIST_CLOSE.

FILELIST_NEXT
FILELIST_CLOSE


FILELIST_NEXT

Format: FILELIST_NEXT
Scope: All
Returns: text

This returns the next file or directory name in an opened file list. When FILELIST_NEXT returns a null string (""), no more files or directories exist in the list.

For details on using file lists, refer to the FILELIST_OPEN function.

FILELIST_OPEN


FILELOOKUP

Format: FILELOOKUP( field, field, expression <,minor fields> )
Scope: Database
Returns: Conditional

FILELOOKUP searches a file for a data item in a specified field. When it encounters a record containing the search item, FILELOOKUP returns data from another specified field of that same record. If the search item exists in multiple records, FILELOOKUP returns data from the first record it encounters. The search field must be a key field, however, the file does not have to be in order by that field. The searched file must not be in index order.

The arguments are used as follows:

FILELOOKUP ( field searched, field returned, search data )

FILELOOKUP ([City], [State], "Greenville") "Alabama"

In the formula above, FILELOOKUP searches the key field [City] for the data "Greenville". The first record in which a match occurs contains the data "Alabama" in the field [State].
NOTE: FILELOOKUP and the File SDb functions cannot be nested.

FILELOOKUP supports searching of a minor key field. To specify the data for the minor key fields, place the data as the fourth parameter, separated by commas, in the order of the minor key fields. For example

FILELOOKUP ([State],[Population],"Alabama","Greenville")

The above example returns the population of Greenville, Alabama. It assumes that [State] is a key field and that [State]'s minor key field is the city.
NOTE: FILELOOKUP and the File SDb functions cannot be nested.


FILEMAX

Format: FILEMAX(field <, logical>)
Scope: Database
Returns: Numeric

FILEMAX returns the largest value in the specified field for all records in a view.

You can enter a logical expression as an optional second argument. Each record is evaluated to determine if it fits the condition specified in the logical expression. If the expression is true for a record, the record is included in the calculation. If the expression is false, the record is not included.

     FILEMAX([ytd])
     FILEMAX([ytd],[yr]>1987)

The first example returns the maximum value occurring in the [ytd] field. The second example computes maximum [ytd] value in records where field [yr] contains data greater than 1987.


FILEMIN

Format: FILEMIN(field <, logical>)
Scope: Database
Returns: Numeric

FILEMIN returns the smallest value in the specified field for all records in a view. Only non-blank fields are included in the calculation.

You can enter a logical expression as an optional second argument. Each record is evaluated to determine if it fits the condition specified in the logical expression. If the expression is true for a record, the record is included in the calculation. If the expression is false, the record is not included.

     FILEMIN([ytd])
     FILEMIN([ytd],[yr]>1987)

The first example returns the minimum value occurring in the [ytd] field. The second example computes minimum [ytd] value in records where field [yr] contains data greater than 1987.


FILEPROMPT

Format: FILEPROMPT(text,item list,numeric,numeric,numeric)
Scope: All
Returns: Text

This function calls the ANGOSS file prompter and returns a string representing one or more user-selected files. The arguments are as follows:

FILEPROMPT("prompt","extension",display default,display extensions,multi-file)

The first parameter is a text string used for the prompt. The second parameter is a space separated list of file name extensions (i.e.,"doc txt") that causes fileprompt to initially list only files with those extensions.

The remaining parameters are boolean. If display default is TRUE, [default] will appear as the upper left file (like the PRINT DOCUMENT file prompter). If display extensions is TRUE, file names are displayed with their extensions. If multi-file is TRUE, then users may select more than one file.

The following rules should be observed when using FILEPROMPT:

1) If [default] is selected, a string containing both square brackets ("[]") is returned.

2) The current directory is initially displayed, though users may move to an other directory.

3) If multiple files are selected by the user, the file names are returned in a space separated list.

4) If multiple files are selected from a different directory, only the first file name will contain the full path

5) All selected files must reside in the same directory.

6) Users may type a file that does not exist.

DIRPROMPT


FILESTD

Format: FILESTD(field <, logical>)
Scope: Database
Returns: Numeric

FILESTD computes the standard deviation of a population for the specified field for all records in a view. Only non-blank values are used in the calculation.

You can enter a logical expression as an optional second argument. Each record is evaluated to determine if it fits the condition specified in the logical expression. If the expression is true for a record, the record is included in the calculation. If the expression is false, the record is not included.

     FILESTD([ytd])
     FILESTD([ytd],[yr]>1978)

The first example computes the standard deviation of a population using all non-blank [ytd] values. The second example computes standard deviation of a population using all [ytd] values in records where [yr] is greater than 1987.


FILESTDEV

Format: FILESTDEV(field <, logical>)
Scope: Database
Returns: Numeric

FILESTDEV computes the standard deviation of a sample for the specified field for all records in a view. Only non-blank values are used in the calculation.

You can enter a logical expression as an optional second argument. Each record is evaluated to determine if it fits the condition specified in the logical expression. If the expression is true for a record, the record is included in the calculation. If the expression is false, the record is not included.

     FILESTDEV([ytd])
     FILESTDEV([ytd],[yr]>1978)

The first example computes the standard deviation of a sample using all non-blank [ytd] values. The second example computes standard deviation of a sample using all [ytd] values in records where [yr] is greater than 1987.


FILESUM

Format: FILESUM(field <, logical>)
Scope: Database
Returns: Numeric

FILESUM calculates the sum of values in the specified field for all records in a view.

You can enter a logical expression as an optional second argument. Each record is evaluated to determine if it fits the condition specified in the logical expression. If the expression is true for a record, the record is included in the calculation. If the expression is false, the record is not included.

     FILESUM([ytd])
     FILESUM([ytd],[yr]>1987)

The first example calculates the sum of values in [ytd]. The second example calculates the sum of values in [ytd] where [yr] is greater than 1987.
NOTE: FILESUM includes deleted records in its calculation. To prevent the use of deleted records, use a qualifier as the second argument, as shown in the following example.

     FILESUM([ytd],NOT(DELETED))


FILESUMSQ

Format: FILESUMSQ(field <, logical>)
Scope: Database
Returns: Numeric

The FILESUMSQ function computes the sum of the squares of the values for the specified field for all records in a view.

You can enter a logical expression as an optional second argument. Each record is evaluated to determine if it fits the condition specified in the logical expression. If the expression is true for a record, the record is included in the calculation. If the expression is false, the record is not included.

     FILESUMSQ([ytd])
     FILESUMSQ([ytd],[yr]=1987)

The first example computes the sum of the squares of all entries in [ytd]. The second example computes the sum of the squares of all entries in [ytd] where [yr] is equal to 1987.


FILEVAR

Format: FILEVAR(field <, logical>)
Scope: Database
Returns: Numeric

The FILEVAR function computes the sample variance of the values in the specified field for all records in a view.

You can enter a logical expression as an optional second argument. Each record is evaluated to determine if it fits the condition specified in the logical expression. If the expression is true for a record, the record is included in the calculation. If the expression is false, the record is not included.

     FILEVAR([ytd])
     FILEVAR([ytd],[month]>=7)

The first example computes the variance of all [ytd] values. The second example computes the variance for all [ytd] values in records where [month] is greater than or equal to 7.


FIND

Format: FIND( text, text, numeric )
Scope: All
Returns: Numeric

FIND returns a number representing the sequential character position at which a text item is found to begin within a larger text expression. For example, "str" begins at position 3 in "substring."

The arguments are used as follows:

     FIND ( search text, text expression, start value )

The first character in the text string is assigned a value of 0, the second character is assigned a value of 1, the third character a value of 2, and so forth.

The search begins at the position specified by the start value argument. If the search text is not found within the text string, or if the start value entered is at a character position beyond the occurrence of the search text, the result is Error 18 (Bad argument). Negative start values also yield Error 18.

In the first example, the cell r3c5 contains the text string "Sales Totals".

In the second example, the field [name1] contains the text string "Mr. and Mrs. Kempton." The result is the position of the second period (following "Mrs") because the search starts at position 4, past the first period.

The third example illustrates how the @MID function can be used with FIND to extract a text string when its starting position is located. The expression "913-492-3800" is contained in [phone].

FIND("ls",r3c5,0) | 11
FIND(".",[name1],4) | 11
@MID([phone],FIND("492",[phone], 0),8) | "492-3800"

@MID


FIXED

Format: FIXED( numeric, numeric )
Scope: All
Returns: Text

FIXED returns a text expression representing a number. The first argument is the number FIXED operates on. The second argument determines the number of decimal places in the text representation of the number.

FIXED(200.3648,3) | "200.365"
FIXED(1.9,2) | "1.90"

STR


FORMAT

Format: FORMAT( expression, text <, numeric> )
Scope: All
Returns: Text

FORMAT is a versatile function that allows you to specify the format, or appearance, of data in a variety of ways. FORMAT returns a text expression in which a data item is formatted according to a formatting specification. If a width is specified, the data is aligned within that width. The arguments are used as follows:

     FORMAT ( data item, format string <, width> )

The first argument, the data item to be formatted, can be either text or numeric. If it is numeric, FORMAT follows SmartWare's formatting conventions for numeric data. For example, if you specify currency format, the data is formatted according to the Currency symbol: and Currency symbol location: settings in the Global Preferences menu. If you specify a date format, the number is interpreted as a date expression type 2. If you specify a time format, any fractional part of the number is interpreted as an amount of elapsed time expressed as a fraction of the whole day.

If the first argument is text, FORMAT interprets the expression according to the data-type format code you specify. If you specify a date format, FORMAT interprets the text as a date expression (type 1 or 2). For date expressions type 1, FORMAT follows the Date style: setting in the Global Preferences menu to determine the order of numeric day, month and year values. If you specify a time format, FORMAT interprets the text as a time expression. If you specify one of the other data-type codes or if you specify a precision, FORMAT converts the text to a number. With no data type and no precision, FORMAT simply aligns and "pads" the text with blanks as specified in the format string.

The format string is a text expression consisting of one or more types of codes that specify the data format. Use of each type of code is optional, depending on the data being formatted and the result you want to obtain. Those that are used must be placed in the following order:

     <precision><alignment><width><options><data-type>
NOTE: The entire format string must be a single sequence of text characters with no intervening spaces.

Precision. A precision code is a number from 0 to 15 that indicates a fixed number of decimal places for numeric data. If no precision code and no data-type are specified, numeric data is returned in the "general" format (decimal precision matches the precision of the numeric value).

Alignment. The alignment code specifies the alignment of the data within a specified width. You can use the following alignment codes.

Code | Meaning
L | Left alignment
R | Right alignment
M | Center (middle) alignment

If no alignment is specified, FORMAT assumes left alignment. Alignment of data has no effect if the width is not specified.

Width. A width code is a number from 1 to 255 that specifies the length (number of characters) of the text expression that FORMAT returns. Space characters (or asterisks if the F option code is specified) are used to "pad" to the desired width that portion of the resulting text not occupied by the formatted data. If the data exceeds the specified width, a string of asterisks filling that width is returned. If no width is specified, FORMAT returns exactly the number of characters required to produce the desired format.
NOTE: Width can also be specified as a third argument to FORMAT. If this third argument is included, it takes precedence over any width specification in the format string. When specified as a third argument, the width can range from 1 to 511 characters.

Options. Option codes provide special formatting capabilities. You can use the following option codes:

Code | Meaning
F | Fill with asterisks (*)
Z | Blank if 0
P | Parentheses around negative numbers
B | "cr" following negative & "db" following positive numbers
C | "cr" following negative numbers
, | Thousands separator; you must also specify a precision with this code

The F option code causes the text returned to be padded to the specified width with asterisks. This option is useful for check amount protection. The F code has no effect if the width is not specified or if the width is less than or equal to the number of characters occupied by the data in the specified format.

The Z code returns a single space character if the data item is a numeric 0.

The P, B, and C codes provide various options for the treatment of negative numbers. FORMAT recognizes these codes only if you also specify a precision code or an appropriate data-type (i.e., $, %, or E).

Data-type. A data-type code specifies one of several data formats available in SmartWare. You can use the following data-type codes:

Code | Meaning
$ | Currency
% | Percent
E | Exponential notation
H | Histogram
D1 | Date1 format
D2 | Date2 format
D3 | Date3 format
T1 | 12-hour time format
T2 | 24-hour time format

You may also create your own date format by specifying a data-type code consisting of the capital letter D followed by a custom date mask including one or a combination of the following characters:

Code | Meaning
d | Numeric day (omits leading 0 on single digit)
dd | Numeric day (includes leading 0)
day | Text day name
m | Numeric month (omits leading 0 on single digit)
mm | Numeric month (includes leading 0)
mon | Text month (3-character abbreviation)
month | Text month name
yy | Numeric year (2-digit)
yyyy | Numeric year (4-digit)

You can include other characters, such as hyphens (-) and slashes (/), within a custom date mask. Such characters are placed literally in the text expression returned, producing the familiar punctuation in date formats. If you want to include a term that serves as a code (e.g., the word "Month"), or the numbers 1, 2, or 3, as literal characters in a custom date mask, you must precede them with the backslash (\) character.
NOTE: If you inadvertently enter more than one data-type code, FORMAT uses the last (rightmost) one in the format string.

The optional width argument is a number from 1 to 511 that indicates the number of characters in the formatted text expression returned by FORMAT. This width specification supersedes any width specified in the format string.

FORMAT(.1,"%") | "10%"
FORMAT(100,"R10") | " 100 "
FORMAT(100,"2R10B") | " 100.00db"
FORMAT("100","2M$F",12) | "**$100.00 **"
FORMAT("-100","0P") | "(100)"
FORMAT(1.634,"T2") | "15:12:58"
FORMAT("32694","Dd/m/yy") | "6/7/89"
FORMAT("07/06/89", "Dday month d, yyyy") | "Thursday July 6, 1989"
FORMAT("11/22/63", "D\Month: month") | "Month: November"
FORMAT(5,"H") | "+++++"


FV

Format: FV( numeric, numeric, numeric )
Scope: All
Returns: Numeric

FV calculates the future value of a current lump sum payment at a given interest rate over a specified period of time. The three arguments are used as follows:

     FV ( principal amount, term, interest rate )

FV(100,2,.12) 125.44

Example:

Using the values listed, if you invested $100 for a two-year term, compounded at an annual interest rate of 12%, the value of your original investment at the end of the 2 year term would be $125.44 ($100.00 + first year's 12% interest = $112.00; $112.00 + second year's 12% interest = $125.44).


FVA

Format: FVA( numeric, numeric, numeric )
Scope: All
Returns: Numeric

FVA calculates the future value of a stream of equal payments (an annuity) at a given interest rate over a specified period of time. The arguments are used as follows:

     FVA ( payment amount, term, interest rate )

FVA(250,12,.09) 5035.18

Example:

If you made an annual investment of $250 for a 12 year term, compounded at an annual interest rate of 9%, at the end of the 12 year term, your $3000 total investment would be worth $5035.18.


GETENV

Format: GETENV(text)
Scope: All
Returns: Text

GETENV searches the operating system environment for the specified environment variable name. The argument is a text expression representing the environment variable name.

If the variable is found, GETENV returns a text string associated with that variable. The text string may be a null (empty) string. If the variable is not found, GETENV returns numeric zero (0). The numeric zero allows you to test for whether the variable is found, as follows:

Example:

     LOCAL X
     X = GETENV("xyzzy")

     IF(ISNUMBER(X))
     MESSAGE "Variable not found"
     ELSE
        .
        .
        .
     END IF


GETFNAMES

Format: GETFNAMES(text, numeric )
Scope: All
Returns: Text

GETFNAMES returns a text expression consisting of a list of filenames separated by space characters. The first argument is a text expression representing the file specification of the files you want listed. You can use "wild card" characters, as in DOS. The second argument is a numeric expression: 0 causes GETFNAMES to return filenames only; any other number returns both filenames and their extensions.

The first two examples assume that expense.rdf and expense.ws are the only files in the current directory. The third example refers to a directory containing three worksheets beginning with the word "week." The last example assumes that the directory specified has two ".rdf" files.

GETFNAMES("*.rdf",0) | "expense"
GETFNAMES("expense.*",1) | "expense.ws expense.rdf"
GETFNAMES("week?.ws",1) | "week1.ws week2.ws week3.ws"
GETFNAMES("c:\prim\data\*.rdf",1) | "qtr1.rdf qtr2.rdf"

You can use the GROUP function to extract individual file names from the list.
NOTE: GETFNAME returns up to approximately 1,024 characters before truncating.

GROUP
CURRFILES
FILE


GETREG

Format: GETREG( register )
Scope: All
Returns: Numeric

GETREG returns the CPU register value from the last Interrupt or Farcall command. Use the register name indicated to specify the register. The following example returns the value in the AX register:

     GETREG(AX)

This function is designed for use with the SmartWare Programming Language's Interrupt and Farcall commands. Consult Project Processing Manual for details on using these commands.
NOTE: GETREG and the Interrupt command were designed for use in a DOS environment.

AX | BX
CX | DX
DI | SI
DS | ES
FLAGS

SETREG


GOAL

Format: GOAL( numeric, numeric, GUESS formula )
Scope: All
Returns: Numeric

GOAL attempts to find a value for a term in an equation that will make the equation true. You supply the equation, an initial estimated value, and a result. The arguments are used as follows:

     GOAL ( estimated value, desired result, formula using GUESS )

The first argument is an approximation of or "guess" at the value you think will solve the equation. This value is initially represented in the formula (the third argument) by the variable GUESS. The second argument is the result that should be obtained when the true result value is substituted for GUESS in the formula. The formula can be an algebraic expression and can use SmartWare functions.

Example:

To solve 270 = X^4 using 3 as an initial guess, the formula is:

     GOAL(3,270,GUESS^4)
NOTE: Remember to check the result GOAL returns by calculating the formula with that result entered as a constant.

The value 3 is substituted in the formula for the variable GUESS and the result of the equation is calculated. The result is compared with the desired result (given in the second argument). Based upon the difference between the actual and desired results, a new value is obtained for GUESS. This second value is substituted into the formula and a new result is calculated. The process is repeated until two successive results differ less than 1E-7 or the maximum of 20 iterations (recalculations) is reached.

When using GOAL you should keep the following in mind:
*** The initial guess should be as close as possible to the expected value, since the process ceases after a total of 20 iterations. If the initial guess is too far from the true value, the successive results will not converge before the maximum number of iterations is reached.
** If the values involved are extremely small or the initial guess is so far out of range as to result in an extremely small result, the difference between the actual and desired results may be less than 1E-7 and the calculation process will cease. In the first case you may need to multiply all values by a large constant (1,000; 1,000,000; etc.). In the second case, you should use a more reasonable initial guess.

GOAL(1,4,GUESS*GUESS) | 2
GOAL(--1,4,GUESS*GUESS) | --2
GOAL(3,270,GUESS^4) | 4.053600464
GOAL(500,5035.18,FVA(GUESS,12,.0 9)) | 250.000002512

The first and second examples show how the estimated value effects the result returned in formulas where more than one true result can be derived. The fourth example calculates the amount of the payments where the desired future value is 5035.18, 12 payments are to be made and the interest rate is 9%.


GROUP

Format: GROUP( text, numeric )
Scope: All
Returns: Text

GROUP returns a group of text characters occupying a particular position in a list. GROUP assumes that the first argument is a text expression listing a series of items separated by spaces. Each item can be one or more text characters, called a "group." The second argument is the position number of the group to be returned. If the position number specified is less than or greater than the number of groups, GROUP returns the null text character.

The second example assumes that the GETFNAMES expression returns the text "moe.doc larry.doc curly.doc".

GROUP("define edit undefine ",2) | "edit"
GROUP(GETFNAMES("*.doc",1),3) | "curly.doc"


GR_FOREGROUND GR_BACKGROUND

GR_LINETYPE GR_LINEWIDTH

GR_FILLTYPE GR_TEXTFONT

GR_TEXTHEIGHT

Format: GR_FOREGROUND
Scope: All
Returns: Numeric

These functions are used in a graphics environment and determine the current values for color, line type, line width, fill type, text font, and text height. The returned value is always numeric rather than the possible constant name. Refer to the GRAPHICS SET project processing commands.


GR_FILE

Format: GR_FILE
Scope: All
Returns: Text

This indicates the name of the file that the graphics device currently has open when GR_MODE returns 1 or 3 (CGM or BMP file).


GR_FONTOPEN

Format: GR_FONTOPEN( text, numeric, constant )
Scope: All
Returns: Numeric

This function requests the use of a font and returns an identifier that can be used from that point on.

     GR_FONTOPEN("type face",point size,attributes)

The parameter "type face" is a string, (e.g. helvetica) that names the font; "point size" is the size of the font (a point is 1/72 of an inch, not the number of pixels); "attrib" is a bit flag field indicating what attributes the font should have.

Legal attributes are:

fn_attr_bold
fn_attr_italic
fn_attr_prop

See also GR_FONTATTRIB.

Multiple attributes can be added together (such as fn_attr_bold + fn_attri_italic).

Example:

     #font_id = GR_FONTOPEN("helvetica",20,0)
     GRAPHICS SET TEXT-FONT #font_id


GR_FONTCLOSE

Format: GR_FONTCLOSE( font_id )
Scope: All
Returns: Nothing

This closes the given font and releases resources for other use.


GR_FONTATTRIB

Format: GR_FONTATTRIB( text, constant )
Scope: All
Returns: Numeric

This function returns whether an attribute is supported by a given font family.

     GR_FONTATTRIB( "type face", attribute )

1 fn_attr_bold | bold face
2 fn_attr_italic | italic
4 fn_attr_prop | proportional

The function returns 1 if the attribute is available or 0 if it is not available.


GR_FONTAVAILABLE

Format: GR_FONTAVAILABLE
Scope: All
Returns: Numeric

This returns the number of font families that are available. It is used in conjunction with GR_FONTFAMILY().


GR_FONTFAMILY

Format: GR_FONTFAMILY( index )
Scope: All
Returns: Numeric

This returns the family name of the font given by some index number. The index runs from 1 to gr_fontavailable.

NOTE: the order of the list is completely arbitrary.


GR_GETPIXEL

Formats:
GR_GETPIXEL( x, y )
GR_GETPIXEL( bmp_var, x, y )
Scope: All
Returns: Numeric

This function returns the color of pixel specified by x and y on the screen or specified bitmap. However, GR_GETPIXEL will only work on some graphics devices. Use GR_GETPIXEL after the following open commands:

     GRAPHICS OPEN SCREEN
     GRAPHICS OPEN BMP-FILE

When GRAPHICS OPEN CGM-FILE is used, GR_GETPIXEL will always return 0.

See also GR_SETPIXEL.


GR_MAPCOLOR

Format: GR_MAPCOLOR( color )
Scope: All
Returns: Numeric

GR_MAPCOLOR takes a color and maps it to the closest color being displayed.


GR_MODE

Format:GR_MODE
Scope: All
Returns: Numeric

This indicates the type of graphics device currently open.

Return values:

0 no graphics device open
1 CGM file
2 screen
3 BMP file


GR_RGBCOLOR

Format: GR_RGBCOLOR( red, green, blue )
Scope: All
Returns: Nothing

This creates a new color, where you specify the RGB values. All values are limited from 0.0 to 1.0


GR_SETPIXEL

Formats:
GR_SETPIXEL( x, y, color )
GR_SETPIXEL( bmp_var, x, y, color )
Scope: All
Returns: Numeric

This function sets the color of pixel specified by x and y on the screen or specified bitmap. However, GR_SETPIXEL will only work on some graphics devices. Use GR_GETPIXEL after the following open commands:

     GRAPHICS OPEN SCREEN
     GRAPHICS OPEN BMP-FILE

GR_SETPIXEL returns the color actually set on the screen or in the bitmap.

When GRAPHICS OPEN CGM-FILE is used, GR_SETPIXEL will always return 0.

See also GR_GETPIXEL.


GR_XDPI and GR_YDPI

Formats:
GR_XDPI
GR_YDPI
Scope: All
Returns: Numeric

These functions return an estimate of the dots per inch for the current graphics screen. It can be used so that graphics can be approximately the same physical size on many different graphic screens. These functions can also be used to convert font point sizes (which are 1/72 of an inch) to pixel coordinates.


GR_TEXTASCENT and GR_TEXTDESCENT

Format: GR_TEXTASCENT
Scope: All
Returns: Numeric

These functions are used in a graphics environment. GR_TEXTASCENT returns the distance from the baseline to the top of capital letters when text is drawn using the current text font and height. GR_TEXTDESCENT returns the distance from the baseline to the bottom of lowercase letters with descenders (like y and g) when text is drawn using the current text font and height. Refer to the GRAPHICS project processing commands.


GR_TEXT_WIDTH

Format: GR_TEXT_WIDTH
Scope: All
Returns: Numeric

This returns the width of the specified string when drawn using the current text font and height in a graphics environment. Refer to the GRAPHICS project processing commands.


GR_X1 GR_Y1

GR_X2 GR_Y2

Format: GR_X1
Scope: All
Returns: Numeric

These functions are used in a graphics environment. GR_X1 and GR_Y1 return the top left screen coordinate. GR_X2 and GR_Y2 return the bottom right screen coordinate. Refer to the GRAPHICS project processing commands.


HEX

Format: HEX( numeric )
Scope: All
Returns: Text

HEX returns a text expression representing the hexadecimal notation of the numeric argument. HEX can represent up to 32-bit numbers in hexadecimal format.

HEX(32767) | "7FFF"
HEX(16) | "10"


HLOOKUP

Format: HLOOKUP( expression, block <, numeric> )
Scope: Spreadsheet
Returns: Conditional

HLOOKUP searches a lookup table and returns data from a target cell in the table. A lookup table is a block of contiguous cells containing related data items. The top row usually contains information categorizing the data in the columns of the table. HLOOKUP searches the top row for a cell containing data matching the first argument. If a match is found, HLOOKUP returns the contents of a target cell in the same column.

The arguments of this function are used as follows:

     HLOOKUP ( search item, table block <, offset> )

The search item can be any valid numeric or text expression. The block can be any valid block name or reference. The block defines the lookup table. HLOOKUP searches for data identical to the search item in the first row of the block. If the data is found, the contents of a target cell in this "lookup column" are returned. If the data is not found, HLOOKUP returns an error.

If no offset is specified, the cell in the last row of the lookup column is the target cell. If you include an offset, that number specifies the number of rows down from top of the block to the target cell. The search row is considered row 0.


@HLOOKUP

Format: @HLOOKUP( expression, block <, numeric> )
Scope: Spreadsheet
Returns: Conditional

@HLOOKUP is similar to HLOOKUP, except that it searches the top row in the block for the cell containing the largest value less than or equal to the first expression. This function requires that data in the search row (the top row) be in ascending numeric order.

For example, assume that the search item is 250. Since 250 falls between 200 and 300, the column containing 200 in the search row is the lookup column.

HLOOKUP(200,r1:5c1:4,3) | 80.00
HLOOKUP(250,r1:5c1:4,3) | Error 8
@HLOOKUP(250,r1:5c1:4,3) | 80.00


HOUR

Format: HOUR( numeric )
Scope: All
Returns: Numeric

HOUR extracts the hour of the day from a decimal number representing the time of day as a fraction of the whole day, and returns a number between 0 (midnight) and 23 (23:00 or 11:00 p.m.). The fractional part of any number can be interpreted as a time of day and assigned a time value.

HOUR(.05) | 1
HOUR(0.99) | 23
HOUR(0.488136574074) | 11


HOURS

Format A: HOURS( time )
Format B: HOURS( date <, time> )
Scope: All
Returns: Numeric

If you use Format A, HOURS returns the number of hours elapsed between the time represented by the time expression and the beginning of the day (00:00:00).

If you use Format B, HOURS returns the number of hours elapsed between the date (and time, if included) and 00:00:00 on 1/1/00 (the beginning of the century).
NOTE: To find the hours elapsed between two times, subtract the value returned by HOURS for the earlier time from the value returned for the later time.

HOURS accepts only date expression types 1 and 2. Type 1 is a text expression representing a date. Type 2 is a numeric expression representing a number of days before or after the beginning of the current century.

HOURS("06:19:11a") | 6
HOURS("Jan 5, 1988") | 771504
HOURS("12/24/84","04:16:00") -- HOURS("12/23/84","22:00") | 6

Time Expressions


IF-THEN-ELSE

Format: IF logical THEN expression ELSE expression
Scope: All
Returns: Conditional

IF-THEN-ELSE is used to construct a logical formula that tests for a condition described by the logical expression. If the condition exists (the logical expression is true), the expression in the "then clause" is returned. If the logical expression is false, the expression in the "else clause" is returned.

IF-THEN-ELSE formulas can be nested by placing one in the else clause of another. You may use logical operators to join logical expressions to create a highly specific condition description. When formulas are nested, the first logical expression found to be true determines the result. Subsequent logical expressions, which may also be true, are ignored.

The following illustrate possible uses of the IF-THEN-ELSE formula in various applications.

Example:

     IF #POINTS >= 1000 THEN "Winner!" ELSE #POINTS + #BONUS

     IF SUM([12;15;19]) <> [20] THEN ERROR ELSE SUM([12;15;19])

     IF (r1c1 = 100) AND (r5c5 = 1000) OR (r2c1<1000)
         THEN (sum(r1c1:10))
         ELSE (sum(r11c1:10))

     #amount * (IF #amount < 1000 THEN .06
         ELSE IF #amount < 2000 THEN .07
         ELSE IF #amount < 3000 THEN .08
         ELSE IF #amount < 4000 THEN .09
         ELSE 1)

The first example formula returns the text expression "Winner!" if the variable #POINTS contains a value that is greater than or equal to 1000. Otherwise, it returns a value obtained by multiplying #POINTS times the variable #BONUS.

The second example formula returns Error 35 (generated by the function ERROR) if the sum of fields 12, 15, and 19 is not equal to the contents of field 20. Otherwise it returns the sum of fields 12, 15, and 19.

The third formula returns the sum of values in r1c1:10 if either of the following two conditions is true:
*** The cell r1c1 contains 100 and the cell r5c5 contains 1000.
** The cell r2c1 contains a value less than 1000.

Otherwise, the third example returns the sum of r11c1:10.

The fourth example returns a value calculated by multiplying the variable #amount by a multiplier obtained from an IF-THEN-ELSE formula. The IF-THEN-ELSE formula is calculated as follows:
1. If the variable #amount contains a value less than 1000, then the multiplier is 0.06.
2. If #amount contains a value greater than or equal to 1000 but less than 2000, then the multiplier is 0.07.
3. If #amount is greater than or equal to 2000 but less than 3000, then the multiplier is 0.08.
4. If #amount is greater than or equal to 3000 but less than 4000, then the multiplier is 0.09.
5. If #amount is greater than or equal to 4000, then the multiplier is 1.


@IF

Format: @IF( logical, expression, expression )
Scope: All
Returns: Conditional

If the logical expression is true, the first expression following the logical expression will be calculated and returned. If it is not true, the second expression will be calculated and returned.

The second example following assumes that #POINTS is greater than 100.

@IF(2*2>3,100,0) | 100
@IF(#POINTS>=100,"Winner!", #POINTS + #BONUS) | "Winner"


INCHAR

Format: INCHAR
Scope: All
Returns: Numeric

INCHAR returns the SmartWare key value of the next key pressed after it is calculated. Program execution pauses until a key is pressed. See also INEVENT.

INEVENT


INDEX

Format: INDEX( block , numeric, numeric )
Scope: Spreadsheet
Returns: Conditional

INDEX returns the contents of a cell whose position is determined by the arguments of the function:

     INDEX ( block reference, row offset, column offset )

INDEX provides a means of using a calculated cell reference. The location of the cell from which the data will be taken is calculated as an offset from the cell in the upper left corner of the block. The row offset is the number of rows below the top row in the block. The column offset is the number of columns to the right of the leftmost column in the block.

Examples for INDEX are provided with @INDEX.


@INDEX

Format: @INDEX( block, numeric, numeric )
Scope: Spreadsheet
Returns: Conditional

@INDEX returns the contents of a cell whose position is determined by the arguments of the function:

     @INDEX ( block reference, column offset, row offset )

@INDEX provides a means of using a calculated cell reference. The location of the cell from which the data will be taken is calculated as an offset from the cell in the upper left corner of the block. The column offset is the number of columns to the right of the leftmost column in the block (the leftmost column is numbered 0) and the row offset is the number of rows below the top row in the block (the top row is numbered 0).

If either argument is too large for the block, or if the argument is a negative value, the formula returns Error 32 (Cell out of range).

NOTE: While the @INDEX and INDEX functions return similar results, you cannot use them interchangeably. @INDEX's arguments must be specified in an order different from those of INDEX.
@INDEX(r1:6c1:6,4,4) | 816.53
@INDEX(r1:6c1:6,3,4) | 6118.97
INDEX(r1:6c1:6,3,4) | 911.84
INDEX(r1:6c1:6,2,5) | 538.16


INDIRECT

Format: INDIRECT( text )
Scope: All
Returns: Conditional

INDIRECT evaluates almost any valid expression. It is particularly useful for returning the contents of a cell or field whose location is specified in another cell or field. The argument, which must be text, can be in any of the following forms:
** A cell reference
** A field reference
** A public variable name
** The name of a user-defined project function that has been declared public
** A valid formula expression

INDIRECT cannot be used to evaluate local or global variables or non-public project functions.

The second example assumes r1c1 contains the value $125.00 and r2c2 contains the text entry "r1c1". The third example, which uses the INDIRECT function to calculate a cell reference with MAKECELL, assumes that cell r6c7 contains the cell reference r20c10 and that the cell r20c10 contains 13295.

INDIRECT("2*2") | 4
INDIRECT(r2c2) | 125.00
INDIRECT(MAKECELL(6,7)) | 13295


INEVENT

Format: INEVENT
Scope: All
Returns: Numeric

The INEVENT function is just like INCHAR except that INEVENT may also return new event constants. The following new constants can be returned by INEVENT:

LeftDown
RightDown
Middleman

LeftUp
RightUp
Middle

LeftDoubleDown
RightDoubleDown
MiddleDoubleDown

LeftDoubleUp
RightDoubleUp
MiddleDoubleUp

LeftHold - Acts like a repeating key.
RightHold
MiddleHold

MouseMoved - Only when a button is down.
MouseMovedNoButton - Only when a button is not down. You must use the SMARTPOKE function with the $_newevents option and a value of 1 to see this event.

WinResize - Window size has changed.
AppActivate - The application is now the active application. You must use the SMARTPOKE function with the $_newevents option and a value of 1 to see this event.
AppDeactivate - The application is being deactivated. You must use the SMARTPOKE function with the $_newevents option and a value of 1 to see this event.
WinFocus - The window is getting the focus. You must use the SMARTPOKE function with the $_newevents option and a value of 1 to see this event.
WinLostFocus - The window is losing the focus. You must use the SMARTPOKE function with the $_newevents option and a value of 1 to see this event.

EndUtterance - Occurs after last keystroke sent when the keystrokes are coming from a verbal utterance (DragonDictate 3.0 Only and Dependant on compatibility delay=0).

DdeAdvise - Server places this in the client's event queue when a specified item has changed.
DdeInitiate - Initiate notification to the server.
DdeRequest - Request notification to the server.
DdeTerminate - Terminate link notification to the server.
DdeUnadvise - Notification to the server that the client has removed an item's advisory status.

INCHAR


INT

Format: INT( numeric )
Scope: All
Returns: Numeric

INT returns the largest integer less than or equal to the value of the numeric expression.

INT(410.98) | 410
INT(--2.5) | --3

ROUND


@INT

Format: @INT( numeric )
Scope: All
Returns: Numeric

@INT, like INT, returns the integer value of a number. Unlike INT, @INT returns the next larger integer for negative numbers.

@INT(410.98) | 410
@INT(--2.5) | --2

ROUND


INTEREST

Format: INTEREST( numeric , numeric , numeric )
Scope: All
Returns: Numeric

INTEREST calculates the interest rate paid on a specified amount, given a fixed payment over a specified period of time. The arguments are used as follows:

     INTEREST ( principal amount, payment amount, term )

INTEREST(65988.40,7000,30) | .10
INTEREST(5000,175,36) | .013

Example:

If you financed a $5000 automobile for 36 months, with monthly payments of $175.00, your interest rate would be 15.6%. The formula for this calculation, INTEREST(5000,175,36), returns a result of 1.3%, which represents your monthly interest rate (based on your entry of the expressions in monthly increments: 36 monthly payments of $175 each). To calculate your yearly interest rate, you must multiply the monthly interest rate of 1.3% by 12 months to yield a 15.6% annual interest rate.
NOTE: To obtain accurate results with this function, you must use consistent increments of time in the formula. If the term is expressed as a monthly value, the payment must also be expressed as a monthly value. If you choose to express the term and payment as yearly values, you will receive a result which is based on only one payment being made annually, which yields a different result from a like formula based on monthly payments.

PRINCIPAL
PMT
TERM


INVERT

Format: INVERT( text )
Scope: Database
Returns: Text

INVERT returns the text expression with the last (rightmost) group of characters placed first (leftmost). A group is one or more text characters separated by spaces in a single text expression. INVERT is useful when you need to convert a name so that the last name comes first. SmartWare Database uses this method for sorting and performing comparisons on data in inverted name type fields.

The backslash (\) character forces the inversion to occur at a specific point in the text expression. In cases where the last group is not the group by which you want to sort (e.g., Tom Jones Jr.), you can insert the backslash to mark another position to be used for sorting purposes.

The following examples assume that [name] is an alphanumeric field, currently containing "James Kempton".

INVERT([name]) | "Kempton James"
INVERT("Fran~c,ois-Marie Arouet de Voltaire") | "Voltaire Fran~c,ois-Marie Arouet de"
INVERT("Tom \Jones Jr.") | "Jones Jr. \Tom"


IRR

Format: IRR( numeric, item list )
Scope: All
Returns: Numeric

IRR calculates an approximate internal rate of return for a sequence of regular payments. The internal rate of return is the discount rate at which the present value of a series of payments made at constant intervals equals the value of the investment. IRR finds an interest rate for which the net present value of a stream of payments equals 0. The arguments are used as follows:

     IRR ( 1st approximation, income flow .  .  .  )

IRR uses 20 iterations (20 subsequent recalculations) in order to produce the most accurate expression of the internal rate of return. The first approximation is used to calculate the first result. This result is then used in the second calculation. The second result is used in the third calculation, and so forth. An error message is issued if no convergence occurs in 20 iterations using the rate entered.

At least one number in the item list (usually the first) is negative, representing an outlay of funds. All empty cells/fields in a block referenced by the item list are interpreted as having a value of 0.
NOTE: Any worksheet blocks referenced in the item list must be one-dimensional (i.e., all cells lie in the same row or the same column).

In the following example, the block r1:11c2 contains -220000; 0; 25,000; 40,000; 40,000; 40,000; 40,000; 40,000; 40,000; 40,000; 40,000.

IRR(.10,r1:11c2) .0787

Example:

Suppose you are considering expanding your business by purchasing equipment at the cost of $220,000. By purchasing this equipment, you estimate that you will generate no additional business the first year, but the second year you estimate a return of $25,000. Returns of $40,000 per year are projected for the next eight years.

To calculate the internal rate of return on your investment over the next ten years, the formula would be IRR(.10,-220000, 0, 25000, 40000, 40000, 40000, 40000, 40000, 40000, 40000, 40000), which returns a result of 0.0787. The 10% figure at the beginning of the formula indicates an estimated 10% interest rate return. The $220,000 is entered as a negative number because it represents the initial cash outlay. The result translates into a 7.87% internal rate of return on your original investment over a 10 year term.

NPV
@NPV
PV


ISBLANK

Format: ISBLANK( expression )
Scope: Spreadsheet, Database
Returns: Numeric

ISBLANK returns TRUE (1) if the expression is blank or FALSE (0) if the expression is not blank. Normally, the argument should be a data reference.


ISCALC

Format: ISCALC
Scope: Spreadsheet
Returns: Numeric

ISCALC returns 1 (TRUE) if the current worksheet has been changed since the last recalculation or 0 (FALSE) if the current worksheet does not need to be recalculated.

In manual recalculation order, the Spreadsheet calculates and displays results only for newly entered and edited formulas. When you edit a worksheet or enter new cells, you must press the recalculation key to have the entire worksheet recalculated and the new results displayed. ISCALC returns 1 when you have made changes to a worksheet without recalculating. During iterative recalculation ISCALC returns FALSE after the first iteration.


ISDATE

Format: ISDATE("text" )
Scope: All
Returns: Numeric

The ISDATE function evaluates a string, and returns 1 (TRUE) if the entry is a date, or 0 (FALSE) if the entry is not a date. ISDATE accepts only date expressions type 1 and 2.

ISDATE("Jan 20, 1987") | 1
ISDATE("Jan Smith") | 0
ISDATE("01/01/87") | 1


ISERR

Format: ISERR( expression )
Scope: All
Returns: Numeric

ISERR returns 1 (TRUE) if the object referenced in the argument returns an error upon calculation. Normally, the argument is a data reference. The value of ISERR is 0 (FALSE) if there is no error in the object. ISERR can be used in a logical expression to determine if a formula error has occurred in a cell, field, or variable.

The example following assumes that r10c2 contains a formula that returns an error.

IF ISERR(r10c2) THEN "Oops" ELSE r10c2 "Oops"


ISNA

Format: ISNA( expression )
Scope: All
Returns: Numeric

ISNA returns 1 (TRUE) if the object specified in the argument returns N/A and 0 (FALSE) if it does not. The NA function is used in a formula to return the N/A (Not available) status. Normally, the argument is a data reference.


ISNUMBER

Format: ISNUMBER( expression )
Scope: All
Returns: Numeric

ISNUMBER returns 1 (TRUE) if the expression is a number or returns a number (value). If the expression is not a number ISNUMBER returns 0 (FALSE).

ISNUMBER(5) | 1
ISNUMBER("July") | 0


ISSTRING

Format: ISSTRING( expression )
Scope: All
Returns: Numeric

ISSTRING returns 1 (TRUE) if the expression is text or returns text. If the expression is not text ISSTRING returns 0 (FALSE).

ISSTRING(5) | 0
ISSTRING("July") | 1


ISVAR

Format: ISVAR( text )
Scope: All
Returns: Numeric

ISVAR evaluates the argument and returns TRUE (1) if it is the name of a public variable, or FALSE (0) if it is not the name of a public variable.

The following examples assume that #AMT1 has been declared a public variable and #AMOUNT has not.

ISVAR("#AMT1") | 1
ISVAR("#AMOUNT") | 0


KEYVALUE

Format: KEYVALUE( text )
Scope: All
Returns: Numeric

KEYVALUE returns the SmartWare key value of the key specified in the argument. The argument must be a SmartWare key term (i.e., an activity control term or character term used in macro definition or with the Keys project commands). If the argument does not contain a valid key term, KEYVALUE returns 0. Refer to Appendix B for a table of keys and their associated key terms.

KEYVALUE("F5") 319


LASTKEY_SOURCE and NEXTKEY_SOURCE

Format: LASTKEY_SOURCE
Scope: All
Returns: Numeric

These functions indicate the source of the last or next keystroke. They return an integer where:

1 = From keyboard
2 = From macro (quick keys)
3 = From voice (some voice recognition software only)
4 = From mouse
5 = From button

NEXTKEY


LEFT

Format: LEFT( text , numeric )
Scope: All
Returns: Text

LEFT returns a string of text characters from the text expression starting at the first character and including the number of characters specified in the numeric expression. The first (leftmost) character is at position 1.

LEFT("07/06/88",3) | "07/"
LEFT("James D. Kempton",5) | "James"

MID
RIGHT


LEN

Format: LEN( text )
Scope: All
Returns: Numeric

LEN returns the length (number of text characters) of the text expression. LEN counts all text characters, including spaces. LEN returns 0 if the expression is null or numeric.

LEN("1.1") | 3
LEN("sales totals") | 12
LEN(1.1) | 0


LERROR

Format: LERROR
Scope: All
Returns: Numeric

LERROR returns the numeric code of the last error that occurred, or 0 if no error has occurred during the current session. The numbers are the same as those returned by CERROR, which returns the number of the "current" error (i.e., the error resulting from the command just executed). The Clearerror project command resets LERROR to 0.

CERROR
ACTXERROR
ACTXERRORTEXT


LET

Format: <LET> expression = expression
Scope: All
Returns: Numeric

LET assigns the result of the second expression (right of the equal sign) to a target data reference specified in the first expression (left of the equal sign). LET then returns the value of the second expression.

LET is a tool for moving data from one place to another. LET allows you to store data in variables, array elements, cells, and fields; thus, the first expression must be one of these data references, appropriate to the module in which you are working.

In SmartWare's Project Development Language, you must first declare a variable before you can use LET to assign a value to it. Elsewhere, if the target is the name of a variable that does not exist, LET creates a new public variable to serve as the target.

Examples:

     LET #amount = 0
     LET $get_the_character = inchar
     LET r5c6 = (LET #subtotal = 60)

The first example formula stores the value 0 in the variable #amount and returns 0. The second example accepts the next keystroke, stores its SmartWare key value in the variable $get_the_character and returns that value. The third example assigns the value 60 to both the variable #subtotal and the cell r5c6. It also returns 60.
IMPORTANT: The use of LET within formulas to perform assignments involving cells and fields should be undertaken carefully. Several limitations on the use of this feature are described below.

LET formulas are designed to fail in cases where assignments may cause undesirable effects. Failure is usually signaled by an error condition. LET fails when you attempt to assign new contents to a Spreadsheet formula cell, except during project file execution. For example, you cannot use a LET formula in a cell to overwrite the cell itself (e.g., LET rc = 3) or another formula cell. This restriction also applies to user-defined functions executed from formula cells. Also, you cannot use LET to assign data to locked cells or read-only fields.

The results of LET formulas used with cells and calculated fields may depend on the recalculation order of the worksheet(s) or view(s) involved. These modules allow you to establish a calculation order for formulas referencing their data. However, because LET can alter data items while calculation is in progress, such applications of the function may have unexpected consequences.


LN

Format: LN( numeric )
Scope: All
Returns: Numeric

LN calculates the natural logarithm (base e) of the numeric expression. The numeric expression must be greater than 0.

LN(7) 1.94591014906


LOG10

Format: LOG10( numeric )
Scope: All
Returns: Numeric

LOG10 calculates the common logarithm (base 10) of the expression. The argument must be greater than 0.

LOG10(7) 0.84509804


LOGICAL

Format: LOGICAL( logical )
Scope: All
Returns: Numeric

LOGICAL evaluates the logical expression and returns 1 (TRUE) if the expression is true or 0 (FALSE) if the expression is false.

LOGICAL(2 > 1) | 1
LOGICAL(10 = 100) | 0


LOWER

Format: LOWER( text )
Scope: All
Returns: Text

LOWER returns the text expression with all characters converted to lower case.

LOWER("LOWER CASE") | "lower case"
LOWER("Toronto Ont.") | "toronto ont."

UPPER
PROPER
SWAPCASE


MAKEBLOCK

Format: MAKEBLOCK( numeric, numeric, numeric, numeric )
Scope: Spreadsheet
Returns: Text

MAKEBLOCK creates a string in the form of a block reference. This function is useful when you want to use a variable or calculated block reference.

Specifically, MAKEBLOCK returns a text string in the format "rW:XcY:Z", where W and X are row numbers, and Y and Z are column numbers. The arguments are used as follows:

     MAKEBLOCK ( row #1, row #2, column #1, column #2 )

In the second example, the current row is assumed to be 4 and the current column is 6.

MAKEBLOCK(1,2,5,6) | "r1:2c5:6"
MAKEBLOCK(ROW,ROW + 1,COLUMN,COLUMN + 3) | "r4:5c6:9"

COLUMN
ROW


MAKECELL

Format: MAKECELL( numeric, numeric )
Scope: Spreadsheet
Returns: Text

MAKECELL is used to create a string in the form of a cell reference. This function is useful when you wish to use a variable or calculated cell reference.

Specifically, MAKECELL returns a text string in the format "rXcY" where X is a row number and Y is a column number. The arguments are used as follows:

     MAKECELL ( row number, column number )

In the following examples, the current row is 3 and the project variable #STATE equals 11.

MAKECELL(1,2) | "r1c2"
MAKECELL(ROW,#STATE + 1) | "r3c12"

COLUMN
ROW
MAKEBLOCK


MATCH

Format: MATCH( text, text <, numeric> )
Scope: All
Returns: Numeric

MATCH searches the first expression for the string of characters specified in the second expression. The arguments are used as follows:

     MATCH ( text searched in, text searched for <, starting position> )

If a match is found, MATCH returns the number of the position where the first character of the second expression occurs in the first expression. If the starting position is included, MATCH will start searching at the character position corresponding to that number, starting at position 0. If no match is found, MATCH returns 0.

MATCH("(913) 555-2089","555") | 7
MATCH("Mississippi","iss",4) | 5


MAX

Format: MAX( item list )
Scope: All
Returns: Numeric

MAX returns the value of the largest numeric item in the item list. Text items and blanks are ignored.

MAX(1,3,32,12,6,17,19) | 32
MAX(4,"A",5,3*2,10/2) | 6
MAX(--4,0) | 0


MEMLEFT

Format: MEMLEFT
Scope: All
Returns: Numeric

MEMLEFT returns the amount, in bytes, of available memory remaining in the system.
NOTE: This function was designed for use in a DOS environment.


MID

Format: MID( text, numeric <, numeric> )
Scope: All
Returns: Text

MID returns the character or set of characters beginning at a specified position within a string of text. The arguments are used as follows:

     MID ( text, starting position <, length> )

The first character in the text is located at position 1. If the length is specified, MID returns that number of characters, beginning with the character at the starting position and extending to the right. If no length is specified, MID returns the character at the starting position and all characters to the right.

You may think of MID as copying characters from the text. The first numeric expression determines where the copy begins. The second numeric expression limits the number of characters copied from the text.

MID("(913) 555-1089",7) | "555-1089"
MID("Overland Park",5,4) | "land"

LEFT
RIGHT


@MID

Format: @MID( text, numeric, numeric )
Scope: All
Returns: Text

@MID returns the character or set of characters beginning at a specified position within a string of text. The arguments are used as follows:

     @MID ( text, starting position, length )

The first character in the text is located at position 0, the second at position 1, and so forth. You can specify a length value that exceeds the length of the text if you want to return the entire remainder of the text. If the length you specify is larger than the remaining characters in the text string, the extra length has no effect on the result returned.

If you enter a start value that is beyond the length of the text string, a null string (0 characters) is returned. A length value of 0 also returns a null string.

The LEFT and RIGHT functions may be used in conjunction with @MID to extract characters from either end of a text string.

NOTE: While the @MID and MID functions return similar results, you cannot use them interchangeably. MID allows you to eliminate the length argument; @MID requires that all three arguments be entered. Also, MID assigns a value of 1 to the first character in the text string, while @MID assigns a value of 0 to the first character in the text string.
@MID("0123456789",0,5) | "01234"
@MID("0123456789abc",10,2) | "ab"

LEFT
RIGHT


MIN

Format: MIN( item list )
Scope: All
Returns: Numeric

MIN returns the value of the smallest numeric item in the item list. Any text items or blanks in the list are ignored.

MIN(3,32,12,600,1,17,19) | 1
MIN(4,"A",5,3*2,10/2) | 4


MINUTE

Format: MINUTE( numeric )
Scope: All
Returns: Numeric

MINUTE extracts the minute from a time decimal number, such as that returned by @TIME, and returns a numeric value between 0 and 59. The fractional part of any number can be interpreted as a time of day and assigned a time decimal number.

MINUTE(0.4881365740) | 42
MINUTE(0.92190972) | 07
MINUTE(3/25) | 52


MINUTES

Format A: MINUTES( time )
Format B: MINUTES( date <, time> )
Scope: All
Returns: Numeric

If you use Format A, MINUTES returns the number of minutes elapsed between the time represented by the time expression and the beginning of the day (00:00:00).

If you use Format B, MINUTES returns the number of minutes elapsed between the date (and time, if included) and 00:00:00 on 01/01/1900 (the beginning of the 20th century).
NOTE: You can use MINUTES to determine the number of minutes elapsed between two times. Subtract the value returned by the function for the earlier time from the value returned for the later time.

MINUTES accepts only date expression types 1 and 2. Type 1 is a text expression representing a date. Type 2 is a numeric expression representing a number of days before or after the beginning of the current century.

MINUTES("06:19:11a") | 379
MINUTES("July 6, 1988") | 46553760

Date Expressions
Time Expressions


MOD

Format: MOD( numeric, numeric )
Scope: All
Returns: Numeric

MOD returns the integer value of the remainder when the first argument is divided by the second argument. If the second argument is 0, MOD returns the first argument.

MOD(22,6) 4


MNU_CLOSE

Format: MNU_CLOSE( numeric )
Scope: All
Returns: nothing

This function removes a menu from memory. Its only parameter is the menu handle identifying the menu being closed.


MNU_DELCH

Format: MNU_DELCH( numeric, numeric )
Scope: All
Returns: nothing

This function is used to delete a choice from a menu. If the choice referred to is a sub menu, then all choices on that sub menu are also deleted. The format of MNU_DELCH is:

     MNU_DELCH( menu, choice_# )

where menu is the menu handle returned by MNU_OPEN. The choice number identifies which choice is being deleted.


MNU_DELLANG

Format: MNU_DELLANG( numeric, num/txt )
Scope: All
Returns: nothing

The MNU_DELLANG function is used to remove all information pertaining to the identified language. The arguments are:

     MNU_DELLANG(menu,language)

where menu is the menu handle returned by MNU_OPEN. The language can be a number or language id text string.


MNU_DELLUM

Format: MNU_DELUM( numeric, num/txt )
Scope: All
Returns: nothing

The MNU_DELUM function is used to remove all information pertaining to the identified usermode. The arguments are:

     MNU_DELUM(menu,usermode)

where menu is the menu handle returned by MNU_OPEN. The language can be a number or usermode id text string.


MNU_INFO

Format: MNU_INFO( numeric, numeric, num/txt, num/txt, constant, num/txt)
Scope: All
Returns: Numeric or string

The MNU_INFO function is used for reading information from the menu structure or for changing information. The format is:

     MNU_INFO(menu,choice,usermode,language,constant,<new val>)

menu

The menu is the menu handle which is returned by the MNU_OPEN function.

choice

The choice is the choice number that you want to read. The first choice of a menu is number 1. If the information you are reading or changing is not related to a choice, then this parameter is ignored. Normally, the choice number will only operate on one level therefore to read choices on sub menus you must get the sub menu's handle (MNU_CH_MENU) first.

The meaning of choice can be changed with MNU_ORDINAL_REF. If MNU_ORDINAL_REF is set to true, then the referenced choice (and menu) is calculated by the number of terminal nodes encountered in a recursive scan. This allows any terminal choice within the menu hierarchy to be accessed. The following chart shows a sample menu with the ordinal reference numbers in brackets.

File Edit Help(8)
Open (1) Copy (4)
Print (2) Paste (5)
Exit (3) Delete (6)
Move (7)

The same menu without MNU_ORDINAL_REF set (which is the default) would be numbered:

File(1) Edit(2) Help(3)
Open (1) Copy (1)
Print (2) Paste (2)
Exit (3) Delete (3)
Move (4)

usermode

The usermode is a number or string. It is used if the field you are accessing is indexed by usermode. If the field is not index by usermode, it is ignored.

language

This argument is also a number or string. It is used if the field you are accessing is indexed by language. If the field is not index by language, it is ignored.

constant

The constant indicates what data item you are reading or changing.

new val

If a sixth parameter is included, its value is assigned to the identified field. If it is not present, the operation is considered to be read only. Note that is you are changing a value, then the old value is returned.


MNU_INSCH

Format: MNU_INSCH( numeric, numeric, text, constant, numeric )
Scope: All
Returns: numeric (TRUE for success, FALSE fail)

MNU_INSCH is used to add a choice to a menu in memory. The arguments are as follows:

     MNU_INSCH(menu,position,description,type,key/sub menu)

menu

Is a menu handle as returned by MNU_OPEN.

position

Is the position in the menu that the new choice will occupy. One (1) is the first choice.

description

Is the text that will be displayed when the menu is shown to the user. The DEFAULT language is assumed.

constant

The constant is either MNU_SUB_MENU or MNU_CHOICE and indicates whether the choice being created is a terminal node (MNU_CHOICE) or leads to a sub menu (MNU_SUB_MENU).

key/sub menu

If the type is MNU_CHOICE, then the last parameter is the event that will occur when the end user selects the choice. This often {MenuSelect} which is a general event meaning that a menu item was selected. It can also be a keystroke, such as {F10}, {Alt-C} etc.

If the type is MNU_SUB_MENU, then the last parameter is the menu handle, created with MNU_OPEN(#), that will be appended to the menu structure as a sub menu.

Examples

The following code segment creates a menu and sub menu with one choice on it, displays it to the user, and prints the choice description when selected.

     main
     local #mnu #sub_mnu #sel_mnu #sel_ch
         #mnu = mnu_open("") ' CREATE AN EMPTY MENU IN-MEMORY
         if #mnu=0
            message "Out of memory allocating new menu."
            exit main
         end if
         ' ALLOCATE A SUB MENU AS A CHILD OF #mnu
         #sub_mnu = mnu_open(#mnu)
         if #sub_mnu=0
            message "Out of memory allocating new menu."
            exit main
         end if
         ' ATTACH SUB MENU NAMED "File"
         mnu_insch(#mnu,1,"File",MNU_SUB_MENU,#sub_mnu)
         ' CREATE A CHOICE CALLED TEST ON MENU "File"
         mnu_insch(#sub_mnu,1,"Test",MNU_CHOICE,{MenuSelect})
         pulldown init #mnu "DEV" "DEFAULT"
         ' DISPLAY MENU IN PULLDOWN FORMAT
         while true
            case inevent ' WAIT FOR AN EVENT
            when {MenuSelect} ' MENU ITEM SELECTED
               ' DETERMINE MENU AND CHOICE # SELECTED
               #sel_mnu = eventinfo(m_mnu_id)
               #sel_ch=mnu_info(#sel_mnu,1,1,1,MNU_USER_SELECT)
               ' DISPLAY DESC OF SELECTED CHOICE
               message mnu_info(#sel_mnu,#sel_ch,1,1,MNU_DESC)
            when {Esc}
               exit while ' END TEST
            end case
         end while
         mnu_close(#mnu) ' FREE MEMORY USED BY MENU
     end main


MNU_INSLANG

Format: MNU_INSLANG( numeric, numeric, text )
Scope: All
Returns numeric (TRUE for success, FALSE fail)

This function adds a language to the specified menu. The arguments for MNU_INSLANG are:

     MNU_INSLANG(menu,position,language id)

Menu is the menu handle as returned by MNU_OPEN. The position is the ordinal number which the new language will occupy. The language id is a text string (maximum eight characters) that will identify the language. See MNU_INFO for a table of which data elements are indexed by language.


MNU_INSUM

Format: MNU_INSUM( numeric, numeric, text )
Scope: All
Returns numeric (TRUE for success, FALSE fail)

This function adds a usermode to the specified menu. The arguments for MNU_INSUM are:

MNU_INSUM(menu,position,usermode id)

As with all MNU_ functions, menu is the menu handle as returned by MNU_OPEN. The usermode id is a text string (maximum eight characters) that will identify the usermode. See MNU_INFO for a table of which data elements are indexed by usermode.

mnu_delch | Deletes a choice
mnu_dellang | Deletes a language
mnu_delum | Deletes a usermode
mnu_write | Saves a menu to disk
mnu_close | Release memory used by a menu


MNU_OPEN

Format: MNU_OPEN( text <,text> <,text> )
Scope: All
Returns: numeric (menu handle)

MNU_OPEN has three distinct forms:

     MNU_OPEN("")

Creates a new menu in memory

     MNU_OPEN(#handle)

Creates a new sub menu where the parent menu is #handle

     MNU_OPEN("file",["usermode"],["language"])

Reads a menu from disk. If a usermode or language is specified only information pertaining to them is loaded. If no usermode or language is specified all are loaded.

MNU_OPEN returns a menu handle (a number greater than 0) if it is successful. The menu handle is used by all other menu functions to identify the menu. If MNU_OPEN fails 0 is returned.

When a menu is created with MNU_OPEN("") the usermode "DEV" and language "DEFAULT" are automatically inserted.


MNU_WRITE

Format: MNU_WRITE( numeric, text, constant )
Scope: All
Returns: numeric (true success,false fail)

The MNU_WRITE function is used to write a menu structure to disk. The arguments are:

     MNU_WRITE(menu,file name,file type)

where menu is the menu handle as returned by MNU_OPEN. The file type must be the constant MNU_ASCII or MNU_BINARY. The ascii format is human readable, but takes a longer time to open. The binary format is not human readable.


MONTH

Format: MONTH( date )
Scope: All
Returns: Numeric

MONTH returns a number corresponding to the month of the year in the date expression.

MONTH("September 15, 1988") 9.0

Date Expressions


MONTHNAME

Format: MONTHNAME( date )
Scope: All
Returns: Text

MONTHNAME returns the name of the month in the date expression.

MONTHNAME("09-15-88") | "September"
MONTHNAME(19180) | "July"


N

Format: N( block )
Scope: Spreadsheet
Returns: Numeric

N returns the value in the cell in the upper left corner of the block referenced in the argument. If the contents of that cell is text, N returns 0.

Although N returns the result of a single cell, the argument specified must be in the form of a block reference. You can use the ! character at the beginning of a cell reference to force SmartWare to interpret it as a block reference.

In the following examples, the value in cell r6c4 assumed to be $255.19.

N(r6:15c4:5) | $255.19
N(!r6c4) | $255.19


MOUSEINFO

Format: MOUSEINFO( constant <,numeric> )
Scope: All
Returns: Numeric

This function returns, and sometimes changes, information about the current mouse status. The first parameter is a named constant indicating the value read or changed.

The arguments are as follows:

MOUSEINFO( constant, new value )

If the second parameter is used to change the mouse status, MOUSEINFO returns the original setting for subsequent restoration. Note that only some values can be changed, see the table below:

# Constant | Description
0 m_buttons | Bits indicating which buttons are pressed (see the table below). This is an alternative to using MOUSEINFO with the following six button constants.
1 m_leftup | Indicates the left button is not held down
2 m_leftdown | Indicates the left button is held down
3 m_rightup | Indicates the right button is not held down
4 m_rightdown | Indicates the right button is held down
5 m_middleup | Indicates the middle button is not held down
6 m_middledown | Indicates the middle button is held down
7 m_row | Row of pointer
8 m_col | Column of pointer
9 m_x | x coordinate pixel of pointer
10 m_y | y coordinate pixel of pointer
12 m_active | Mouse active (Read/Write)
13 m_nobuttons | Number of buttons
14 m_cursoron | Mouse cursor shown (Read/Write)
15 m_keyright | Value of right mouse button (Read/Write)

MOUSEINFO( m_buttons ) will return one of the following values:

0000001 - Left button down
0000010 - Left button up
0000100 - Middle button down
0001000 - Middle button up
0010000 - Right button up
0100000 - Right button down
1000000 - Double button

Example:

     WHILE TRUE
        if MOUSEINFO(m_leftdown)
           SCREEN PRINT 1 1 15 0 "Left Mouse Down"
        ELSEIF MOUSEINFO(m_leftup)
           SCREEN PRINT 1 1 15 0 "Left Mouse Up"
        ELSEIF MOUSEINFO(m_rightdown)
           SCREEN PRINT 2 1 15 0 "Right Mouse Down"
        ELSEIF MOUSEINFO(m_rightup)
           SCREEN PRINT 2 1 15 0 "Right Mouse Up"
        END IF
        SCREEN PRINT 3 1 15 0 "Mouse row ="&str(mousinfo(m_row))
        SCREEN PRINT 4 1 15 0 "Mouse col ="&str(mousinfo(m_col))
        IF NEXTKEY>0 AND INCHAR={esc}
           EXIT WHILE
        END IF
     END WHILE

CLICKINFO


NA

Format: NA
Scope: All
Returns: Text

NA returns the message N/A (Not available). NA is often used during worksheet development to indicate that some information has not yet been entered or determined. Formulas referencing a cell returning NA also return NA. Thus, NA allows you to indicate when not all data upon which a result is dependent are available.


NEXTKEY

Format: NEXTKEY
Scope: All
Returns: Numeric

NEXTKEY returns the SmartWare key value of the next keystroke waiting in the keyboard buffer, or 0 if no key has been pressed. Unlike INCHAR, NEXTKEY does not remove this character from the buffer. Program execution does not pause when NEXTKEY is calculated.

INCHAR
NEXTKEY_SOURCE


NOCHANGE

Format: NOCHANGE
Scope: All
Returns: Conditional

NOCHANGE is often used in logical formulas to retain the current contents of a data reference. NOCHANGE provides that no change is made to the data.

For example, you can use NOCHANGE to create a formula that causes data to be entered into a data-file field only if the field currently has no data in it. The following example stores a record's date of initial entry but provides that field will not be altered when the record is updated.

Example:

The formula IF [Datefield] = BLANK THEN TODAY ELSE NOCHANGE returns today's date if no date has yet been entered for field 3. Otherwise, it makes no change to the data in the field.


NORMAL

Format: NORMAL( numeric )
Scope: All
Returns: Numeric

NORMAL returns a number randomly selected from a normal distribution. The numeric expression specifies the standard deviation of the distribution.


NOW

Format: NOW
Scope: All
Returns: Numeric

NOW returns a decimal number (integer and fraction) which represents the current date and time. The whole number returned identifies the date as the number of days from the start of the century to the current date. The fraction returned identifies the time of day as a fraction of the 24-hour day.

NOW uses the operating system's current date and time values. The accuracy of the result is based on whether the correct date and time were entered into the system when it was started. SmartWare automatically updates NOW formulas whenever recalculations are performed.

In the following example, the current date and time are 10:06 a.m., October 6, 1988.

NOW 32421.42


NPV

Format: NPV( numeric , item list )
Scope: All
Returns: Numeric

NPV (net present value) calculates the present value of a group of future returns, discounted at a specified rate, and reduced by the amount of the initial investment. "Net present value" is often used to project whether a proposed investment will return not only the initial investment and the projected cash flow requirements, but additional funds as well.

NPV is calculated from the beginning of the time periods, rather than the end. The arguments are used as follows:

     NPV ( interest rate, cash flow )

If the item list is defined as a worksheet block reference, the block must be one-dimensional (i.e., all cells in a single row or a single column).
NOTE: Empty cells/fields in a block referenced by the item list are interpreted as 0.

NPV(.11,r3:6c2) | 106.00
NPV(.11,r3:6c3 | 945.70
NPV(.11,r3:6c4) | --751.39

Example:

Suppose that you are selecting an investment from three possible plans. All three plans require the same initial $17,000 investment, and all three return the same total cash flow. The annual cash flows from the first plan are equal. Cash flows from the second plan are larger in the earlier years and become smaller. The third plan's cash flows are small at the beginning and grow larger.

Based upon the results of the formulas (and assuming all other considerations are equal), the second plan appears to be the best choice because it produces the largest net present value. The first plan produces a smaller but still positive net present value, while the third plan results in a negative net present value.


@NPV

Format: @NPV( numeric, item list )
Scope: All
Returns: Numeric

@NPV is used to calculate net present value using a formula slightly different from NPV. @NPV assumes that each return is calculated and received at the end of each time period.

The arguments for @NPV are:

     @NPV( interest rate, cash flow)

If the item list is defined as a block reference, the block must be one-dimensional, i.e., a single row or a single column.

@NPV(.11,r4:6c2) | 17,106.00
@NPV(.11,r4:6c3) | 17,945.70
@NPV(.11,r4:6c4) | 16,248.61

As in the example for NPV, suppose that you are selecting an investment from three possible plans. All three plans require the same $17,000 investment, and all three return the same total cash flow. The annual cash flows from the first plan are equal. Cash flows from the second plan are larger in the earlier years and become smaller. The third plan's cash flows are small at the beginning and grow larger.

Since @NPV by itself does not return net present value, you must insert an additional calculation into the formula. To obtain net present value using @NPV, reduce the amount returned by the amount of the initial investment.

@NPV(.11,r4:6c2)+r3c2 | 106.00
@NPV(.11,r4:6c3)+r3c3 | 945.70
@NPV(.11,r4:6c4)+r3c4 | --751.39

Based upon the results of the adjusted formulas, you can then determine which investment provides the greatest positive net present value.


NULL

Format: NULL
Scope: All
Returns: Text

NULL returns the null text character, ASCII character number 0. NULL is sometimes described as the "empty string." NULL is not equal to a space character (ASCII 32) or to the numeric value 0, nor are blank objects necessarily equal to NULL.
NOTE: Another way of specifying NULL is to type "", two double quotes with no intervening space (e.g., $var = "" is the same as $var = NULL.


OFFSETOF

Format: OFFSETOF(pointer)
Scope: All
Returns: Numeric

OFFSETOF extracts the offset portion of a real or virtual pointer. The argument is the passed address. This function is equivalent to the following formula:

     OFFSETOF(pointer) == BITAND(pointer, 0xFFFF)

SEGMENTOF


OLDKEY

Format: OLDKEY( numeric )
Scope: All
Returns: Numeric

OLDKEY returns a numeric key code equivalent to that returned for a particular key in SmartWare 3.10. The argument should be a SmartWare numeric key value, such as that returned by INCHAR, NEXTKEY, and KEYVALUE.

In SmartWare the values of some keys and key combinations have changed from SmartWare 3.10. Changes to key values fall into three categories. For keys whose old value was below 32, the SmartWare value equals the old value plus 736. Keys whose old value was between 32 and 255 have the same value in SmartWare. For keys whose value was greater than 255, the SmartWare value equals 256 plus the old value divided by 256.

The main purpose of OLDKEY is to allow you to update project files created under SmartWare 3.10 with a minimum of alteration. If your projects contain lines comparing the value of keys typed against specific constant values, you may wish to use OLDKEY to convert the input to SmartWare 3.10's value so that you do not have to revise the constants.

For example, if your project contains the statement LET $X = INCHAR, followed by a series of IF statements testing for particular key values in $X, you may want to revise the line as follows: LET $X = OLDKEY(INCHAR). With this change, subsequent lines should not have to be changed to reflect the new SmartWare key values.

INCHAR
NEXTKEY


PATH

Format: PATH( numeric )
Scope: All
Returns: Text

PATH returns the path requested in the argument, as specified with a named constant, as follows:

     PATH(datapath)

Named constants include the following:

DATAPATH | SYSPATH
PAGEPATH | NOPATH
HOMEPATH | DEFPATH
CMDPATH | CURPATH

DATAPATH. The data path is the path currently used for all data files. The current data path is set by the Tools New-Directory command. The default data path is established in the Tools Preferences menus.

SYSPATH. The system path is the path where the SmartWare program files, such as SMART.AIF, are located. The system path is the directory where SmartWare was installed, thus it does not change.

PAGEPATH. The paging path is the path where a temporary file is written if SmartWare has to overflow to disk. The paging path can be set or changed with the Tools Preferences Global command.

NOPATH. Nopath always returns null text. Specifying nopath allows SmartWare to use the default path for any particular file operation.

HOMEPATH. The home path is the user's home directory. Under DOS, homepath is the same as curpath.

DEFPATH. The default path is the data path for the Main Menu. It is also used by the SmartWare modules if no other path has been set using a module's Tools Preferences command. When SmartWare is first invoked, defpath refers to the current directory, unless it is set otherwise by the -D switch on the command line or specified with Tools Preferences Global.

CMDPATH. The command path is set by the -D command line switch.

CURPATH. The current path refers to the directory SmartWare is in when invoking SmartWare. It may be used for some temporary files under DOS. It is also used (the same as defpath) if no other data path is specified by -D or the Preferences commands.


PHONEX

Format: PHONEX( text )
Scope: All
Returns: Numeric

PHONEX evaluates a text expression and returns a number representing its sound when pronounced. In general, words that sound the same are likely to return equal or similar values.

In the following example, "Coal" and "Cole" are pronounced identically and PHONEX returns the same number for each.

PHONEX("Coal") = PHONEX("Cole") 1

PHONEX is useful for locating a name when you know the pronunciation but are uncertain of the exact spelling. For example, you might use the following formula in a database query:

     PHONEX([lastname]) > PHONEX("mark") -- 20 and PHONEX([lastname]) < PHONEX("mark") + 20

Since the word "mark" has a PHONEX value of 14224, this query formula selects names with values in a range from 14204 (14224--20) to 14244 (14224+20). The name "Markley," having a value of 14228, is selected, while the name "Manning," having the value 14186, is not.
NOTE: Experiment with various numeric ranges until you become familiar with the results returned by PHONEX. Words that you pronounce identically may not yield the same PHONEX value.


PI

Format: PI
Scope: All
Returns: Numeric

PI returns the value of pi (3.14159265358979).


PMT

Format: PMT( numeric, numeric, numeric )
Scope: All
Returns: Numeric

PMT calculates the payment required over a given term at a fixed interest rate to equal the specified principal amount. The arguments are used as follows:

     PMT ( principal amount, term, interest rate )

PMT(65988.40,30,.1) | 7000.00
PMT(5000,36,.18/12) | 180.76

Example:

If you financed a $5000 automobile for 36 months at an annual interest rate of 18%, your monthly payment would be $180.76. The formula for this calculation is PMT(5000,36,.18/12), with the 18% annual interest rate being divided by 12 months to maintain the consistency of monthly increments in the formula.
NOTE: The interest rate is expressed as the rate per term. The term may be any unit of measure (month, week, year, etc.). To calculate the monthly payment given an annual interest rate use:

     PMT ( principal, number of months, annual interest rate divided by 12 )


@PMT

Format: @PMT( numeric, numeric, numeric )
Scope: All
Returns: Numeric

@PMT calculates the payment required over a given term at a fixed interest rate to equal the specified principal amount. @PMT returns the same value as PMT, but the arguments are entered in a different order. The arguments are used as follows:

     @PMT ( principal amount, interest rate, term )

NOTE: The interest rate is expressed as the rate per term. The term may be any unit of measure (month, week, year, etc.). To calculate the monthly payment given an annual interest rate use:
@PMT(65988.40,.1,30) | 7000.00
@PMT(5000,.18/12,36) | 180.76

     @PMT ( principal, annual interest rate divided by 12, number of months )


POINTEROF

Format: POINTEROF(segment, offset)
Scope: All
Returns: Numeric

POINTEROF creates and returns a pointer from a passed segment and offset. This function is equivalent to the following formula:

     POINTEROF(segment, offset) == (segment * 65536) + offset

OFFSETOF
SEGMENTOF


POWER

Format: POWER( numeric, numeric )
Scope: All
Returns: Numeric

POWER raises the value of the first expression to the power represented by the value of the second expression. Using a fractional power results in a root. If the power includes a fraction, the first expression must be an integer.
NOTE: You may also use the ^ operator to raise a number to a power (eg., 10^2 = 100).

POWER(10,2) | 100
POWER(100,.5) | 10


PRECORD

Format: PRECORD
Scope: Database
Returns: Numeric

PRECORD returns the physical record number of the current record in the main data-file of the view. The physical record number is the absolute number of the record in the sequential order in which it was entered.


PRECORDS

Format: PRECORDS
Scope: Database
Returns: Numeric

PRECORDS returns the total number of records contained in the main data-file of the view.


PRINCIPAL

Format: PRINCIPAL( numeric, numeric, numeric )
Scope: All
Returns: Numeric

PRINCIPAL calculates the principal amount which would produce a fixed, regular payment over a given term at a specified interest rate. The arguments are used as follows:

     PRINCIPAL( payment amount, term, interest rate )

PRINCIPAL(7000,30,.1) | 65988.40
PRINCIPAL(150,36,.18/12) | 4149.10

Example:

If you made monthly payments of $150 for a term of 36 months at an annual interest rate of 18%, the principal amount that you would have paid at the end of the 36 month term would be $4149.10. The formula for this calculation is PRINCIPAL(150,36,.18/12), with the 18% annual interest rate being divided by 12 months to maintain the consistency of monthly increments in the formula.

INTEREST
PMT
TERM


PROCESS_CREATE

Format: PROCESS_CREATE( text, <, text, ...> )
Scope: All
Returns: Numeric

PROCESS_CREATE executes an external program. The first parameter is the full path of the program (including the program name), the remaining optional parameters are command line arguments to the executing program. All parameters must be strings.

For example, the following function will start the Windows Paintbrush utility from an SPL program. Because Paintbrush can take a bitmap file as a command line parameter, this function call will load the cars.bmp file into Paintbrush as well.

     PROCESS_CREATE("c:\windows\pbrush","c:\windows\cars.bmp")

If the function is successful, PROCESS_CREATE will return a process number otherwise, -1 is returned. For 16 bit applications in Win32S, 0 always indicates a successful return. Note that, under Unix, a process number will probably be returned regardless of success.

CREATE_OBJECT


PROPER

Format: PROPER( text )
Scope: All
Returns: Text

PROPER converts each word in the text expression so that the first letter of the word is capitalized and the rest of the word is in lower case characters.

PROPER("jamEs d. kemPtOn") "James D. Kempton"

UPPER
LOWER
SWAPCASE


PV

Format: PV( numeric, numeric, numeric )
Scope: All
Returns: Numeric

PV calculates the present value today of a future lump sum payment at a given interest rate. The arguments are used as follows:

     PV( principal amount, term, interest rate )

PV(5000,5,.1) 3104.61

Example:

Suppose you were given the option of receiving a lump sum payment today on an investment asset in lieu of receiving a specified rate of interest over a specified term with the lump sum payment being made at the end of the term. To determine what the amount of the lump sum payment today should be, you would use a PV formula. Using the values listed above, if you were to receive 10% annual interest for five years, with a lump sum payment of $5000 being made to you at the end of the five years, the formula to determine the current value of the $5000 would be PV(5000,5,.1). The result of $3104.61 is the amount you should receive if you elect to take the lump sum payment today.

PVA
@NPV


@PV

Format: @PV( numeric, numeric, numeric )
Scope: All
Returns: Numeric

@PV calculates the present value today of a stream of equal payments (an annuity) at a given interest rate over a specified period of time. @PV returns the same value as PVA, but the arguments are entered in a different order. The arguments are used as follows:

     @PV( payment amount, interest rate, term )

@PV(5000,.12,10) 28251.12


PVA

Format: PVA( numeric, numeric, numeric )
Scope: All
Returns: Numeric

PVA calculates the present value today of a stream of equal payments (an annuity) at a given interest rate over a specified period of time. The arguments are used as follows:

     PVA( payment amount, term, interest rate )

PVA(5000,10,.12) 28251.12

Example:

Suppose you were given the option of receiving a lump sum payment today on an investment asset in lieu of receiving scheduled equal payments at a specified interest rate for a specified period of time. To determine what the present value of the investment asset would be, you would use PVA. For instance, if you were to receive annual payments of $5000 for a term of ten years, with an annual interest rate of 12%, the formula to determine the present value would be PVA(5000,10,.12). The result of $28,251.12 would be the lump sum payment you should accept today in lieu of accepting the annuity payments.


RAND

Format: RAND
Scope: All
Returns: Numeric

RAND returns a number selected randomly from between 0 and 1. RAND is equivalent to UNIFORM(1).
NOTE: Each of SmartWare's random number functions, EXPONENTIAL, NORMAL, RAND, and UNIFORM, returns numbers from a different distribution.

UNIFORM
EXPONENTIAL
NORMAL


RATE

Format: RATE( numeric, numeric, numeric )
Scope: All
Returns: Numeric

RATE returns the periodic interest rate for an investment, based on the arguments of the formula:

     RATE( future value, present value, term )

The rate returned represents the interest rate for the period specified, not necessarily an annual interest rate. If the interest is compounded quarterly, for example, the value returned must be multiplied by four to compute the annual rate.

RATE(20000,5000,10*12) | 0.011619
RATE(20000,5000,10*4) | 0.035265

Example:

Suppose you invested $5000 in an IRA that matures in 10 years with a value of $20,000. In the first formula above, you are seeking a monthly interest rate return (indicated by the 10 year term being multiplied by 12 months), with the result being 1.16%. In the second formula, you are seeking a quarterly interest rate return (indicated by the 10 year term being multiplied by 4 quarters), with the result being 3.53%.


READPTR

Format: READPTR( pointer <,index> <,index> <,index> )
Scope: All
Returns: Conditional

If the pointer passed to READPTR is the address of a variable, the value of that variable is returned. With an array, the address plus the index arguments (one for each dimension) are used to return the value of a specific element.

     $value = READPTR( VP_variable )
     $element = READPTR( AP_array, 3 )

ARRAYPTR
VARPTR


RECORD

Format: RECORD
Scope: Database
Returns: Numeric

RECORD returns the logical record number of the current record. If the file is in index order, the logical record number will usually differ from the physical record number. If the file is in key order, RECORD returns the physical record number.

PRECORD


RECORDS

Format: RECORDS
Scope: Database
Returns: Numeric

RECORDS returns the total number of logical records in the file for the current order of the file. If the file is in an index order, the number of logical records may be smaller than the number of physical records.

PRECORDS


REPEAT

Format: REPEAT( text, numeric )
Scope: All
Returns: Text

REPEAT returns the text expression repeated the number of times indicated in the numeric expression. The maximum length of the resulting expression is 1000 characters.

REPEAT("*",5) | "*****"
REPEAT("+--",5) | "+--+--+--+--+--"


REPLACE

Format: REPLACE( text , numeric, numeric, text )
Scope: All
Returns: Text

REPLACE removes a specified number of characters from an existing text string and replaces those characters with new text, as determined by the arguments of the function:

     REPLACE( existing text, start value, length value, new text )

REPLACE deletes the number of characters specified as the length, starting with the character at the starting position, and replaces these characters with the new text. The first character is located at position 0. If you specify a start position that is greater than the number of existing text characters, the new text will be added to the end of the existing text, as illustrated in the third example following.

In the first three examples, r7c2 contains the text string "The difference is speed." In the fourth example, r4c1 contains the text string "The difference is either power or speed."

REPLACE(r7c2,18,5,"power") | "The difference is power."
REPLACE(r7c2,15,2,"should be") | "The difference should be speed."
REPLACE("The difference is speed.",14,21,"s are speed and power.") | "The differences are speed and power."
REPLACE(r4c1,18,16,"") | "The difference is speed."


REPLACESTR

Format: REPLACESTR( text, text, text )
Scope: All
Returns: Text

This function performs a `find and replace' on the passed string (parameter 1). All occurrences of the find string (parameter 2) are replaced with the replacement string (parameter 3). The following example sets $str to "1B3B1":

$str = replacestr( "12321", "2", "B" )


RIGHT

Format: RIGHT( text, numeric )
Scope: All
Returns: Text

RIGHT returns a line of text characters from the text expression consisting of the rightmost number of characters specified by the numeric expression.

RIGHT("Sept 15, 1989",4) | "1989"
RIGHT("James D. Kempton",3) | "ton"

MID
LEFT


ROUND

Format: ROUND( numeric, numeric )
Scope: All
Returns: Numeric

ROUND returns the value of the first numeric expression rounded to the number of decimal places specified in the second argument. If the second argument is negative, the number is rounded to that power of ten.

ROUND(1.1234567,5) | 1.12346
ROUND(32.55,1) | 32.6
ROUND(1959.8,-2) | 2000

INT


ROW

Format: ROW
Scope: Spreadsheet
Returns: Numeric

ROW returns the integer number of the worksheet row in which the formula containing the function is located.

COLUMN


ROWS

Format: ROWS( block )
Scope: Spreadsheet
Returns: Numeric

ROWS returns a number equivalent to the number of rows in a worksheet block.

ROWS(r23:109c2:4) | 87
ROWS(!r2c2) | 1

COLS


S

Format: S( block )
Scope: Spreadsheet
Returns: Text

S returns the text contents of the cell in the upper left corner of the block referenced in the argument. If that cell contains a numeric value, S returns NULL.
NOTE: SmartWare interprets a reference to a single cell as a block reference if you precede it with the ! character.

In the following examples, SM is a named cell at r10c1 containing the text "Toronto".

S(r10:15c1:3) | "Toronto"
S(!SM) | "Toronto"

INDIRECT


SCRCOLUMN SCRHEIGHT SCRLINE SCRMODE SCRWIDTH

Format: SCRCOLUMN
Scope: All
Returns: Numeric

These functions return information about the screen and the location of data printed on the screen by the Message and Screen Print project commands. With these functions you can quickly calculate locations for printing data on the screen through project processing.

SCRCOLUMN returns the number of the column following the last (rightmost) character printed on the screen. SCRLINE returns the line number of the last character printed on the screen. These functions are affected only by the Message and Screen Print commands.

SCRHEIGHT returns the screen height in lines. SCRWIDTH returns the screen width in columns. SCRMODE returns 1 for a graphics display mode or 0 for a character-based display mode.

The following examples assume the use of an IBM CGA display adapter in character mode.

SCRHEIGHT | 25
SCRWIDTH | 80


SCR_TEXT

Format: SCR_TEXT( row, col, length )
Scope: All
Returns: Text

This returns the string of characters found on the screen at the specified row, column, and maximum length. Trailing spaces are trimmed.


SECOND

Format: SECOND( numeric )
Scope: All
Returns: Numeric

SECOND extracts the second from a time decimal number, such as that generated by @TIME, and returns a numeric value between 0 and 59. The fractional portion of any number can be interpreted as a time of day and assigned a time decimal number.

SECOND(0.488136574074) | 55
SECOND(0.921909722222) | 33
SECOND(3/25) | 48


SECONDS

Format A: SECONDS( time )
Format B: SECONDS( date <, time> )
Scope: All
Returns: Numeric

If you use Format A, SECONDS returns the number of seconds elapsed between the time represented by the time expression and the beginning of the day (00:00:00).

If you use Format B, SECONDS returns the number of seconds elapsed between the date (and time, if included) and 00:00:00 on 01/01/00 (the beginning of the 20th century).

SECONDS("06:19:11a") | 22751
SECONDS("Feb 22, 1988", "11:55:23") | 2781604523

SECONDS accepts only date expression types 1 and 2. Type 1 is a text expression representing a date. Type 2 is a numeric expression representing the number of days before or after the beginning of the century.

Date Expressions
Time Expression


SEGMENTOF

Format: SEGMENTOF(pointer)
Scope: All
Returns: Numeric

SEGMENTOF extracts the segment portion of a real or virtual pointer. The argument is the passed address. This function is equivalent to the following formula:

     SEGMENTOF(pointer) == BITAND(pointer/65536, 0xFFFF)

OFFSETOF
POINTEROF


SELECT

Format: SELECT( select list ) ELSE expression
Scope: All
Returns: Conditional

SELECT creates a special type of logical formula which provides for a set of possible responses to a list of specified conditions.

The select list consists of pairs of expressions separated by a comma and enclosed in parentheses. Each pair contains a logical expression to be evaluated and an item to be returned if the logical expression it is paired with is the first in the list to be found true. You may include an ELSE statement in the formula to provide a response if none of the logical expressions in the select list are true. SELECT returns an error when no ELSE statement is included and none of the logical expressions are true.

In the following example the field [Qty] is assumed to contain 75.

SELECT([Qty]<50,0)([Qty]<100,.05) ([Qty]<500,.1) ([Qty]<1000,.25) ELSE ERROR .05

The function proceeds through the select list and returns the item paired with the first logical expression which is evaluated as true. Subsequent logical expressions in the list, which may also be true, are ignored.

A SELECT formula is a special type of IF-THEN-ELSE statement. The following example shows how the SELECT formula would look if written as an IF-THEN-ELSE formula:

     IF [Qty] < 50 THEN 0
        ELSE IF [Qty] < 100 THEN .05
        ELSE IF [Qty] < 500 THEN .1
        ELSE IF [Qty] < 1000 THEN .25
        ELSE ERROR

IF-THEN-ELSE
CASE


SETREG

Format: SETREG( numeric, numeric expression )
Scope: All
Returns: Numeric

The SETREG function presets values to be loaded into CPU registers prior to an Interrupt command. The first argument is a register name indicated below. The second argument is the value to be placed in the register. The following example sets the segment address of the variable #var1 as the value to be loaded in the AX register by the next Interrupt command.

     SETREG(AX,DOSSEG(#var1))

This function is designed for use with the Project Development Language's Interrupt command. Consult Project Processing for details on using the Interrupt command.
NOTE: SETREG and the Interrupt command were designed for use in a DOS environment.

AX | BX
CX | DX
DI | SI
DS | ES
FLAGS |

GETREG


SIN

Format: SIN( numeric )
Scope: All
Returns: Numeric

SIN calculates the sine of the numeric expression. The numeric expression is a value expressed in radians.

SIN(0.1) .0998334166468


SINH

Format: SINH( numeric )
Scope: All
Returns: Numeric

SINH calculates the hyperbolic sine of the numeric expression.

SINH(0.1) .1001667500198


SLN

Format: SLN( numeric, numeric, numeric )
Scope: All
Returns: Numeric

SLN computes the straight-line yearly depreciation of an asset. The arguments are used as follows:

     SLN( cost, salvage value, life )

SLN(10000,1000,7) 1285.71

Example:

To determine the annual depreciation expense of a $10,000 automobile which has a useful life of seven years and a salvage value of $1000 at the end of the seven years, the formula is SLN(10000,1000,7). The result, $1285.71, is the uniform depreciation expense for each of the seven years during which the car is depreciated.

DDB
SYD


SQRT

Format: SQRT( numeric )
Scope: All
Returns: Numeric

SQRT calculates the square root of the numeric expression. The numeric expression must be greater than or equal to 0.
NOTE: To obtain roots other than the square root, use the function POWER with a fractional second argument.

SQRT(100) 10

POWER


SSGET

Format: SSGET( <text,> numeric, numeric )
Scope: Spreadsheet
Returns: Conditional

SSGET returns the result stored in a cell. The data retrieved is from the current worksheet unless another worksheet is specified in the optional first argument. The arguments are used as follows:

     SSGET( <worksheet name,> row number, column number)

The example shown assumes that r4c1 contains the value 12.

SSGET(4,1) 12

SSGET is one means of creating a "calculated" cell reference because its arguments can be formulas returning the numbers of a target row and column. It is primarily intended for use in project processing for applications other than user-defined functions. Because SSGET is not encompassed in the natural or minimal worksheet recalculation orders, its use in formula cells and user-defined formula functions is not recommended. Another method of using a calculated cell reference is to use a MAKECELL formula as an argument for INDIRECT.


SSPOS

Format: SSPOS( numeric, numeric)
Scope: Spreadsheet
Returns: Text

SSPOS returns the worksheet name and cell that occupies the passed screen coordinates in the form of a string:

<work sheet>.r<row>c<col> (e.g., "mysheet.r51c313"). The arguments are as follows

SSPOS( row, column )

Example:

     $d = SSPOS(CLICKINFO(m_row), CLICKINFO(m_col))
     message "The data you clicked on is: "|CELLTEXT($d)

Note that if the screen coordinates supplied are on a border, status line, or other non worksheet locations, a null string ("") is returned.


SSPOSROW and SSPOSCOL

Format: SSPOSROW( numeric, numeric)
Scope: Spreadsheet
Returns: Numeric

The SSPOSROW and SSPOSCOL functions return an integer representing the worksheet row or worksheet column that occupies the passed screen coordinates. The arguments are as follows:

SSPOSROW( row, column ) and SSPOSCOL( row, column )

Example 1:

     `Put "Hello" into the `clicked' cell
     $ws = SSPOSWS( CLICKINFO(m_row), CLICKINFO(m_col) )
     #r = SSPOSROW( CLICKINFO(m_row), CLICKINFO(m_col) )
     #c = SSPOSCOL( CLICKINFO(m_row), CLICKINFO(m_col) )
     IF #r > 0 `Check if user clicked a cell
        SSPUT( "Hello", $ws, #r, #c )
     END IF

Example 2:

     'Calculate the top displayed row of the worksheet assuming
     'the border and numbers are on.
     #r = SSPOSROW(3,5)
     MESSAGE "The first row displayed is row # "|str(#r)

Note that if the screen coordinates supplied are on a border, status line, or other non worksheet location, 0 is returned.


SSPOSWS

Format: SSPOSWS( numeric, numeric)
Scope: Spreadsheet
Returns: Text

SSPOSWS returns a string containing the worksheet name that occupies the passed screen coordinates. The arguments are as follows:

SSPOSWS( row, column )

Note that if the screen coordinates supplied are on a border, status line, or other non worksheet locations, a null string ("") is returned.


SSPUT

Format: SSPUT( expression, <text,> numeric, numeric)
Scope: Spreadsheet
Returns: Numeric

SSPUT places the data returned by the first expression into a cell identified in the remaining arguments, returning TRUE (1) if the procedure is successful or FALSE (0) if the procedure is not successful. SSPUT operates on the current worksheet unless the name of another active worksheet is specified. The arguments are used as follows:

     SSPUT(data, <worksheet name,> row number, column number)

SSPUT fails (and returns 0) if you attempt an assignment to a locked cell or a cell containing a formula. If the expression results in an error or in NA, the result is entered into the cell as text.
IMPORTANT: Use of SSPUT in formula cells is subject to limitations similar to those described for LET. See the paragraph marked IMPORTANT under LET for more information.


STD

Format: STD( item list )
Scope: All
Returns: Numeric

STD calculates the standard deviation of a population for the items in the item list. Text items are considered to have a value of 0. Blanks are ignored. The list must contain at least 2 entries.

STD returns a value equivalent to the square root of the variance as calculated by the @VAR function.

STD(4.5,6.7,27.2,32.4) 12.2635639192


STDEV

Format: STDEV( item list )
Scope: All
Returns: Numeric

STDEV calculates the standard deviation of a sample for the numeric items in the item list. All text items or blanks in the list are ignored. The list must contain at least 1 entry.

STDEV returns a value equivalent to the square root of the variance as calculated by the VAR function.

STDEV(4.5,6.7,27.2,32.4) 14.1607438599


STR

Format: STR( expression <, numeric> )
Scope: All
Returns: Text

STR returns a text representation of the numeric expression in the first argument. The number of decimal places represented is the same as that of the numeric expression. The optional second argument allows you to specify the number of significant digits to be returned. Nonsignificant trailing zeros are omitted. STR converts the number to E-notation when it would exceed 15 places to the left or right of the decimal. If the expression is already text, it is returned unchanged.

STR(11.2300349) | "11.2300349"
STR(.68100,2) | "0.68"

FIXED


SUM

Format: SUM( item list )
Scope: All
Returns: Numeric

SUM calculates the sum of the numeric items in the item list. Any text items or blanks in the list are ignored.

SUM(2,2) | 4
SUM(1,3,5,7,9,9) | 34
SUM(2+2,"18",3*7,3^2) | 34


SUMSQ

Format: SUMSQ( item list )
Scope: All
Returns: Numeric

SUMSQ calculates the sum of the squares of the numeric items in the item list. Any text items or blanks in the list are ignored.

SUMSQ(2,3,10) 113


SWAPCASE

Format: SWAPCASE( text )
Scope: All
Returns: Text

SWAPCASE will swap the case of each character in the argument. Upper case characters will be converted to lower case and lower case characters will be converted to upper case.

SWAPCASE("Swap Case") | "sWAP cASE"
SWAPCASE("Toronto") | "tORONTO"

UPPER
LOWER
PROPER


SYD

Format: SYD( numeric, numeric, numeric, numeric )
Scope: All
Returns: Numeric

SYD calculates depreciation using the sum-of-the-years' digits method. The depreciation value is determined by the arguments of the function:

     SYD( cost value, salvage value, useful life, term )

This function computes depreciation at an accelerated rate, whereby a greater depreciation expense occurs early in the term. The depreciable cost is the actual cost less the salvage value. The useful life is the term over which the asset is depreciated.

SYD(15000,2000,7,1) | 3250
SYD(15000,2000,7,3) | 2321.43
SYD(15000,2000,7,6) | 928.57

Example:

Suppose you purchase a $15,000 automobile which has a useful life of seven years and a salvage value of $2000 at the end of the seven years. The first formula listed above is used to determine what the depreciation rate would be for the first year of the car's useful life and returns a result of $3250.00. The second formula computes the depreciation rate for the third year of the car's useful life and returns a result of $2321.43. The third formula returns a result of $928.57, indicating the depreciation rate for the sixth year of the car's useful life.

DDB
SLN


SYSVAR

Format: SYSVAR( constant <,value> )
Scope: All
Returns: Original value

The SYSVAR function will read and/or change internal system variables. Essentially, it is a convenient way of issuing SMARTPEEK and SMARTPOKE statements. The first parameter specifies the system variable to inspect or change. The second parameter, which is optional and only allowed in some cases, is the new value to assign. For a detailed listing of constants, refer to the documentation on SMARTPEEK and SMARTPOKE.

Example 1:

     `Store current value of INSERT and set it to 0
     #ins = SYSVAR($_ins,0)
     `Commands that require INSERT to be off
     `Restore original INSERT value
     SYSVAR($_ins,#ins)

Example 2:

     `Remember repaint mode
     #rep = SYSVAR($_paint)
     REPAINT OFF
     `Commands the require repaint off
     `Put repaint on, (if it was off)
     IF #rep
        REPAINT ON
     END IF

SMARTPEEK


TABLEAVERAGE

Format: TABLEAVERAGE( field <, logical> )
Scope: Database
Returns: Numeric

TABLEAVERAGE computes the average value in the specified field for all table records in a view record. The field must be in a table in the view in which it is referenced. Only non-blank fields are included in the calculation.

You can enter a logical expression as an optional second argument. Each table record for which the expression returns TRUE is included in the calculation.

     TABLEAVERAGE([price])
     TABLEAVERAGE([price], [quantity] > 10)

The first example computes the average of all non-blank values in the table's [price] field. The second example computes the average of all the table's [price] values in records where another table field, [quantity], is greater than 10.


TABLECOUNT

Format: TABLECOUNT( field <, logical> )
Scope: Database
Returns: Numeric

TABLECOUNT counts the number of (non-blank) entries in the specified field for all table records in a view record. The field must be in a table in the view in which it is referenced.

You can enter a logical expression as an optional second argument. Each table record for which the expression returns TRUE is included in the calculation.

     TABLECOUNT([price])
     TABLECOUNT([price], [quantity] > 10)

The first example returns the count of entries in the table's [price] field. The second example returns the count of the table's [price] entries in records where another table field, [quantity], is greater than 10.


TABLELOOKUP

Format: TABLELOOKUP( field, logical )
Scope: Database
Returns: Conditional

TABLELOOKUP returns the contents of a specified field in a table. The field must be in a table in the view in which it is referenced. The arguments are used as follows:

     TABLELOOKUP(result field, selection criterion)

TABLELOOKUP searches the table beginning with the first record. It returns the contents of the result field in the first record it encounters where the selection criterion evaluates to a non-zero value.

The TABLELOOKUP examples are based on the following data. The column headings are the field titles and each row represents a table record.

Fund | Return | Shares
Money Market | 11.36 | 850
Kempton Mutual | 10.92 | 1000
Canadian Superior Fund | 10.12 | 5000
Hazel Group Securities | 10.30 | 1000

The first formula returns the value in [Return] from the record containing "Money Market" in [Fund]. The second example returns the contents of [Fund] for the first table record containing a value greater than or equal to 1000 in [Shares].

NOTE: TABLELOOKUP and the Table SDb functions cannot be nested.
TABLELOOKUP([Return], [Fund] = "Money Market") | 11.36
TABLELOOKUP([Fund], [Shares] >= 1000) | "Kempton Mutual"

Example:

If your view contains a table, you may want to select records based upon data in the table. When you base a query upon table data matching the selection conditions you have specified, if a match is found, all of the table records associated with a particular view record are returned, not just the table records that contain matching data.

In the following query example, SmartWare is instructed to search the table records for values greater than 100 in a table field titled [quantity]:

     Invoice            Quantity         Unit Price     Total
                            >100

To enter a full formula expression selecting records from a table, enter an expression using the TABLELOOKUP function in conjunction with the NOT and ISERR functions. The first argument for TABLELOOKUP, in this example, is any field in the table; the second argument is the selection equation, as follows:

     NOT(ISERR(TABLELOOKUP([quantity],[quantity]>100)))
NOTE: If this formula cannot find a value greater than 100 in the table during a query, it will fail. The NOT and ISERR functions are included to handle the resulting error message.


TABLEMAX

Format: TABLEMAX( field <, logical> )
Scope: Database
Returns: Numeric

TABLEMAX returns the largest value in the specified field for all table records in a view record. The field must be in a table in the view in which it is referenced.

You can enter a logical expression as an optional second argument. Each table record for which the expression returns TRUE is included in the calculation.

     TABLEMAX([price])
     TABLEMAX([price], [quantity] > 10)

The first example returns the maximum value in the table's [price] field. The second example returns the maximum value in the table's [price] field from among records where another table field, [quantity], is greater than 10.


TABLEMIN

Format: TABLEMIN( field <, logical> )
Scope: Database
Returns: Numeric

TABLEMIN returns the smallest value in the specified field for all table records in a view record. The field must be in a table in the view in which it is referenced.

You can enter a logical expression as an optional second argument. Each table record for which the expression returns TRUE is included in the calculation.

     TABLEMIN([price])
     TABLEMIN([price], [quantity] > 10)

The first example returns the minimum value in the table's [price] field. The second example returns the minimum value in the table's [price] field from among records where another table field, [quantity], is greater than 10.


TABLEREC

Format: TABLEREC( field )
Scope: Database
Returns: Numeric

The TABLEREC function returns the relative position of the current table record. The argument must be a text expression in the form of a field reference to a field in the table. The first record displayed in the table has position one, the second record has position two, etc.


TABLESTD

Format: TABLESTD( field <, logical> )
Scope: Database
Returns: Numeric

TABLESTD computes the standard deviation of a population for all table records in a view record. The field must be in a table in the view in which it is referenced. Only non-blank fields are included in the calculation.

You can enter a logical expression as an optional second argument. Each table record for which the expression returns TRUE is included in the calculation.

     TABLESTD([scores])
     TABLESTD([scores], [age] > 18)

The first example computes the standard deviation of a population for all non-blank values in the table's [scores] field. The second example computes the standard deviation of the table's [scores] field in records where another table field, [age], is greater than eighteen.


TABLESTDEV

Format: TABLESTDEV( field <, logical> )
Scope: Database
Returns: Numeric

TABLESTDEV computes the standard deviation of a sample for all table records in a view record. The field must be in a table in the view in which it is referenced. Only non-blank fields are included in the calculation.

You can enter a logical expression as an optional second argument. Each table record for which the expression returns TRUE is included in the calculation.

     TABLESTDEV([scores])
     TABLESTDEV([scores], [age] > 18)

The first example computes the standard deviation of a sample for all non-blank values in the table's [scores] field. The second example computes the standard deviation of the table's [scores] field in records where another table field, [age], is greater than eighteen.


TABLESUM

Format: TABLESUM( field <, logical> )
Scope: Database
Returns: Numeric

TABLESUM returns the sum of the values in the specified field for all table records in a view record. The field must be in a table in the view in which it is referenced.

You can enter a logical expression as an optional second argument. Each table record for which the expression returns TRUE is included in the calculation.

     TABLESUM([price])
     TABLESUM([price], [quantity] > 10)

The first example returns the sum of all values in the table's [price] field. The second example returns the sum of all the table's [price] values in records where another table field, [quantity], is greater than 10.
NOTE: TABLESUM does not include deleted records when calculating the sum.


TABLESUMSQ

Format: TABLESUMSQ( field <, logical> )
Scope: Database
Returns: Numeric

TABLESUMSQ computes the sum of the squares for all table records in a view record. The field must be in a table in the view in which it is referenced. Only non-blank fields are included in the calculation.

You can enter a logical expression as an optional second argument. Each table record for which the expression returns TRUE is included in the calculation.

     TABLESUMSQ([scores])
     TABLESUMSQ([scores], [age] > 18)

The first example computes the sum of the squares for all non-blank values in the table's [scores] field. The second example computes the sum of the squares of the table's [scores] field in records where another table field, [age], is greater than eighteen.


TABLEVAR

Format: TABLEVAR( field <, logical > )
Scope: Database
Returns: Numeric

TABLEVAR computes the sample variance for all table records in a view record. The field must be in a table in the view in which it is referenced. Only non-blank fields are included in the calculation.

You can enter a logical expression as an optional second argument. Each table record for which the expression returns TRUE is included in the calculation.

     TABLEVAR([scores])
     TABLEVAR([scores], [age] > 18)

The first example computes the variance for all non-blank values in the table's [scores] field. The second example computes the variance of the table's [scores] field in records where another table field, [age], is greater than eighteen.


TAN

Format: TAN( numeric )
Scope: All
Returns: Numeric

TAN returns the tangent of the numeric expression. The argument is a value expressed in radians.

TAN(.12) .120579337211


TERM

Format: TERM( numeric, numeric, numeric )
Scope: All
Returns: Numeric

TERM calculates the term over which a fixed payment must be made in order to equal a principal amount, assuming a given interest rate. The arguments are used as follows:

     TERM( principal amount, payment amount, interest rate )

TERM(65988.40,7000,.1) | 30
TERM(5000,250,.18/12) | 23.96

Example:

If you financed a $5000 car at an annual 18% interest rate and set your monthly payment at $250, the formula TERM(5000,250,.18/12) would return a result of 23.96 months as the term of the loan. The annual 18% interest rate is divided by 12 months to maintain the consistency of monthly increments in the formula. Remember that the time periods for the interest rate and the payments must be the same, i.e., both must be in months, or both must be in years, etc. The first example includes a yearly payment schedule, while the second example shows a monthly schedule.
NOTE: The payment amount cannot be less than the interest amount for a given time period. The interest amount is calculated by dividing the principal by 100 and multiplying the results by the interest rate, as in the following example:

     interest amount = 5000 / 100 * 18/12 = 75

Note that 75 is less than the $250 payment.


@TERM

Format: @TERM( numeric, numeric, numeric )
Scope: All
Returns: Numeric

@TERM calculates the term over which a fixed annuity payment, made at the end of every month, must be made to equal a specified future value, assuming a specified interest rate. The arguments are used as follows:

     @TERM(payment amount, interest rate, future value amount)

@TERM(150,.10/12,20000) 90.04

Example:

Suppose you started an investment account with the intention of using the funds at a future time to finance your child's college education. Having established $20,000 as the amount you will need, you plan to deposit $150 at the end of each month into an account earning 10% annual interest. To determine how many months it will take for you to accrue the $20,000 needed, use the formula @TERM(150,.10/12,20000). The result returned is 90.04 months. The 10% annual interest rate has been divided by 12 months to maintain monthly increments in the formula expressions.

To compute the term of an annuity when the payment is made at the beginning of each month, rather than the end of each month, you should enter the formula as follows:

     @TERM( payment amount, interest rate, future value divided by (interest plus 1) )

@TERM(150,.10/12,20000/(1+.10/12 )) 89.51

PRINCIPAL
PMT
INTEREST


TIME

Format: TIME
Scope: All
Returns: Text formatted as a time

TIME returns the current system time as a time expression. The time expression is formatted in 12- or 24-hour format according to the Time Format setting in the Tools Preferences Global menu.


@TIME

Format: @TIME( numeric, numeric, numeric )
Scope: All
Returns: Numeric

@TIME returns a decimal number that represents a time of day as a fraction of the whole day. The arguments are used as follows:

     @TIME(hours, minutes, seconds)

The hours argument represents the number of hours since the beginning of the day (i.e., to indicate 6:00PM you must specify a value of 18 for the hours argument). @TIME uses only the integer part of any argument which includes a fraction.

@TIME(11,42,55) | 0.488136574074
@TIME(11.9,42,55) | 0.488136574074
@TIME(25,16,70) | 1.05358796296


TIME24

Format: TIME24
Scope: All
Returns: Text formatted as a time

TIME24 returns the current system time as a time expression in 24-hour format.


TIMEVALUE

Format: TIMEVALUE( time )
Scope: All
Returns: Numeric

TIMEVALUE returns the decimal number fraction (between 0 and 1) that corresponds to a particular time of day. The argument can be in either 12- or 24-hour time display format.

TIMEVALUE("9:27:50") | 0.394328703704
TIMEVALUE("21:16:00") | 0.886111111111
TIMEVALUE("09:09:09a") | 0.381354166667
TIMEVALUE("09:09:09p") | 0.881354166667


TODAY

Format: TODAY
Scope: All
Returns: Text formatted as a date

TODAY returns the current system date in Date2 format. Date2 format is one of three formats you can use to control the appearance of date information. The Date Format settings in the Tools Preferences Global menu define these formats. TODAY returns the equivalent of the formula DATE2(@TODAY). For an example, see @TODAY.


@TODAY

Format:@TODAY
Scope: All
Returns: Numeric

This function returns a whole number representing the number of days since the beginning of the twentieth century (12/31/1899). @TODAY returns the equivalent of DAYS(TODAY). The following examples assume that the current system date is July 6, 1991.

TODAY | "07-06-91"
@TODAY | 33424


TRIM

Format: TRIM( text )
Scope: All
Returns: Text

TRIM removes all leading and trailing spaces and removes extra spaces from between words in the text expression, leaving one space between each word.

TRIM(" un deux trois ") | "un deux trois"
TRIM("J.D. ")&TRIM(" Kempton") | "J.D. Kempton"


TRUE

Format: TRUE
Scope: All
Returns: Numeric

TRUE returns the value 1. TRUE can be used in a logical formula to signal that a condition does exist.

The following example assumes that the variables CUSTZIP and OURZIP contain the same values.

IF CUSTZIP = OURZIP THEN TRUE ELSE FALSE 1

FALSE


UNIFORM

Format: UNIFORM( numeric )
Scope: All
Returns: Numeric

UNIFORM returns a real number selected randomly from a uniform distribution between 0 and the value of the numeric expression. The following example simulates the roll of a six-sided die.

     INT(UNIFORM(6)+1)

NORMAL
EXPONENTIAL
RAND


UPPER

Format: UPPER( text )
Scope: All
Returns: Text

UPPER returns the text expression with all characters converted to upper case.

UPPER("upPer caSe") "UPPER CASE"


VAL

Format: VAL( text )
Scope: All
Returns: Numeric

VAL converts a text expression to a numeric value. Conversion proceeds from left to right in the text expression and stops with the first character which cannot be interpreted as part of a number. If the expression is numeric or contains only non-numerals, VAL returns 0. The number may be in the form of a decimal number, such as 2300, or a number in exponential notation, such as 23E2.

To yield a negative result, the argument must begin with a minus sign. Leading and trailing space characters do not affect the result.

NOTE: VALUE and VAL are not identical. If the argument is a numeric expression, VAL returns 0 but VALUE returns the value of the numeric expression.
VAL("100") | 100
VAL("2.56E002") | 256
VAL("a") | 0
VAL(100) | 0


VALUE

Format: VALUE( text )
Scope: All
Returns: Numeric

VALUE, like VAL, converts a text expression to a numeric value. Conversion proceeds from left to right in the text expression and stops with the first character that cannot be interpreted as part of a number.

VALUE("15 September") | 15
VALUE(100) | 100


VAR

Format: VAR( item list )
Scope: All
Returns: Numeric

VAR calculates the statistical variance for the numeric items in the item list. All text items or blanks are ignored.

VAR(4.5,6.7,27.2,32.4) 200.527


@VAR

Format: @VAR( item list )
Scope: All
Returns: Numeric

@VAR calculates the population variance for the items in the item list. The item list must contain at least two items. Text items are treated as 0; blanks are ignored.

@VAR(4.5,6.7,27.2,32.4) 150.395


VARPTR

Format: VARPTR( variable )
Scope: All
Returns: Address

This function returns the address of a variable. The passed argument must be a declared variable. For example:

     VP_ptr = VARPTR( $variable )


VARLENGTH

Format: VARLENGTH( variable )
Scope: All
Returns: Numeric

VARLENGTH returns the length of the buffer allocated to a variable by the Buffer project command. This function also returns the length of any text the variable holds and is faster than using the LEN() function, for this specific purpose. VARLENGTH must be used to obtain the buffer length when the buffer contains binary data. Using the LEN function would not work because it counts only the characters up to the first NULL.


ViewLoad

Format: Function name_ViewLoad( ref Cancel )
Scope: Database

When SmartWare is loading a view, it will call the ViewLoad event function with the name of the view as a prefix. Spaces in the view name will be converted into underscores. The ViewLoad can be in a project file that is attached to the view, or it can be in any project file that is currently loaded.

The ViewLoad event can be used to keep a view from loading by setting its Cancel argument to True. The ViewLoad event is also a good place to perform initializations.

Example (cal is the name of the view):
     External readyForLoad
     Function cal_ViewLoad(ref Cancel)
        if Not(readyForLoad)
           Cancel = True
        end if
     End Function

ViewUnload
CurrentRecord


ViewUnload

Format: Function name_ViewUnload( ref Cancel )
Scope: Database

When SmartWare is unloading a view, it will call the ViewUnload event function with the name of the view as a prefix. Spaces in the view name will be converted into underscores. The ViewUnload can be in a project file that is attached to the view, or it can be in any project file that is currently loaded.

The ViewUnload event can be used to keep a view from unloading by setting its Cancel argument to True. The ViewUnload event is also a good place to perform any clean up.

Example (cal is the name of the view):
     Public done
     Function cal_ViewUnload(ref Cancel)
        if Not(done)
           Cancel = True
        end if
     End Function

ViewLoad
CurrentRecord


VLOOKUP

Format: VLOOKUP( expression, block <, numeric> )
Scope: Spreadsheet
Returns: Conditional

VLOOKUP searches a lookup table and returns data from a target cell in the table. A lookup table is a block of contiguous cells containing related data items. The left column usually contains information categorizing the data in the rows of the table. VLOOKUP searches the left column for a cell containing data matching the first argument. If a match is found, VLOOKUP returns the contents of a target cell in the same row.

The arguments of this function are used as follows:

     VLOOKUP( search item, table block <, offset> )

The search item can be any valid numeric or text expression. The block can be any valid block name or reference. The block defines the lookup table. VLOOKUP searches for data identical to the search item in the left column of the block. If the data is found, the contents of a target cell in this "lookup row" are returned. If the data is not found, VLOOKUP returns Error 8, LOOKUP failed.

If no offset is specified, the cell in the rightmost column of the lookup row is the target cell. If you include an offset, that number specifies the number of columns that the target cell falls to the right of the search column. The search column is considered column 0.


@VLOOKUP

Format: VLOOKUP( numeric, block <, numeric> )
Scope: Spreadsheet
Returns: Conditional

@VLOOKUP is similar to VLOOKUP, except that it searches the left column in the lookup table for the cell containing the largest value less than or equal to the first expression. This function requires that data in the search row (the left row) be in ascending numeric order (the values increase from the top to the bottom of the block).

For example, assume that the search item is 250. Since 250 falls between 200 and 300, the row containing 200 in the search column is the lookup row.

VLOOKUP(200,r1:4c1:5,3) | 80.00
VLOOKUP(250,r1:4c1:5,3) | Error 8
@VLOOKUP(250,r1:4c1:5,3) | 80.00


VOICEINFO

Format: VOICEINFO( constant, numeric )
OS: Differences
Scope: All
Returns: Numeric

The VOICEINFO function provides information about various aspects of the voice software. Some settings may also be changed. Note that, while there is no voice control under Unix, this function can still be used to determine whether or not voice is active.

The first parameter is a named constant or integer and indicates what aspect to return or change. The optional second parameter contains the new value. Its presence indicates that the value should be changed. This approach allows a programmer to save the existing value and set a new value with one command. For example:

     #save = VOICEINFO(v_voicemode,0) 'save & turn off
     ... commands
     VOICEINFO(v_voicemode,#save) 'restore previous value

# Constant | Description
0 v_voicemode | This constant can be used to turn on and off voice mode. When voice mode is on, prompts indicate verbal commands. Note that the behavior of voice mode depends on the voice recognition software that is loaded. If voice mode is on, 1 is returned. Otherwise, 0 is returned. The default is based on whether the voice recognition software could be automatically detected. READ/WRITE
1 v_wwrmode | Whole Word Recognition mode is 0 for off, 1 for always and 2 for voice keystrokes only. The default is 2 if DragonDictate version 3.0 is detected, 1 for other voice recognition software and 0 when no voice recognition software is active. READ/WRITE
2 v_ddcolor | Dictation Display Color determines the color of dictated words when at a menu. By default it is the same as the autohelp order colors. Use MOD(x,16) to obtain the foreground color, and INT(x,16) to obtain the background color. READ/WRITE
3 v_ddrow | The Dictation Display Row specifies the row on which the dictated words are displayed when at a menu. The default is the bottom of the screen. READ/WRITE
4 v_ddcol | The Dictation Display Column specifies the left most column on which the dictated words are displayed when at a menu. The default is 1. READ/WRITE
5 v_ddlen | The Dictation Display Length specifies the maximum width of the display area of dictated words are displayed when at a menu. The default is the screen width. READ/WRITE
6 v_ddquiet | If Dictation Display quiet is 1, dictated words are not shown when at a menu. By default it is 0 when voice mode is on. READ/WRITE
7 v_modswstate | This constant indicates and controls whether SmartWare should automatically switch states when changing modules. If you are writing a program that manages the states, it may be useful to turn this off. By default it is 1. READ/WRITE
8 v_rectype | This constant indicates the type of speech recognition software that is active. It is autosensed on start up and can also be controlled with the -os start up parameter. The following values are supported: 0=None, 1=Dragon 2.0, 2=Dragon 2.5, 3=Dragon 3.0, 4=Generic. READ/WRITE
9 v_ltdvocab | This indicates if the currently loaded voice recognition software supports limited vocabulary. It returns 1 for DragonDictate version 2.5 and 3.0. READ
10 v_switchkey | This is the voice mode on/off keystroke. It defaults to Ctrl Alt V, but may be changed. READ/WRITE
11 v_statemgr | This indicates if the voice recognition software supports states and therefore whether ANGOSS SmartWare should employ its State Manager. It is 1 for all supported versions of DragonDictate. READ
12 v_phrasebld | This indicates if the voice recognition software supports phrase building. Only DragonDictate 3.0 does. READ
13 v_rdparam | The v_rdparam constant is used to determine if the voice recognition software has the capability of returning its various parameters via the VOICEPARAM function. It is true for DragonDictate 3.0. READ
14 v_knowkbsrc | This constant indicates whether the voice recognition software can determine if the keystroke source is the keyboard or voice. If it can, then lastkey_source and next_keysource can be used to distinguish key presses and keystrokes generated by speech. When DragonDictate 3.0 is active, it is true (1). All other supported voice software return 0. READ
15 v_skippeek | The v_skippeek constant determines how often DragonDictate is called to check if a keystroke is waiting. The default value is 10 which improves performance considerably compared to a value of 0. Setting this higher can improve SmartWare's performance even more but may lead to slight delays in typing or recognition. READ/WRITE

v_switchkey

The v_switchkey parameter is a two byte number representing a scan code and extended shift states. The high byte contains bits indicating what modification keys are depressed (Ctrl, Alt, Shift, etc.) and the low byte represents the scan code number for the key stroke.


VOICEERROR

Format: VOICEERROR
OS: Differences
Scope: All
Returns: Text

The VOICEERROR function returns the error message produced by DragonDictate. It can be used to diagnose a program after an error occurs using one of the voice related commands or functions. Lines are separated by backslash n, backslashes are represented by a double backslash.


VOICEPARAM

Format: VOICEPARAM( text <,numeric> )
OS: DOS Only
Scope: All
Returns: Numeric

The VOICEPARAM returns and sets current values of the DragonDictate parameters.

The first parameter is a text string containing the parameter name. Use the optional second parameter to assign a new value to the parameter.

Note that the parameters available vary depending on the voice recognition software that is active.

DragonDictate 2.0 - Write Only
DragonDictate 2.5 - Write Only
DragonDictate 3.0 - Read & Write
Generic - No parameters

The following is a list of the parameters that can be used. Refer to the DragonDictate User's Guide for details.

key-pause
double-space-sentence
punctuate
computation
rejection-thresh
pop-up-row
pop-up-col
max-list-size
allow-spell-mode
pop-always
keys-immediate
compatibility-delay
word-pause
pop-up-delay
auto-save-time
int9-always
overwrite-protection
adapt-on-correction-only
number-of-saves-per-backup
limited-vocabulary (DragonDictate 2.5 and higher only)
disk-write-delay


V_OASTATE

Format: V_OASTATE( numeric )
OS: DOS Only
Scope: All
Returns: Text

The V_OASTATE function returns the name of states used by ANGOSS SmartWare. Given a number, it returns the string of the corresponding state name.

0 = Main Menu Base
1 = SS Base
2 = WP Base
3 = DB Base
4 = Com Base
5 = WP block mark
...

It is used so that applications can set the voice software to the appropriate state when dropping a user off in one of the modules. For example:

     IF VOICEINFO(v_statemgr) 'is a state manager active
     ...VOICE STATE CALL NEW V_OASTATE(#module)
     END IF
     SUSPEND
     IF VOICEINFO(v_statemgr) 'is a state manager active
     ...VOICE STATE RETURN
     END IF


WPGET

Format: WPGET( numeric, numeric )
Scope: Word Processor
Returns: Text

WPGET returns up to 240 characters of text from a document. The first argument specifies the number of characters to be returned. The count begins at the current cursor position. Reform spaces, which are used only for alignment purposes, are not included in the count. A -1 value for the number of characters will read to the end of the paragraph. If the second argument is 0, only the text is returned. If the second argument is other than 0, font and special character information are included in the returned text. Font and special character information are not included in the character count.

Fonts are indicated by %[x], where x is the font number. Boldface and underscore are indicated by B and U, respectively. The returned text may also include the following special characters.

Spec. Character | Meaning
%t | tab
%i | indent tab
%p | paragraph mark
%e | end of document
%- | soft hyphen
%% | percent sign, as text


WPINFO

Format: WPINFO( numeric )
Scope: Word Processor
Returns: Conditional

WPINFO returns a variety of information about the current document, based upon the named constant specified in the argument. Valid argument entries and their uses are as follows:

Named Constant | Returns
wp_cursect | Current section number
wp_curpage | Current page number
wp_curline | Current line number
wp_curcol | Current screen column position
wp_filename | Filename (name.ext only)
wp_filespec | File specification
wp_curfont | Font of the current character
wp_newfont | Font for new text
wp_mcacol | Current MCA column number (or 0 if not in MCA)
wp_mcaent | Current MCA entry (or 0 if not in MCA)


WPPUT

Format: WPPUT( text )
Scope: Word Processor
Returns: Numeric

WPPUT enters text with optional special character and font codes into a document at the cursor position. WPPUT returns 1 if the operation is successful, or 0 if the operation is not successful. WPPUT leaves the cursor on the first character of the "put" data.

Text is entered using the specified font, or if no font is specified, the currently selected font. You can change the font within the text by inserting a code in the form %[fontnumber]. To specify boldface and/or underscore, include "B" and/or "U" after the font number. If the font specified does not exist, Font 0 is used. Fonts changes effected by WPPUT have no effect upon existing text in the document.

You can also include the following special characters in the text expression.

Special Character | Meaning
%t | tab
%i | indent tab
%p | paragraph mark
%- | soft hyphen
%% | percent sign, as text

     WPPUT("This is text.")
     WPPUT("%[4U]This%[4]  is text.")

The first example inserts "This is text." at the cursor position, using the current font. The second example inserts "This is text." in font 4, with the word "This" underscored.


WPREAD

Format: WPREAD( numeric, numeric )
Scope: Word Processor
Returns: Text

WPREAD returns up to 240 characters of text from a document. The first argument specifies the number of characters to be returned. The count begins at the current cursor position. Reform spaces, which are used only for alignment purposes, are not included in the count. A -1 value for the number of characters will read to the end of the paragraph. If the second argument is 0, only the text is returned. If the second argument is not 0, font and special character information are included in the returned text. Font and special character information are not included in the character count.

Note that WPREAD works like the WPGET function except that it moves the cursor to the first character that has not yet been read. This makes it easy to read through a document in project processing programs (similar to FREAD).

Fonts are indicated by %[x], where x is the font number. Boldface and underscore are indicated by B and U, respectively. The returned text may also include the following special characters.

Spec. Character | Meaning
%t | tab
%i | indent tab
%p | paragraph mark
%e | end of document
%- | soft hyphen
%% | percent sign, as text


WRITEPTR

Format: WRITEPTR( pointer, <,index> <,index> <,index>, expression )
Scope: All
Returns: Boolean

Using the expression argument, WRITEPTR changes the value in the variable or array element specified by the pointer and index arguments.

     WRITEPTR( VP_variable, $newvalue )
     WRITEPTR( AP_variable, 10, 2, "newvalue" )

WRITEPTR returns 1 if the operation is successful and 0 for failure.

ARRAYPTR
VARPTR


YEAR

Format: YEAR( date )
Scope: All
Returns: Numeric

YEAR returns a value corresponding to the number of the year in the date expression.

YEAR("July 6, 1952") | 1952
YEAR("09/15/2099") | 2099

Date Expressions


@YEAR

Format: @YEAR( date )
Scope: All
Returns: Numeric

@YEAR returns a value represented by the last two digits of the year in the date expression.

@YEAR("July 6, 1952") 52

Date Expressions


RAD Function Reference

A wide variety of functions are available to RAD Application programmers. Most of these functions form an integral part of the RAD App. To use these functions in your RAD programs, simply list them as external functions at the top of the program (before MAIN) and then follow the syntactical instructions laid out in this section.

The function arguments (parameters) in the syntactical example are shown on the Format line. These arguments are preceded with either a dollar sign ($) or a pound sign (#). The dollar sign indicates that the argument is a text string, while the pound sign indicates a numeric value is expected. Arguments preceded by both ($/#) can be either numeric or text values.


ACTIVE_LEV

Format: active_lev( #menu_level )
Module: All
Returns: Numeric -- level of current view

Returns the level (or position in the menu stack) of the currently active data view, spreadsheet or document view. Hence, if a number of menus are called from a view, you could call this function with the current level as the argument, and the returned value would be the level of the view from which all of these menus were ultimately called. This function is used for determining which $$stat[] array element should be used for reading and writing to the database, spreadsheet or document. The following example determines the status at the level of the currently-active view with respect to the current level (which is held in ##lev).

     $status=$$stat[active_lev(##lev)]

Refer to the Developer manual for a discussion of the menu stack and usage of the $$stat[] array.


ADD_LOG

Format: add_log()
Module: Database
Returns: Numeric -- process id

Records an entry in the process and batch update log. It obtains data regarding the entry from the public variables $$desc, $$obj, $$sysid and $$usrid.

COMPLETE_LOG


ASK_FILENAME

Format: ask_filename( $extension, $title, #create )
Module: all
Return: text - name of selected file or 0 if Esc is pressed

Specifies a group of files from which the user selects one. The extension parameter is a space seperated list of extensions that determines which files are to be displayed to the end user. The title is displayed as a prompt at the bottom of the selection box. The path of the files is assumed to be the value of the function expression PATH(datapath) which is the current data path. Note that a developer can issue a Tools Directory New-Directory before calling this function in order to change the path. The end-user may override this path if desired. If create is set to zero, then the file the user selects must exist. If set to one, the user may create a file by typing a name which does not exist. If the user presses the escape key then this function will return a 0. Note that the path filename and extension (e.g., c:\oe\test.dfr) is returned.

     $dfr=ask_filename( "dfr", "Reports", 0 )


ASK_FILENAME_DIR

Format: ask_filename_dir ( $file_spec, $title, #create )
Module: all
Return: string of path and file name.

Calls the ask_filename function however, its format is sometimes more useful. The $file_spec parameter must be a text string with a path, a * for the filename and the extension. The $title is used as prompt and #create indicates if the user may specify files that do not exist.

     $file = ask_filename_dir ( "c:\myfiles\*.doc", "Enter:", 0 )


CHAP

Format: chap( $directory )
Module: all
Return: 0 or 1

Changes execution to another RAD App. The argument specifies the home directory of the target application. When an end user exits the target application, the original system will be reloaded, and the user will be returned to the point in the application from where this function was called.


CHECK_FILE_NAME

Format: check_file_name( $filename )
Module: all
Return: numeric - status (0 = invalid name, 1 = valid name)

Checks whether the argument text string is a valid file name. If it is valid, a value of one (1) will be returned. If invalid, an error message will be displayed and a zero value will be returned.

     WHILE TRUE
         SCREEN SHORTINPUT $fn "Enter file name:"
         IF check_file_name($fn) = 1
             EXIT WHILE
         END IF
     END WHILE


CHECK_PATH

Format: check_path( $path )
Module: all
Return: text - corrected path

Prepares the argument text string to be concatenated with a file name. If a slash or back-slash is required, it is appended.

     IF FILE( check_path($path)|"myfile.txt" )
         ...Process MYFILE.TXT
     END IF


CHOICE_TITLE

Format: choice_title( $menu, #choice )
Module: all
Return: text - choice description

Returns the description, as it appears on the application's menu, of the specified choice. The first parameter is the short name of the menu on which the choice in question appears. The second parameter is that choice's number on the menu. The description is always in the default language, even if another language is currently active. The choice number codes for the physical location of the choice, making no provisions for choices which have been removed from the menus of certain user modes.

     $desc = choice_title( "mm", 1 )


CLEAR_KEYBOARD

Format: clear_keyboard()
Module: all
Return: 0

Clears any key strokes from the keyboard buffer.


CLOSE_CUR_MENU

Format: close_cur_menu( #write )
Module: all
Return: numeric - status (1 = successful, 0 = failed)

Closes and optionally writes the currently opened menu.


CLOSE_ALLWIN

Format: close_allwin( $text_file )
Module: database - file handle ##wrkhnd
Return: numeric - status (1 = successful, 0 = failed)

Unloads all views (except for DV_INFO). If a text file is specified, saves the list of files so that a reload may be performed. A failure occurs if the text file cannot be created.

     close_allwin( $$workdir|"save.win" )

RESTORE_ALLWIN


CMENU Functions

Command Menu Interface (COMMANDLIST replacement)

This series of SPL functions simplify the interface to the pulldown menus and is an improved alternative to the old commandlist() function. These functions allow developers to quickly specify and run pulldown menus or command lists.

Note: If you are not using these commands from within RAD, you must load the RAD libraries by executing the following line before using these functions:

     execute path(systpath)|"loadalib.rf0" in-memory

Constructing a menu

The functions dicussed here allow you to quickly build a menu. In essence, they are a simplified alternative to the mnu_open() and mnu_insch() functions. Note that these functions are written in SPL and, in fact, use the mnu_ functions.

Format: cmenu_init()
Module: all
Return: numeric

This function starts a new menu. It returns 0 for fail, 1 for success.

Format: cmenu_add( $desc, $act, $linehelp, $helpfile )
Module: all
Return: none

Adds an item to menu being built. The following parameters are used.

$desc

Command description. Use -> to specify levels. For example "File->Exit" creates a command named exit under a submenu named file.

$act

Command action. A string that can be used to identify the choice. If left blank then the description of the choice is returned.

$linehelp

The autohelp line for the current choice

$helpfile

The base file name of the file containing help text for this command.

Format: cmenu_makemnu()
Module: all
Return: numeric

This function builds a menu, using mnu_info() related functions, based on the information previously provided with cmenu_add().

It returns a menu handle or 0 if a failure occurred.

Format: cmenu_free( #menu )
Module: all
Return: none

Frees the memory used by a menu file. It is the same as mnu_free().

Format: cmenu_run(#menu,#nav,$key_cb,$com_cb,$h_pth,$h_ext,$#data)
Module: all
Return: none

The cmenu_run() function displays a menu and responds to the end user. The menu can be built with the above listed cmenu functions or with the mnu_info() related functions. For a "quick-and-dirty" menu, the menu choices can also be passed as a text string. Here is the format of cmenu_run()

The parameters are:

#menu

The menu handle or a space seperated text string listing commands.

#nav

Navigation keys. If it is set to 1, then the end user may use the mouse or keystrokes to move around the database, spreadsheet or document. Otherwise, use 0.

$key_cb

Keystroke call back function. If you want your own function to respond to mouse events, keystrokes, etc. then list the name of the public function to deal with these events. See below for more details. If you do not want to use it, simply enter "".

$com_cb

Command call back function. It is best if you specify a function that will be called when a command is selected. This way, the processing overhead to set up the menu only need be run when the menu is entered. See below for details. If you do not specify this parameter (i.e., enter ""), then cmenu_run() will terminate when the user selects a choice, returning the action (or description) of the choice selected.

$h_pth

Help path. This must be a directory name which contains help files for the menu.

$h_ext

Help file extension. This is the three character file extension that the help files for this menu will have. When a user requests a help file the path ($h_pth), file name (from cmenu_add()) and the extension ($h_ext) are combined to calculate the file to display.

$#data

This parameter is passed to the call back functions. You may use it however you want. If more than one data element is required, consider using an array pointer.

If you are running in character mode, (##pulldowns=0) then a command list will be used. A command list is a ring style menu occupying the bottom portion of the text window. If you are running in graphics mode, (##pulldowns=1), then pulldown menus, which sit above the text window, are used.

Command Call Back Function

The command call back function, which is passed as an arguement to cmenu_run(), is called when the end user selects a command. You must write this function yourself. It must be a public function and it must have the following arguements:

     function my_callback($act,$#data,#menu,#choice)

$act

This is the "action" of the menu choice selected as specified by the cmenu_add() or MNU_ACT. Typically, your function will branch based on this value.

$#data

This is whatever was passed to cmenu_run().

#menu and #choice

The #menu and #choice parameters are usually not used. They can be used to further enquire about the menu choice selected. For instance the password, help file, object, etc. can be obtained by passing these choices to mnu_info().

The command call back function should usually return 0. If it returns a value other than 0, cmenu_run() will terminate, returning the same value that you returned. So, when the user selects a choice that should terminate the menu, return a value other than 0.

Key Call Back Function

When a key call back function is specified in cmenu_run(), each time the user presses a key or uses the mouse this function is called. As usual, the call back function must be public. The key call back function requires this format:

     function my_callback(#key,$#data,#menu)

#key

Is the event id as returned by the EVENTINFO function.

$#data

This is whatever was passed to cmenu_run().

#menu

The #menu and #choice parameters are usually not used but can be used by mnu_info() to obtain more information about the current menu.

The key call back function must return 0 if the event was not handled, 1 if the event was handled and 2 if you want the menu to terminate.

Examples

Each program using the cmenu functions must include the following declarations:

     ' Menu Building
     external cmenu_init()
     external cmenu_add()
     external cmenu_makemnu()
     external cmenu_free()

     ' Menu Run
     external cmenu_run()

     global simple()
     global very_simple()
     global still_simple()
     global complex()

     ' If you are not using RAD, the functions must be loaded by:
     execute path(syspath)|"loadalib.rf0" in-memory

     ' VERY SIMPLE EXAMPLE
     **********************************************
     function very_simple()
     local $ret

         $ret =  cmenu_run("Run Exit Copy Delete", 0, "","","","","")
         ' Call a command menu with above commands, no data base navigation

         case $ret
         when "Run"
             message $ret
         when "Exit"
             message $ret
         when "Copy"
             message $ret
         when "Delete"
             message $ret
         otherwise
             message "huh:"|str($ret)
         end case

     end function

     ' SIMPLE EXAMPLE
     **********************************************
     function simple()
     local $ret #menu

         ' Build a Menu
         if cmenu_init()
             cmenu_add("Run","r","","")
             cmenu_add("Exit","x","","")
             cmenu_add("Copy","c","","")
             cmenu_add("Delete","d","","")
             #menu = cmenu_makemnu()
             $ret = cmenu_run(#menu, 1, "","","","","")
             ' Call command menu, with buildmenu with navigation
             cmenu_free(#menu)
             case lower($ret)
             when "r"
                 message $ret
             when "x"
                 message $ret
             when "c"
                 message $ret
             when "d"
                 message $ret
             otherwise
                 message "huh:"|str($ret)
             end case
         end if
     end function

     ' AN ADVANCED EXAMPLE
     **********************************************
     public my_commands()
     public $mydir

     function still_simple()
     local #menu $ret
         $mydir = ""
         if cmenu_init()
             cmenu_add("File->Run","run","run a program","run")
             cmenu_add("File->Exit","x","quit this program","quit")
             cmenu_add("File->Whatever","what","quit this program","quit")
             cmenu_add("Edit->Copy","cpy","copy something","cpy")
             cmenu_add("Edit->Delete","del","delete something","del")

             #menu = cmenu_makemnu()

             $ret = cmenu_run(#menu,1,"","my_commands",$mydir,"txt","")

             cmenu_free(#menu)

         end if
     end function

     ' 0=continue, anything else exit
     function my_commands($action,$data,#menu,#choice)
         case $action
         when "run"
             message $action
         when "cpy"
             message $action
         when "x"
             message $action
             return 1 ' This terminates menu
         when "del"
             message $action
         when "what"
             message $action
         otherwise
             message "action:"|$action
         end case
         return 0
     end function

     ' COMPLEX EXAMPLE
     **********************************************
     public my_keys()
     ' Also uses my_commands from previous example

     function complex()
     local #menu $ret
         $mydir = ""
         if cmenu_init()
             cmenu_add("File->Run","run","run a program","run")
             cmenu_add("File->Exit","x","quit this program","quit")
             cmenu_add("Edit->Copy","cpy","copy something","cpy")
             cmenu_add("Edit->Delete","del","delete something","del")
             cmenu_add("File->Whatever","what","quit this program","quit")
             cmenu_add("Data->Find->Name","f name","find name","fn")
             cmenu_add("Data->Find->Phone","f phone","find phone","fp")
             cmenu_add("Data->Order->Name","o phone","order name","on")
             cmenu_add("Data->Order->Phone","o phone","order phone","op")

             #menu = cmenu_makemnu()

             $ret = cmenu_run(#menu,1,"my_keys","my_commands",$mydir,"txt","Hi There")

             cmenu_free(#menu)

         end if
     end function

     function my_keys(#key,$data,#mnu)
         case #key
         when {Alt-H}
             message $data
             return 1 ' Thank you, I have dealt with event
         when {Alt-Q}
             message "bye alt-q"
             return 2 ' Let's get out of menu
         when {f10}
             message "bye f10"
             return 2 ' Let's get out of menu
         when {esc}
             message "bye esc"
             return 2 ' Let's get out of menu
         end case
         return 0 ' I don't know about this event
     end function


COMPLETE_LOG

Format: complete_log( #process number, $comments )
Module: database
Return: 0

Closes a process/batch update log entry. The process number must be the value returned by the ADD_LOG() function.

ADD_LOG


COUNT_WORDS

Format: count_words( $text )
Module: all
Returns: numeric - number of words

Counts the number of words in a text string. A word is considered to be any sequence of characters not containing a space.

     #words = count_words( $str )


DECODE_EDA

Format: decode_eda( $edit_area )
Module: spreadsheet
Return: 0

Parses the $edit_area string and populates the global $area[] array with those edit area specifications. The $area[] array is used by the EDIT_AREAS() functions. The format of the edit area string is:

     block<outside rows,outside cols>inside rows,inside cols;...

Block specifies a block of spreadsheet cells that define the edit area. The specification must be in standard SmartWare expression format: either an explicit reference (e.g., r1:3c2:19) or the name of a predefined block. Named blocks are defined with the SmartWare command sequence Sheet Name Define. The outside and inside area locks are optional; these specify the number of rows and columns to lock, outside and inside the defined block respectively. The outside lock, if specified, must be preceded with a less-than symbol (<). The inside lock specification, if included, must be preceded with a greater-than symbol (>).


DEF_EDIT_AREAS

Format: def_edit_area( $default_areas )
Module: spreadsheet
Return: text - modified areas string

Interface that allows an end user to define edit areas. The edit areas screen is displayed where the user may type in edit area specifications or choose them from the spreadsheet with the block-marking technique. Edit areas are initially set to those specified by the default areas string. A string specifying the user-selected area specifications is returned.


DISPLAY_MESSAGE

Format: display_message( $string1, $string2, #mode )
Module: all
Return: nothing

Displays one or two line message. Valid mode parameter values:

0 screen only (no key press)
1 Key press and restore screen
2 Key press and clear
3 Message dialog box with OK
4 Mode 1 or 3 depending on ##pulldowns


DO_CALC

Format: do_calc( $definition )
Module: database
Return: 0

Executes a totals definition and displays the results on the screen. It operates on the current data file in its current state - if a standard Query command had been issued to select a subset of records, only these records are totalled.

     do_calc( "totsales" )


EDIT_AREAS

Format: edit_areas( $areas, #start_block, #row, #col, $fkey, #return_fkeys )
Module: spreadsheet
Return: numeric - key stroke used to exit

Interface that allows an end-user to modify the contents of the specified edit areas on the current worksheet. The areas string specifies the edit areas using the format described in the DECODE_EDA() function. The row, column and block number in which the cursor is initially placed are specified by the #row, #col, and #start_block parameters. A description of key stroke functionality can be supplied with the $fkey parameter. If the #return_fkeys parameter is set to 1, then the user key stroke is returned if F3, F4, F6 or F9 is pressed. Otherwise, these keys are ignored.

     #exitkey=edit_areas("blk1<1,1;r1:10c2:20>2,2",1,1,1,"F3=Special",1)
     IF #exitkey = {F3}
        ...
     ELSEIF
        ...
     END IF


ERRORREP

Format: errorrep( $path_file )
Module: all
Return: 0

Asks the end-user to indicate whether an error report should be printed or displayed.

     errorrep( "c:\test\system\errors.txt" )


FIND_COMMAND

Format: find_command( $task )
Module: database
Return: 0

Presents the Find command interface based on the current view. This always returns 0.


FINDRECORD

Format: findrecord( $key_menu, $keys, #view )
Module: database
Return: 0

Displays a list of the current view's key fields, allowing an end user to select one on which to search based on the user's comparison data. The first record meeting that criteria is made current.

The $key_menu parameter is a string listing each key field name, separated by spaces. Any spaces in the actual key field names must be replaced with an underscore character. The $keys parameter lists the key field names again, however, spaces within field names are NOT replaced with underscores. The #view parameter indicates whether the appropriate $$stat[] array entry should be updated to reflect any changes in the order of the data file. It also determines whether the variable $$kytp should be used to indicate if and when the user's input should be automatically converted to upper case, lower case, proper case or masked. A value of 1 indicates that the $$stat[] array should be updated and the $$kytp variable dictates any input case conversions or masks.

     findrecord( "Part_# Part_Type", "Part # Part Type", 0 )


FREE_CELL

Format: free_cell()
Module: spreadsheet
Return: numeric - status (0=locked, 1=free)

Checks the current cell and returns a value of 0 (False) if it is locked and 1 (True) if it is unlocked.


GET_ANGII_VER

Format: get_angii_ver( #product, #info )
Module: all
Return: text - version and/or build information

Obtains the version and build information. Set the #product parameter to 0 for application environment information and 1 for Developer information. Set the #info parameter to 0 for the version number, 1 for the build information or 2 for both. If an error occurs, a ? will be returned.


GET_CHOICE

Format: get_choice( $str1, $str2, $st3, $str4, $choices, #mode )
Module: all
Return: text

Displays message and prompts for selection. Valid mode parameter values:

1 Key press and restore screen
2 Key press and clear
3 Message dialog box with OK
4 Mode 1 or 3 depending on ##pulldowns


GET_FILE

Format: get_file($pth,$vw,$typ,#cur,#excl,#retry,#hnd,#ind)
Module: database
Return: result string

This RAD function loads the specified view or makes it current if the view is already loaded. This last action assumes that the #cur parameter is set - see below.

Parameters:

$pth

The path of the view. If its value is a null string, the path is determined by the RAD application's internal data (i.e., dv_info).

NOTE: If the view is already loaded, the path parameter is ignored. In cases where the application uses multiple views with the same name, it is safer to unload the view and call GET_FILE again - see the Return Strings section below.

If the path parameter is a view name prefixed with a question mark (e.g., "?customer"), GET_FILE will find that view's path (again in dv_info) and use it. Typically, this is done when loading a standard-view that is normally attached to a custom-view but does not share the same name.

$vw

The view name. Do not include the path or extension.

$typ

Indicates the type as custom-view or standard-view. Valid options for this parameter are "vw" for custom-view and "vws" for standard-view.

#cur

Makes the view current. Valid options for this parameter are 1 (view is current) and 0 (view is active).

#excl

Loads the view as exclusive - this prevents other users from loading the file. Note that the #cur parameter must be true (1).

NOTE: If the view is already loaded but is not exclusive, unload it before calling GET_FILE again, otherwise the view will not be reloaded - see the Return Strings section below.

#retry

Number of load attempts. If this parameter is set to 0, the program is interrupted and the user is prompted to retry or abort the load attempt. A value greater than 0 indicates the number of uninterrupted retries. In this case, after each failed load attempt, the function pauses before retrying. This pause is increased by one minute per attempt (e.g., after the ninth attempt, the function waits nine minutes before retrying).

#hnd

Message file handle. When this parameter is greater than 1, messages are written to the opened file represented by the handle. The program will not be interrupted when errors occur. Typically, this is used in an AUDITED PROGRAM where the standard handle passed to GET_FILE is ##mhnd. Messages are then written to the Batch Update/ Process Log. When the handle is set to 0, error messages are displayed on the screen while the program waits for user input.

#ind

Indentation level for messages.

Return Strings:

"error" - Unable to load the view.
"loaded" - GET_FILE loaded the view.
"already loaded" - View was previously loaded.

Example 1:

The code fragment below loads the view, if it is not already loaded, and makes it current. Exclusive mode is not invoked, load retries are prompted, and error messages are displayed on the screen. For more advanced usage, refer to the second example.

     FUNCTION Init()
     LOCAL $view

         $view = "customer"

         IF get_file("",$view,"vw",1,0,0,0,0) == "error"
             RETURN 0
         END IF

         ... other initiation code

         RETURN 1
     END FUNCTION

Example 2:

The code fragment below was extracted from an AUDITED PROGRAM. It loads the inventory custom-view exclusively. In case of loading errors, six attempts will be made to retry the load.

Note that, because the view must be loaded exclusively, an unload is performed if GET_FILE returns "already loaded". The WHILE loop then causes a reload.

     FUNCTION UpdateInventory()
     LOCAL $view $result

         $view = "inventry"

         WHILE TRUE
             $result = get_file("",$view,"vw",1,1,6,##mhnd,2)
             IF $result == "already loaded"
                 FILE UNLOAD VIEW $view|".vw"
             ELSE
                 EXIT WHILE
             END IF
         END WHILE

         IF $result == "error"
             rec_message( "Could not load" & $view )
             rec_message( "* Critical view - Batch aborted" )
             RETURN 0
         END IF

         ... code to update view

         RETURN 1

     END FUNCTION

Notes:

While GET_FILE can be used to load views in any program, it has a number of features that make it valuable in Batch Processing programs where the program runs unattended. The message and load retry facilities are ideal in that, no program interruption is required. Further, the exclusive loading mode eliminates potential LOCK RECORD problems and other update record issues.


GET_LINE

Format: get_line( $str1, $str2, $st3, VP_$str, $default, #len, #mode )
Module: all
Return: text

Displays message and prompts for selection. Valid mode parameter values:

1 Key press and restore screen
2 Key press and clear
3 Message dialog box with OK
4 Mode 1 or 3 depending on ##pulldowns


GET_PATH

Format: get_path( $short_name )
Module: spreadsheet, database - Uses: file handle ##wrkhnd
Return: text - path name

Returns the path of a spreadsheet or data view whose short name is specified by the parameter. If more than one data view or spreadsheet is associated with the menu, then it is the path of the primary view or worksheet which is returned.

     $path = get_path( "disctab" )


GROUP_NUM

Format: group_num( $list, $item )
Module: all
Return: numeric - original position

Returns the original position number of an item within a list. Items are delimited by spaces. If the item is not found, a value of 0 is returned. For example, the following lines of code are true.

     IF group_num( "ABC DEF GHI", "DEF" ) = 2

     IF group_num("A B C D E F", "M") = 0


HELP_TEXT

Format: help_text( $null )
Module: all
Return: 0

Invokes the RAD App help system. It assumes the menu file is open, and current choice variables are set. The parameter is not used and should be set to the Null string.

     help_text( "" )


INT_PATH

Format: int_path( $pathvar )
Module: all
Return: text - decoded path

Interprets coded paths. Such paths utilize public variables, which contain system-wide path names, so as to avoid hard-coding these paths. These variables are converted into explicit paths. To mix explicit path specifications and coded specs, separate the variable name and the explicit portion by a single space.


KEY_FIELD_PROMPT

Format: key_field_prompt( $type )
Module: database
Return: Key field number, 0 for Esc.

Presents a menu that prompts a user for a key field based on the current view. The $type parameter specifies whether Special_sort or Physical are added to the list:

o Both Special_sort and Physical are added.
f Only Physical is added.
k Only key fields are presented.

Possible return values:

0 if Esc was pressed by the user.
The number of the key field, whose value can be used as an array index in $$keys[], $$key_types[], and $$key_alias[].
The text "Special_sort".
The text "Physical".


KRUNCH_SCREEN

Format: krunch_screen( $screen, $path )
Module: database
Return: 0

Allows an end user to krunch one or all data files attached to the specified screen. When run, the user will be given suitable warnings.


LOADDATAVIEW

Format: loaddataview( $menu, $load/unload, $mode )
Module: database
Return: numeric - success? (0=unsuccessful, 1=successful)

Loads or unloads all data files and views associated with the specified menu name. The load/unload parameter can be set to "load" or "unload".

The mode parameter is left blank under most circumstances. When it is used, the first three characters specify the type of special action to perform. Additional characters may be required, as outlined below.

If the left three characters are "DDL", the system will read the Database to Database link definition specified by the remaining characters of the third parameter (e.g., "DDLmyddldef").

If the left three characters are "PTH", the main data view will be loaded from the path specified by the remaining characters (e.g., "PTHC:\arch").

If the left three characters are "ALL", the main view and all associated views will be loaded from the specified path.

     IF loaddataview( "oe", "load", "")
         process data view...
     ELSE
         error handling...
     END IF


LOCK_REC

Format: lock_rec( $message, #must_lock )
Module: database
Return: number - success? (0=unsuccessful, 1=successful)

Locks a record and retries the lock if not successful. The first parameter is a text string that is displayed when the lock fails. Typically this message should communicate the name and path of the data file that is being locked. The RAD App will also print the physical record number and allow the user to view the data file being locked.

The second parameter must be 1 or 0 (true or false) and indicates whether the record must be locked. If it is 1, the function will not terminate until the record is locked. If the second parameter is false and the maximum number of retries is reached or the user presses Esc, the function will abort and return 0.

NOTE: The LOCK_REC functionality is modified by two public variables which are set in the angoss.cfg file. The ##lck_rt variable indicates the number of seconds between lock retries and the ##lck_nr indicates the number of retries that will occur before giving up - note that this only has an effect when the #must_lock second parameter is 0. The product of ##lck_rt and ##lck_nr is the approximate number of seconds LOCK_REC will wait before giving up.

     #lock = lock_rec("Locking "|get_path("inven")|"inven.db.",0)
     IF #lock
         [on hand] = [on hand] + #qty
         WRITE-RECORD
     ELSE
         rec_message( "ERROR: lock failed" )
         rec_message( [part #]&"not updated by"&str(#qty) )
     END IF


MENU

Format: menu( $mode )
Module: all
Return: 1 (or causes program to terminate)

This function accesses the program which drives every RAD App. It is responsible for managing the menu structure, and interpreting user input. It may be called in either of two modes, specified by the $mode parameter. If called with mode set to "normal", the calling program will terminate, and the MENU() function will take over indefinitely. If mode is set to "dochoice", a single action will be processed and control is then passed back to the calling program providing a module change is not performed and an OSA script is not run.

To invoke in "normal" mode, the READ_HEADER() function must first be called in order to set the public variables appropriately and open the menu file. All stack variables must be set properly. When called, the MENU() function will cause the calling program to terminate and the RAD App menu system will be made operational.

To invoke in "dochoice" mode, the public variables $$act, $$obj, $$fct (action, object and function) must be set to specify the desired task. When invoked in this mode, only this one task will be performed.

     $$act = "pcr"  'Print Current Record
     $$obj = ""
     $$fct = ""
     menu( "dochoice" )


MENU_CALL

Format: menu_call( $menu )
Module: all
Return: 1

Invokes the application menu specified by the $menu parameter. The menu will operate as usual. Any choice which appears on the menu may be selected, including those which lead to other menus. This function terminates when the user exits the original menu.

In order to guarantee that control will be returned correctly to the calling program, you must disable module changes by setting the public variable ##dsmch to 1 first. If ##dsmch is 0 and a module change takes place, the calling program will be terminated. Be certain to reset ##dsmch to 0.

     ##dsmch = 1
     menu_call( "oe" )
     ##dsmch=0


MENU_TITLE

Format: menu_title( $menu )
Module: all
Return: text - name of menu

Returns the title of the menu specified by the $menu parameter. The title is returned in the default language.

     menu_title( $$sn[##lev] )


MODULE_CALL

Format: module_call( #module, $project_file )
Module: all
Return: numeric

This function, along with the MODULE_RETURN function, is used to call a project in another SmartWare module when running a RAD application. They do all the work necessary to save and restore the current application position.

The parameters are:

#module

1=SS, 2=WP, 3=DB, 4=CM, (-1=special)

$project

text string which is path and filename to execute when at the destination module (required)

If #module = -1 then the caller is to do the actual module change. (e.g., using the send command.) If -1 is used, the caller must execute the project $$advr|"ppmodch.rf3", which in turn executes the project specified by $project_file.

Return values are:

0 = Fail
1 = If #module=-1 and successful.
Doesn't return if 1<=#module<=4 and successful

MODULE_RETURN


MODULE_RETURN

Format: module_return()
Module: all
Return: nothing

The MODULE_RETURN() function is only used after MODULE_CALL(). It requires no parameters. When called, it returns to running the application at the point that MODULE_CALL() was issued.

MODULE_CALL


ONE_RECORD

Format: one_record( $index, $view, #record )
Module: database - Uses: file handle ##wrkhnd
Return: 1

Creates an index containing a single record and orders the file to that index. Subsequent print-outs, mail merges or send to spreadsheet actions will involve only this record.

The $index parameter contains the filename of the index to create. The $view parameter specifies which view (of those currently loaded) to act upon. The #record parameter specifies the physical record number of the record to select.

     one_record( "temp", "invoice", PRECORD )
     PRINT REPORT EXECUTE "inv" PRINTER DETAIL START * END * COPIES 1
     reorder()
     TOOLS FILE ERASE $$workdir|"temp.idx"


OPEN_FILE

Format: open_file( $path, $file, #mode )
Module: All
Return: file handle, <=0 if error occurs

Opens the specified file and returns a file handle. Used as a replacement for SmartWare's FOPEN command.

The file is specified by the $path and $file parameters. Note that the path parameter can be set to null ("") and added to the file name instead, however, if the path parameter is used, it must contain a directory separator at the end. The #mode parameter specifies whether the file should be opened in read only mode, share mode, etc. You can pass the mode parameter as a named constant (rw_mode, ro_mode, ro_share, rw_share) or as a string ("rw_mode", "ro_mode", "ro_share", "rw_share").

Briefly, the differences in the modes are:

RW_MODE Read and Write abilities, locks file. Will create file if it does not exist.

RO_MODE Read Only, locks the file. Error if file does not exist.

RO_SHARE Read Only, allows simultaneous access. Error if file does not exist.

RW_SHARE Read and Write abilities, allows simultaneous access. Creates file if it does not exist.

The returned file handle allows you to write programs that will not conflict with the RAD App or any other currently running programs.

If the function runs out of user file handles (maximum of 20 allowed) it returns 0. If an error occurs when opening the file, it returns the error number as a negative value, so that the error code can be determined by an absolute value (ABS function) of the result. No error message is shown to the end user.

     local #hnd
     #hnd = open_file( $$workdir, "temp.txt", RW_MODE )
     IF #hnd=0
         MESSAGE "No more file handles. Press a key..."
         RETURN 0
     ELSEIF #hnd<=0
         MESSAGE ERRORTEXT( abs(#hnd) )|". Press a key..."
         RETURN 0
     END IF

     FSEEK #hnd 0
     FWRITE #hnd FROM "Hello There!"
     FCLOSE #hnd
     RETURN 1


OPEN_LOG

Format: open_log()
Module: all
Return: numeric - success? (0=unsuccessful, 1=successful)

Opens the user activity log for the current user ($$usrid) and seeks to the end of the file in preparation for more entries. The first time called, $$workdir is set.


ORDER_COMMAND

Format: order_command( $task, $word )
Module: database
Return: 0

This presents the ORDER COMMAND interface on the current view. The return value is always 0.


OS_APL

Format: os_apl( $script )
Module: all
Return: 0 (or causes program to terminate)

Runs an operating system application such as a third-party software package. The $script parameter specifies the batch file. Its location must be in the system directory ($$syspath) with an extension of .OSA. When the application is terminated, the user is returned to the menu last used prior to execution of this function.

     os_apl( "cadcam" )

This is only recommended for use in DOS.


PASSWORD

Format: password( $password )
Module: all
Return: numeric - correct password (0=incorrect, 1=correct)

Displays the "Enter the password:" prompt. Any characters typed will be displayed as asterisks (*) on the screen. The user will have three chances to enter the correct password (specified by the parameter). If the correct password is entered, a value of 1 is returned, otherwise 0 is returned.

     IF password( "ABC" )
         ...allow access
     ELSE
         MESSAGE "Access denied."
     END IF


PASSWORD_CRYPT

Format: password_crypt( $password )
Module: all
Return: nothing

This function is just like PASSWORD except that the $password parameter is a string encrypted with the CRYPT() function.


POP

Format: pop()
Module: all
Return: 0

Unloads all files related to the current menu and sets up the files and variables required for the previous menu in the hierarchy. The ##lev level indicator is decremented by one. This function will not terminate the current program unless the it causes a module change. In that case, the program terminates, changes modules, and returns control to the RAD App (i.e., the MENU() function in "normal" mode). However, if the variable ##dsmch is set to 1 (this disallows a module change), the POP function and module change will not occur and the current program will continue from the following line.


PRINT_DOC

Format: print_doc( $file, $en_dr, $copies, $startpage, $endpage, $dest )
Module: word processor
Return: 0 if escaped, 1 if print command executed

Prints a word processor document. Valid values for the parameters:

1 $file Path and file name of document to print - "[]" indicates the current document.

2 #en_dr Print mode: "E" prints enhanced mode, "D" prints draft mode, "A" prompts user for mode.

3 $copies Number of copies to print: "A" prompts user for number of copies, null for 1 copy.

4 $startpage Start print at page number: "A" prompts user for starting page, null for first page.

5 $endpage End print at page number: "A" prompt user for end page, null for end of document.

6 $dest Path and file name to print to, "A" prompts user for destination, "P" prints to the printer.

     print_doc( "[]", "a", "", "", "", "p" )


PRINT_T_FLD

Format: print_t_fld( #row, #col, #fg, #bg, $text )
Module: database
Return: text - next row and column

Print the contents of a scrollable text field on the screen. The upper left-hand corner is defined by the row and column parameters. The foreground and background parameters specify the colors that are to be used. The last parameter is the text to print. Database field references may be used. Tilde characters (~) are used as line feeds.

The row and column of the last screen position used by the print are returned in the form of a string: row followed by column and separated by a space (e.g., "10 42" ).

The following code fragment prints the contents of the [Question] field at position (5,10) on the screen, with a black (0) on white (15) color scheme. The returned position is then used as the starting position for the user's answer.

     $rc = print_t_fld( 5, 10, 0, 15, [Question] )
     #row = VALUE( GROUP($rc,1) )
     #col = VALUE( GROUP($rc,2) )
     SCREEN INPUT #row #col 0 15 8 $answer


PUSH

Format: push( $menu )
Module: all
Return: numeric - success? (0=unsuccessful, 1=successful)

Sets the variables and loads the files required for the menu specified by the $menu (short name) parameter. It increments the ##lev stack level variable by one. If a module change is required by the new menu, the calling program will be terminated and control returned to the RAD App.

     push( "oe" )

POP


READ_CHOICE

Format: read_choice( #choice )
Module: all
Return: 0

Sets public variables according to the information for the specified choice on the current menu. The menu file must have been read with READ_HEADER(). The #choice number represents the sequential node number in the menu file. Note that, is READ_HEADER was called in RO mode, various transformations take place, such as deleting choices not required for the current user.
The following table lists the variables that are set by this function:

$$desc - Description which appears on the menu.
$$act - Action.
$$obj - Object.
$$fct - Function/parameter.
$$ah - Autohelp line.
$$hppt - Help file pointer (".AHP").
$$pw - Password, if any.

The $$desc and $$ah variables will be appropriately translated if an alternative language is active. The $$pw variable is determined by the current user mode.

     read_header( "oe" )
     FOR #ct=1 to ##numch
         read_choice( #ct )
         SCREEN PRINT #ct 1 15 0 $$desc
     END FOR


READ_HEADER

Format: read_header( $menu )
Module: all
Return: numeric - success? (0=unsuccessful, 1=successful)

Opens the specified menu file in read only mode and sets public variables for the menu.

The following public variables are set:

$$sn[##lev] Current menu short name indicator.
$$typ[##lev] Current menu type indicator.
$$mttl Menu title.

$$clttl - Command list title.
$$hphp - Overview help file name.
##numch - Number of choices on current menu.
##top - Top of menu (row).
##left - Left position of menu color.
##width - Width of menu.
##height - Height of menu.
##comfg - Text foreground color.
##combg - Text background color.
##grafg - Graphics color.
##audon - Record selections in Audit File.
##mod[##lev] - Current resident module locator.

Menu color variables are also set - refer to the RAD Colors section in the Developer manual.


RELOAD

Format: reload( $files )
Module: spreadsheet, word processor
Return: 0

Loads all files passed in the $files parameter. This string accepts full file names with each file separated by a space (e.g., "\test\files\file1.ws \test\files\file2.ws"). This string can be obtained through SmartWare's CURRFILES() function prior to unloading files. Note that reload function detects files which are already loaded and skips all such files.

     $files = CURRFILES(2)
     FILE UNLOAD ALL
     ... other operations
     reload( $files )


REORDER

Format: reorder()
Module: database
Return: numeric - success? (0=unsuccessful, 1=successful)

Reorders records in the current data view, placing the records in the order specified by the appropriate $$stat[] array entry. Each entry in this array contains the order (i.e., the key name, index name or "physical") and the record number. The stat array should be modified by the UP_DB_STAT function.

     'SAVE RECORD #
     #lev = active_lev( ##lev )
     up_db_stat( #lev, record, "", "", "") 'update record #

     'ORDER FILE
     ORDER CHANGE KEY [name]
     PRINT REPORT EXECUTE ...

     'RETURN TO ORIGINAL STATUS
     reorder()


RESTORE_ALLWIN

Format: restore_allwin( $file )
Module: database
Return: numeric - success? (0=unsuccessful, 1=successful)

Reload all files that were closed and saved by the CLOSE_ALLWIN() function. The $file parameter specifies the text file that stored open file names at the time of the close call.

     close_allwin( $$workdir|"save.win" )
     ... other operations
     restore_allwin( $$workdir|"save.win")

CLOSE_ALLWIN


RP_EXEC

Format: rp_exec( $vw, $rep, $in_scrn, $qry, $prog, $order, $params, #no_interrupt )
Module: database
Return: 0

Executes a previously defined Developer report. Each of the objects or null strings must be passed. Execution parameters ($params) are passed as a set of seven numbers. The order is based on the report's execution dialog box.

1 Destination (1) ask user, (2) disk, (3) printer, (4) screen, (5) text screen

2 Type (1) ask user, (2) details, (3) totals only

3 Pages (1) ask user, (2) complete report

4 Copies (1) ask user, (2) one

5 Allow One (1) ask user, (2) yes, (3) no

6 Records (1) whole file, (2) user index

7 Audit (1) yes, (2) no

If $param is a null string, the user is prompted for all options with the report operating on the user index and no audit. Thus, the value of this parameter defaults to "1111122".

Warning: If a program that executes RP_EXEC is called in a job stream, its input screen can halt the stream. In this case, call the report directly from the job stream or do not use an input screen.


RUN_QUERY_STR

Format: run_query_str( $name, $query, #mess_hnd )
Module: database
Return: numeric - number of records selected

This function runs a query specified by the $query string variable. It avoids the need for separate query files and makes code more readable by embedding query statements in project file.

The parameters are:

$name

File name of index that is generated (do not supply path or extension) path will be $$workdir, ext=.idx

$query

String containing the logical expression of query.
Use \n for new line.
Use \' for double quotes (see example).

#mess_hnd

File handle of an already open text file for messages.
Use 0 for no message file.
Use number to write the query name and expression to a file when executed for tracing purposes.

Return values:

Successful - the number of records selected

Error - 0 means error was caused internally by the RUN_QUERY_STR() function, otherwise a negative value indicates a SmartWare error number (multiply this by -1 to get real number).

Examples:

     run_query("dept","[Department]=\'A\'",0)

     $dept = "A"
     run_query("dept","[Department=\'"|$dept|"\'",0)


SCROLL

Format: scroll( #speed )
Module: all
Return: 0

Causes the records, cells or lines of the current data view, spreadsheet or document to scroll up or down on the screen. The #speed parameter must be an integer from -10 to 10, 0 not included. The absolute value of this integer indicates the speed of the scroll; its sign indicates the direction - negative values cause upward scrolling, and vice-versa. While scrolling, the user may change the scroll direction by pressing the up/down arrow keys and the speed by pressing the appropriate number key.

     scroll( 8 )


SORT_STRING

Format: sort_string( $list )
Module: all
Return: text - sorted list of words

Alphabetically sorts the list of words contained in the argument. Words are delimited by spaces.


SPLIT_PFE

Format: split_pfe( $fullpath )
Module: all
Return: text - argument string broken into words

Separates the path, file name and extension in the argument string from one another. Each element is stored in the returned string separated by spaces. SmartWare's GROUP function may be used to separate these elements from the returned string.

     $pfe = split_pfe( "c:\gl\files\coa.db" )
     IF GROUP( $pfe, 1 ) = "c:\gl\files\"
         'Path exists
     END IF
     IF GROUP( $pfe, 2 ) = "coa"
         'File exists
     END IF
     IF GROUP( $pfe, 3 ) = "db"
         'extension exists
     END IF


SUSPEND_APP

Format: suspend_app( $message, #pulldowns )
Module: all
Return: nothing

Suspends the RAD App and provides end user access to SmartWare. When the user exits SmartWare, the program is resumed.


TOOLS_FILE

Format: tools_file( $command, $file1, $file2, #interrupt )
Module: all
Return: 0

A convenient version of SmartWare's TOOLS FILE... commands.

The $command parameter must be "copy", "delete", "move", "rename", or "print". The $file1 parameter specifies a full file name. Wild card characters are allowed. The $file2 parameter is required for the copy, rename and move variants, specifying the destination file name.

If the #interupt parameter is set to 0, an end user will NOT be able to terminate the operation with an Esc key. Normally the Esc key will interrupt a TOOLS FILE operation and present the end user with the prompt: Abort (Y/N). If you have already used the REPLY command to affect prompt 12, or want to allow the Abort (Y/N) prompt then set this parameter to 1.

TOOLS_FILE() turns error messages to the end user off, so there's no need to check for the existence of a file before erasing it. Use CLEARERROR and LERROR to check for any errors.


UP_DB_STAT

Format: up_db_stat( #lev, #record, $ord_type, $ord_name, $ddl )
Module: database
Return: 0

Modifies the $$stat[] variable (status stack variable). The $$stat[] array contains information about data views or spreadsheets that are active. In the database it contains: the current record number, the order of the file, and any active DDL's (database to database link definitions). This information is used when changing menus. The REORDER() function, which resets a file's order and record number, inspects the $$stat[] array. You will need to use this function if you change the order of a data file and want the RAD App to recognize the new order or record number.

The #lev parameter is used to identify which active data view you are specifying new information for. If you are changing the current data view, pass the ##lev public variable. The #record parameter indicates the new record number. The $ord_type parameter must be set to "key", "index" or "physical". The $ord_name parameter is specifies the index name or the key field name if appropriate. Finally, the $ddl parameter specifies the database to database link definition that was used to reach the current data view. To skip the last three parameters, pass null strings.

     ORDER CHANGE KEY [name]
     up_db_stat( ##lev, record, "key", "name", "" )


WRITE_NAME

Format: write_name( $str, #pos, #handle )
Module: database
Return: 0

Writes a view name to an index file. This allows you to create indices manually with SPL. It assumes the index is already opened in write mode with the specified file handle. To write a view name on an index, use a position of 4.

     write_name( "inven", 4, ##wrkhnd )

WRITE_NUM


WRITE_NUM

Format: write_num( #number, #pos, #handle )
Module: database
Return: 0

Writes record numbers or record counts on an index file. This allows you to create indices manually with SPL. It assumes the index is open with the specified file handle. The following example creates an index with one record, the current record, in it.

     FUNCTION one_record( $index, $file, #record )
         WHILE NEXTKEY <> 0
             INCHAR
         END WHILE

         IF FILE( $$workdir|$index|".idx" )
             TOOLS FILE ERASE $$workdir|$index|".idx"
         END IF

         'CREATE INDEX
         TOOLS FILE COPY $$advr|"blank.idx" TO $$workdir|$index|".idx"

         FOPEN $$workdir|$index|".idx" AS ##wrkhnd OPTIONS RW_MODE

         'WRITE RECORD COUNT
         write_num( 1, 0, ##wrkhnd )

         'WRITE NAME
         write_name( $file, 4, ##wrkhnd )

         'WRITE PHYS RECORD #
         write_num( #record, 64, ##wrkhnd )

         FCLOSE ##wrkhnd
         ORDER CHANGE INDEX $$workdir|$index
         RETURN 1

     END FUNCTION


WRITE_ULOG

Format: write_ulog()
Module: all
Return: 1

Records an entry in the user usage log. It uses the public variables $$usrid, $$sn[##lev], $$act, $$obj, and $$fct to determine the details of the entry. It assumes that the user's usage log is open with file handle ##lgfh.

     write_ulog()


ZAP_DB

Format: zap_db( $file, $path )
Module: database
Return: 0 if an error occurs, or 1 if no error occurs.

Completely erases all records in a data file. If the standard view is loaded, it is unloaded, purged and then reloaded. No other views containing the specified data file must be loaded.

Note: This gives no warnings to the end user.


Project Command Reference


Introduction

This chapter explains the purpose and format of each SmartWare Project Processing command and statement. Example code has been included where appropriate to illustrate the use of these commands and statements.

The Project Processing Command Reference is arranged alphabetically with a few related commands (PACK and UNPACK, for example) grouped together. References to the grouped commands explain where to look for further information.

For clarity, all project commands, statements, and SmartWare functions are printed in uppercase letters to distinguish them from module commands. This does not mean, however, that you have to type them into the Project Editor in all uppercase letters.


Special Considerations

SmartWare Project Processing is significantly different from previous versions. If you have not already done so, you should read the Project Processing manual.


Basic Concepts

Before you begin, there are a few concepts and terms with which you should be familiar to understand how certain project commands work.


Buffer Variables

A number of Project Processing commands use buffer variables. Buffer variables are generally used to hold records or blocks of non-text (binary) data. Many of these commands require native addresses. The following commands use buffer variables:

FREAD BINARY | FWRITE BINARY
INTERRUPT | FARCALL
BUFFER | LOW BUFFER
SCREEN RESTORE | SCREEN SHORTRESTORE
NATIVE PEEK | NATIVE POKE
PACK | UNPACK
PEEK | POKE
MEMPACK | MEMUNPACK
SOUNDBLOCK

Project Processing variables generally contain either numbers or text. Text stored in a variable is generally expected to be a string of text characters, such as a name, followed by one character that is a binary zero, usually called a NULL. This NULL character is automatically added by SmartWare when you assign the text to the variable and is used to mark the end of the text. In the examples in on-line help, NULL is shown as <0> to indicate that it is not the ASCII character 0.

When an expression containing a text variable is evaluated, SmartWare copies the text characters out of the variable until it finds the NULL that marks the end of the text.

However, the commands that use buffer variables use data that may not contain text characters and that may include NULL characters in many places within the data. To process this data, these commands work directly with the variable instead of allowing the data to be copied. (If the data were copied, then only the data up to the first NULL would be used).

A buffer variable is simply one that does not contain pure text. It would be more appropriate to think of the variable as containing a buffer, rather than text, even though internally a buffer variable is exactly the same as a variable that contains text. It is the commands that use the variable that treat it differently from a variable containing normal text.
NOTE: Buffer variables can be copied by assignment from one variable to another and passed as parameters to a function, as in the following example:

     BUFFER var SIZE 10

     var1 = var   'var1 contains a copy of the buffer in var
     myfunc(var)  'copy of buffer in var is passed to a function

Project developers should be careful not to accidentally use a variable that is used for buffer data as a normal text variable. However, because internally there is no distinction between the two, it is acceptable to use a variable containing normal text as a buffer variable, and vice-versa.


Memory Records

A memory record is a portion of memory that is explicitly allocated using the MEMALLOC command. The commands that use memory records are as follows:

MEMALLOC | MEMFREE
MEMPACK | MEMUNPACK
LOW MEMALLOC |

Unlike a buffer, which is actually attached to a variable, a memory record is referenced only by the memory address that is returned by the MEMALLOC command. This address is really a pointer to the memory record and is stored as a number.

When allocated, a memory record is linked internally to other memory records and is tagged for identification purposes. A memory record is not deallocated until the MEMFREE command is executed, or until the module is exited. If the pointer to the memory record is lost, then the memory will remain allocated until the MEMFREE ALL command is executed, or until the module is exited.

MEMALLOC
MEMFREE

The data in a memory record can be stored and retrieved only through the MEMPACK and MEMUNPACK commands. These commands operate identically to the PACK and UNPACK commands, except for using memory records. Unlike a buffer, a memory record must be packed or unpacked from the beginning of the record (i.e., you cannot give MEMPACK or MEMUNPACK a pointer that is an offset into a memory record). This is primarily for validity checking.

With memory records, it is possible to work with structures and linked lists. In essence, the template is a structure definition. By creating templates in which all but one of the data items is skipped, a single data reference is created. Since a memory record pointer is just a number, one or more of the data items in a memory record can be pointers to other memory records. These can either be "P" or "D" types. "P" types take only 4 bytes, but "D" types are actually faster in referencing because conversions do not have to be done internally.

When using memory records, you must pack and unpack the data to be operated on into other variables or buffers. Therefore, moving data from one memory record to another is always a two-step process. For example, moving a pointer from one record to another could be accomplished as follows:

     LOCAL temp

     MEMUNPACK rec1 "P" temp
     MEMPACK   rec2 "P" temp

MEMPACK and MEMUNPACK


Buffer/Memory Templates

Several Project Processing commands take a "template" as a parameter. This template is a specification for how data is organized in a section of memory and includes the characteristics of the data. The following commands use a template:

INTERRUPT | FARCALL
BUFFER | LOW BUFFER
MEMALLOC | LOW MEMALLOC
MEMPACK | MEMUNPACK
PACK | UNPACK
PEEK | POKE

A template is a text string in which characters from left to right represent the formats of fields or pieces of data to be found or stored in a block of memory. The data in the memory is ordered consecutively according to the order of the formats in the template. Some characters in the template also affect data processing in other ways, such as specifying repeat counts or groups of data fields. There will be more on this as you continue.

To understand the relationship of the template to the memory, envision a pointer that points to the next data field to be used. Initially, the pointer starts at the first field in the memory block, which is offset (position) 1. Each format in the template describes something about the type and length of the data at the current pointer position. Depending on the format, some operation is performed on the data field, and then the pointer is adjusted to a new position, ready for the next format. For example, here is the sequence of events for a template of "I:L>IC" used in a PACK operation. Notice that the "I" format stands for an integer, which is 2 bytes long, the "L" format represents a long, which is 4 bytes long, and the "C" for a character, which is 1 byte long:

     PACK var "I,:L,>I,C" exp1 exp2 exp3

+------+
1: | exp1 | <- "I" Packs exp1 into bytes 1 and 2. The pointer
2: | exp1 | moves to position 3.
3: | exp2 | <- ":L" Packs exp2 into bytes 3,4,5, and 6.
4: | exp2 | The pointer doesn't move.
5: | exp3 | <- ">I" Skips pointer +2 to position 5, then
6: | exp2 | the "c" stores exp3 at position 5.
+------+ The pointer moves to position 6, and
the command ends.

Templates are used by the listed commands to control movement of data or to determine the size of a buffer. When data is being moved into a buffer, it is being "packed." The PACK, MEMPACK, POKE, INTERRUPT, and FARCALL commands all involve packing data. In a pack operation, there is an expression supplied for each active data field in the template, and the result of the expression is placed in the corresponding data field in the buffer. This is illustrated below for the template "ICX,4M". The numbers down the left side are the offsets into the packed data buffer.

+----+
1: | | <- "I" ---------- Expression
2: | |
+----+
3: | | <- "C" ---------- Expression
+----+
4: | | <- "X" (unchanged)
+----+
5: | | <- "4M" --------- Buffer Variable
6: | |
7: | |
8: | |
+----+

When data is being moved out of a buffer, it is being "unpacked." The UNPACK, MEMUNPACK, and PEEK commands involve unpacking data. When data is unpacked, there is a variable supplied for each active data field in the template, and the content of the data field is stored in the variable. This is illustrated as follows for the template "ICX,4M". The numbers down the left side are the offsets into the unpacked data buffer.

+----+
1: | | -- "I" ---------> Variable
2: | |
+----+
3: | | -- "C" ---------> Variable
+----+
4: | | <- "X" (unchanged)
+----+
5: | | -- "4M" --------> Variable
6: | |
7: | |
8: | |
+----+

Notice that for unpacking, the "M" format is the same as other formats. In this example, the address of the variable is automatically passed by the compiler.

The BUFFER and MEMALLOC commands each use a template to determine the size of the buffer to allocate. None of the formats refer to active data, but the template is evaluated as if they did, and the highest position in the buffer that would have been stored into or positioned to defines the length of the buffer needed. Note that for this purpose, the "M" and "S" formats using no length prefix are invalid, since there is no actual data for which to determine the length.

BUFFER
FARCALL
INTERRUPT
MEMALLOC
PACK
PEEK and POKE


 There are seven basic and four special template options as identified in the following two tables:

Basic Option | Meaning | Field
B | Byte | A one-byte, signed value from -128 to 127.
C | Character | A one-byte, unsigned value from 0 to 255.
I | Integer | A two-byte, signed value from -32,768 to 32,767.
W | Word | A two-byte, unsigned value from 0 to 65520.
L | Long | A four-byte, signed value from -2147483648 to 2147483647.
P | Pointer | A four-byte, unsigned value from 0 to 4294967295.
D | Double | An eight-byte, double precision, floating point value, +/- E308.


Special Option | Meaning | Field
<#>S | String | With no #, the field is a variable length string. SmartWare packs or unpacks everything up to and including the NULL terminator. If you precede the S with a number, SmartWare transfers up to the specified number of characters or to the end of the string, whichever is shorter. The pointer is always moved the full # field width.
<#>M | Memory (Buffer) | Transfers data to or from a buffer variable. If you do not specify a number, the entire source variable will be moved in a pack operation, or the remainder of the buffer when unpacking. If you precede the M with a number, SmartWare moves the specified number of bytes. When unpacking, the target variable is resized to a buffer variable of the correct size.
Z | Binary Zero | If packing, SmartWare stores a binary zero, or NULL, in a single byte. If unpacking, it acts the same as the X option. This option does not require a corresponding expression.
X | Skip Byte | Skips a single byte.
\? | Literal | If packing, this option stores a single byte containing the character following the backslash. When unpacking, it acts the same as the X option.


There are several modifiers that can precede template options to control the "pointer" movement, group format options, or increase readability.

The pointer refers to the placement of the data in the buffer variable. Initially, the pointer is located at the beginning of the first byte in the buffer variable; as data is stored, the pointer moves to the end of that expression, according to the template used. The pointer's location can be controlled with some of the format modifiers.

Modifier | Meaning | Action
> | Skip | The number of bytes the following format option would use is skipped. There is no corresponding expression or variable if this option is used. >S and >M used with a pack operation is invalid.
# | Repeat | This is used to repeat the following format option a specified number of times (# is any number). This modifier requires the same number of expressions as the number of times the format option is repeated. The S and M options require parentheses to be repeated, e.g., 3(S).
() | Group | Groups the format options together to repeat a sequence. For example, if you wanted to store three pairs of names and ages, you could specify the format expression as "3(SB)". This is the equivalent to typing "SBSBSB".
: | Hold | Causes the pointer to remain in the same position after processing the format following this modifier.


Outside Interfacing

This section is meant to be a brief overview of project commands that can be used to obtain information or to perform actions outside of SmartWare. All of these commands are detailed in the alphabetical command reference following this introduction.

NOTE: References to invalid memory locations: this will produce a core dump in Unix; in DOS, a project protection error message will display the address (segment:offset) of the memory being referenced.

For Unix:

Unix IPC commands. Angoss has a series of Unix project processing commands that allow programmers to utilize the Unix IPC messaging system. See the Unix commands for more information.

For DOS:

IMPORTANT: Each of the commands mentioned in this section is potentially dangerous if misused and can result in loss of data or a failed system. In general, only developers familiar with DOS, BIOS, and the general 8x8xx architecture should use these commands. The use of these commands on one brand of machine is no guarantee that they will work the same way on other machines.

PEEK and POKE. These two commands can be used to access memory outside of the SmartWare system. Both use segment and offset parameters and allow transfer of data from an arbitrary memory location to a SmartWare variable (PEEK), or from the result of an expression to an arbitrary memory location (POKE).

These commands allow you to access the BIOS data area or directly read and write to the screen, although, in general, the SmartWare SCREEN commands will be faster.

PEEK and POKE
SCREEN

INPORT and OUTPORT. These two commands are use to directly read to and write from the hardware ports. INPORT reads a byte from a port, while OUTPORT writes the result of an expression to a port. This is useful for reading the status of a peripheral device.
IMPORTANT: Do not use these commands for operations that require more than one consecutive port access; there is no guarantee that an interrupt will not access the port between successive INPORT or OUTPORT commands. You should use these commands only if you know that no other code could be accessing the port.

INPORT
OUTPORT

INTERRUPT. Access to DOS and BIOS functionality, as well as to any other interrupt routines, is available through the INTERRUPT command. This command allows any software interrupt to be invoked from within a project file. The hardware registers are preset to the appropriate values using the SETREG function. (See Formula Reference Manual for information about SETREG.) It is also possible to pass data on the hardware stack. See the explanation of the INTERRUPT command in the alphabetical command reference for more information.

After the software interrupt is executed, the contents of the hardware registers are saved for access by the GETREG function.

The INTERRUPT command can also be used to access external user-written functionality outside the SmartWare system. A terminate and stay resident (TSR) program can be written that loads its address into an unused interrupt vector. From within SmartWare, this interrupt can be called, and information can be passed to and from the TSR program. By using buffer variables in conjunction with the DOSPTR, DOSSEG, and DOSOFFSET functions, the TSR program can directly read and write information to or from SmartWare variables. Also, it may be possible (though not necessarily practical) to use the MEMALLOC command to allocate a block of memory, then call a TSR that will load a program or overlay into that memory.

INTERRUPT
MEMALLOC

FARCALL. This command is used to directly call a memory location. This command uses the 80x8x CALL FAR instruction. Like the INTERRUPT command, the hardware stack can be set to contain data; however, the registers cannot be pre-initialized. On return from the call the contents of the registers are saved for access by the GETREG function. Because this is a standard assembly-language call, it is possible to use this command to access functions written in C or, possibly, other languages. To do this, you must make the address of the functions available to a SmartWare project file. This could be done by storing the addresses in known memory locations, or using the INTERRUPT command to call code (such as in a TSR) that in turn returns the addresses of the other functions into SmartWare variables.
IMPORTANT: In SmartWare, references to invalid memory locations will be signaled by the error message Project protection error, address ####"####. The address is the segment:offset of the memory being referenced. This can occur from NATIVE PEEK/POKES to invalid addresses, and FARCALLS to non-existent or non-executable memory.

FARCALL
INTERRUPT


Module-Specific Considerations

This chapter contains information you need to know to use PDL effectively within each SmartWare module. The section is divided by application, beginning with SmartWare Communications.


SmartWare Communications

In general, communications projects are used to automate the connection process between two computers. For example, you may call an information service that is prepared to receive your call. When you connect, the remote system may send prompts to which you must respond correctly. After completing the login, you usually respond to options allowing you to perform tasks that might include reading messages, downloading data to your computer, or uploading data from your computer. You can perform these procedures manually, but if they are always the same, you may want to write a project file that recognizes prompts and automatically responds to them.

Certain module commands help you automate the process of connecting to an information service or another computer. These commands are Data Match, Data Get, and Data Output. They recognize information sent to your computer and can send information in response. (Refer to Communications Manual for detailed information about how these commands work.) They are the basic tools you use in communications project files and are capable of more than just establishing a connection; for example, you can use them to move through menus and select files to download to your computer. Once your communications project has done its work, you may want to execute a Database or Spreadsheet project to report on the data that has been downloaded.
NOTE: Project files written to communicate with another computer rely heavily on prompts from that computer. If those prompts change, you have to alter your project files accordingly.


Receiving Data

Data Match and Data Get are used to receive and analyze data sent by another computer. Data Match analyzes data directly. Data Get stores data into a variable that allows other commands to analyze the data and determine the correct response.

Data Match. This command is essential for recognizing prompts. Generally, an information service sends the same prompts every time you attempt to connect. Data Match, followed by a text expression, halts the project file until a specified sequence of characters is received. During the connection process, this sequence of characters represents a login prompt. After the prompt is acknowledged with Data Match, you can respond with the Data Output command.

Data Get. Data Get also receives text from another computer. However, the text is not analyzed but is instead stored in a project variable. This command can be used in conjunction with the project command IF to specify different actions, depending on the contents of the variable. There are two forms of the Data Get command. Data Get Character allows you to store a single character in a variable, whereas Data Get Line stores a full line of text in a variable. It is important that you make sure that your Data Get command receives a character or line at the right moment, or you may not obtain the correct data needed to decide on a response. Use Data Match in conjunction with Data Get to verify that the data is appropriate.


Sending Data

The reverse of receiving data is sending data. During the connection process, you must respond to prompts in order to connect successfully with another computer. Data Output allows you to send information to another computer.

Data Output. This command allows you to respond to prompts sent from another computer. You may send regular text or control codes, such as carriage returns and line feeds, with this command.

Consider the following example. A national computer industry periodical provides an information service to its readers. In addition, readers can interact by leaving messages for one another. The login procedure requires a name and password. After login, a message informs the caller about any new messages, and a menu of choices appears. Usually, "m" is selected from the menu to display newly received messages. Then the caller presses {Enter} to display information on additions or changes that have occurred at the service.

     Set-Terminal Settings Load "infoserv.ucp"
     Connection Dial Carrier Number "1-800-123-4567"

     Data Match "Enter your login name:"
     Data Output "dominicp"|CHR(13)

     Data Match "Enter your password:"
     Data Output "xyzzy"|CHR(13)

     Data Match "New messages:"
     Data Get Line Variable $message
     IF $message = "Yes"|CHR(13)
       Data Output "m"
     ELSE
       Data Output CHR(13)
     END IF
NOTE: Data Output does not send a carriage return at the end of the specified string, so to send one, you must concatenate an ASCII 13 to your output string using the concatenation operator | and the CHR function.

The first line of this project loads the communications profile with the proper settings to connect to the information service. The next line dials the number of the service. (See Communications Manual for descriptions of these commands.) The first Data Match command begins the login procedure by pausing until the exact text specified in the command is received. Once the login prompt is received, the project continues by sending the login name "dominicp" and a carriage return using the Data Output command. Similar Data Match and Data Output commands are used to respond to the password prompt. The Data Output command sends the user's login password "xyzzy" plus a carriage return to the information service to complete the login process.

Next, the information service sends the "New messages:" text, followed by either Yes or No and a carriage return. This text acts as a flag to the next Data Match command. After the third Data Match command is completed, the remainder of the text being sent from the information system is stored in the variable $message using the Data Get Line command. The Data Get Line command will store all characters received until a carriage return is encountered. Then, the value of $message is analyzed and one of two actions is taken. If the value stored in $message is "Yes"|CHR(13), the letter "m" is sent, without a carriage return, to the service to activate the menu of new messages. Otherwise, a carriage return is output to the service to indicate that the user wants to continue to the additions and changes information.

Two other project commands are useful for sending data. The Empty command can ensure that all characters have been transmitted by pausing the project until the transmit buffer is empty or a {Ctrl} {Z} is pressed or until three minutes have elapsed.

The Break-Key command simulates pressing the key defined to be the Break Key in the current profile setting.


SmartWare Database

Database projects allow you to automate almost any data management task. You can write projects that completely control the user interface or that run completely unattended.

In addition to the module commands described in Database Manual, several other module commands are used in project files. This section describes these commands.

File Load Exclusive. In a multi-user environment, File Load Exclusive loads a view and grants you exclusive rights to the view and all of its associated data-files. Other users are prevented from loading the view or any of its data-files until you unload it. This may allow you to write simpler, faster projects because you will not have to lock individual records. In a single-user environment, the command has no effect.

To load a file exclusively, use either of the following commands:

     File Load Custom-View "view-name" Exclusive
     File Load Standard-View "view-name" Exclusive

If someone else is currently using the file, an error message will be generated, and you will not be able to load it.

Files must be held exclusive to perform operations such as rebuilding, or adding or deleting keys. If you are performing any of these functions in your project file, you must load the file exclusively. Loading a file exclusively also makes all key buffers available to you on that file for operations such as Browsing, Finds, or Updates.

Data Enter Blank. Data Enter Blank adds a new record to the current view and makes that record the current record. This command is more useful than Data Enter in project files because it does not access Enter/Update mode. Counter fields are updated automatically, but the newly added record will have a value of BLANK in all other fields. Data Enter Blank is typically followed either by Data Update Only-One or by a sequence of assignments that fill in the fields.

Data Enter Lock. Data Enter Lock adds a new record to the current view, but leaves it in a locked state. Used in project processing, it allows the adding of records approximately twice as fast as Data Enter Blank and Lock-Record. Data Enter Lock is typically followed by field assignment statements, then Write-Record.

Data Enter Only-One. Data Enter Only-One allows you to limit a data entry session to one new record. This command is similar to the Data Update Only-One command.

Data Update. Data Update accesses Enter/Update Mode until the user presses {Esc} and then resumes project execution.

Data Update Only-One. Data Update Only-One allows the user to interactively update the current record. This command is more useful than Data Update because it prevents the user from changing data in records other than the current record. This command is similar to the Data Enter Only-One command.

Example. The following example illustrates how to find a name in a view, add the name if it is not found, and then update the record.

     PUBLIC last_name
        _' get input from user
     SCREEN SHORTINPUT last_name "Enter last name:  "
        _' look for name

     Data Find [last name] Equal last_name Options "gi"

     IF CERROR
        _ ' not found
     Data Enter Blank
        _' create new record
     [last name] = last_name
        _' initialize name
     END IF

     Data Update Only-One
        _' let user update

Recalc. Recalc causes all calculations in the view to be evaluated. Normally, you will use Recalc after updating a record.

Lock-Record. In a multi-user environment, Lock-Record grants you exclusive update rights to the current record. Unlike File Load Exclusive, other users can still read the record, but they are prevented from making any changes. The record is unlocked when the project encounters Write-Record, Cancel-Record, or any command that changes the current record position.

Lock-Record is required before making assignments in a multi-user environment. It has no effect in a single-user environment or when you load the file with the Exclusive option.
NOTE: In a multi-user environment, Lock-Record does allow several assignments to be made at once in an update. In a single-user environment, an update is pending in memory until you make an assignment. In either case, the transaction ends when you use Write-Record, Cancel-Record, or any command that changes the current record position.

Write-Record. Write-Record writes the current record to disk, committing all changes to the record. It then unlocks the record.

Cancel-Record. Cancel-Record unlocks the current record but also cancels all changes made to the record since an update began on that record. Cancel-Record is used to abort an update and delete any changes made. On a network, Cancel-Record releases the record so it can be accessed by other users.
NOTE: When you begin updating, the update may fail for a number of reasons. An assignment can fail if a field is read-only, if it is a mandatory-entry field and you assign BLANK, or if it has an error-check rule that fails. You can use Cancel-Record in any of these situations. Anytime an assignment fails, CERROR and LERROR are set to an appropriate error code. See Formula Reference Manual.

Example. The following example shows how Lock-Record, Write-Record, and Cancel-Record can be used to create a transaction. It updates a record in the "chart" view from a record in the "stock" view. Failure of any command or any assignment will set LERROR, and the transaction will fail.

     CLEARERROR
        _' clear LERROR

     Data Goto View "chart.vws"
        _' put "chart" in the current window

     Lock-Record
        _' start a transaction in "chart"

     [chart.Date] = [stock.Date]
        _' make all assignments
     [chart.Open Quote] = [stock.Open Quote]
     [chart.Close Quote] = [stock.Close Quote]
     [chart.High Quote] = [stock.High Quote]
     [chart.Low Quote] = [stock.Low Quote]

     IF LERROR
        _' did anything fail?
       Cancel-Record
        _' yes, transaction fails
     ELSE
       Write-Record
        _' no, transaction succeeds
     END IF

Data Goto Record First/Last. These commands make the first or last record the current record. They are especially useful when you want to process records in key order. In key order, Data Goto Record First will go to the first record in the key order, whereas Data Goto Record Record-Number 1 will go to the record with a physical record number of one.

Example. This example will evaluate calculated fields on all records in the current order, regardless of whether they are in physical, key, or index order. Data Goto Record First and Data Goto Record Next always work within the current order; however, while RECORD will return physical record numbers in key order, it will always return one more than the number of records in the order when the end of the order is reached.

     Data Goto Record First
        _' go to first record

     WHILE (RECORD <= RECORDS)
        _' test for end of order
       Recalc
        _' evaluate calculated fields
       Data Goto Record Next
        _' go to next record
     END WHILE

Data Goto Record Next/Previous View. These commands affect the current record position in the specified view. This allows you to position views that are not in the current window. These commands are faster and more convenient than series of Data Goto Window and Data Goto Record commands.
NOTE: The specified view name must include the extension of .VW or .VWS.

Data Goto Window Next/Previous. These commands make the next or previous window the current window. They perform the same functions as {Alt} {F7} and {Alt} {F8} do interactively.

Data Goto Line number. Data Goto Line number allows you to type a number representing the line you wish to go to. SmartWare will scroll the view vertically so that the line, the number of which you have specified, is on the screen. It can be used to position the view so that the user sees a particular portion of the view. The command has no effect if the entire view fits on the screen.

Data Delete. Data Delete Yes and Data Delete No allow you to set the delete status of the current record regardless of its current delete status. That is, Data Delete Yes will always mark the current record as deleted, and Data Delete No will always make the current record active. Sometimes these commands are more useful than Data Delete because Data Delete switches, rather than sets, the delete status. For details on the behavior of Data Delete in multi-file views, see the section on Edit Links in Database Manual.

Quit Database. Quit Database is available as a way of restarting SmartWare Database. It unloads all files, closes all windows, and in some cases, frees memory that would otherwise be unavailable. It also stops execution of any project file. The following formats are available:

     Quit DataBase Project-File project filename
     Quit Main-Menu Project-File project filename
     Quit Spreadsheet Project-File project filename
     Quit Wordprocessor Project-File project filename
     Quit Communications Project-File project filename

The Project-File option starts the specified project file as soon as the new application is entered. This option allows you to create integrated projects that move smoothly from module to module.

Field prompt. The field prompt commands each display the standard field prompter used within SmartWare Database. There are two field prompt commands:

     field  prompt  target  <help>

The first field prompt command allows the user to select a single field to be returned to the target.

     field  prompt  multiple  target  <help>

The field prompt multiple command allows the user to select a field string to be returned to the target.

The target is a Project Processing variable; the optional help string will appear in standard colors on the Status Line of your screen.

For more information about field prompters, refer to Database Manual.


Referencing Database Fields

In addition to Database-specific commands to consider when creating or executing projects, there are also some things to remember about referencing fields in project files.

First, if you have used the TRANSLAT.EXE utility to convert a SmartWare 3.10 project file to SmartWare format, make certain that all Database fields previously referenced by number are now referenced by field name. If you do not reference the fields by name, the converted project file may not operate correctly in SmartWare. For more information about converting files, refer to Release Notes.

Finally, remember that data is stored in Database inverted fields in the form in which it was entered. For example, if "John Smith" was entered into an inverted field, any Project Processing commands or formulas that reference this field will return "John Smith," not "Smith, John." This is a change SmartWare 3.10. The data will be inverted when the view is ordered by fields, so "John Smith" will be sorted with the S's, not the J's.


Serial Processing

The RECORD and PRECORD functions, as documented in Formula Reference Manual, return the current logical and physical record numbers in a view. In project files you can use these functions plus some added keys to construct loops that permit the serial processing of multiple records.

If the current record is the last record in the view and you use {F6} or {Down} in a standard or browsed view only, or you execute Data Goto Record Next, to advance beyond the last record, RECORD and PRECORD return a value 1 greater than the number of (logical) records in the view. For example, when you have 200 records in a view and you move to the last record, RECORD and PRECORD return the value 200. If you then press {F6} or {Down}, or execute Data Goto Record Next, RECORD and PRECORD return the value 201.

If you are working interactively with the Database when you do this, you will also notice that the code EOF appears in place of the physical record number (in parentheses) on the Status Line. This signals that the end of the file has been reached.

You can use this feature to facilitate loop and recursive processing in project files. For example, suppose that you want to create a project that executes Print Current-Record View All for every record in a view. The project file might look like this:

     Data Goto Record First

     WHILE RECORD <= RECORDS
        Print Current-Record View All
        Data Goto Record Next
     END WHILE

This project begins at the first (logical) record and moves serially through the file, printing each record. When it reaches the last record, the WHILE condition remains true; that is, the current record number is still less than or equal to (in this case, equal to) the value returned by the function RECORDS. (RECORDS returns the total number of logical records in the view.) Because the condition is still true, the record is printed and the project once again attempts to advance to another record (Data Goto Next). This is impossible because you have reached the last record. However, the attempt to advance causes the value returned by RECORD to be increased by one. When the WHILE condition is again evaluated, the value RECORD is again compared to RECORDS. This time the condition is false because RECORD returns a value 1 greater than that returned by RECORDS, so the WHILE loop is not repeated.


SmartWare Spreadsheet

This section describes project-specific information about SmartWare Spreadsheet. Refer to Spreadsheet Manual for explicit instructions on how to mark blocks in a worksheet. Also, keep in mind that if you use external worksheet references in your project file, they must be active when you compile or an error will result.


BLOCKMARK Function

The BLOCKMARK function, used only within project files, is used to specify a block of cells in the current worksheet. To use this function, you must first assign a variable with the value of BLOCKMARK, as follows:

     LOCAL block
     block = BLOCKMARK

Once this variable assignment is encountered, the worksheet is displayed, and you can then press {F2} to drop anchor and define a block. After the block is defined, the variable contains a string that defines the location of the block.

This variable containing the block location string can be used as an expression for commands such as Edit Copy From, where you must specify one or more blocks. You can also use this variable as an argument to a function, but you must concatenate it into a string containing that function, as follows:

     Enter Formula "SUM("|BLOCKMARK|")"

You cannot use BLOCKMARK directly in a formula or use the result of BLOCKMARK as an argument representing a range or block to another function. For example, you cannot use the formula

     total = SUM(BLOCKMARK)


Specifying Worksheet Locations

This section describes how to specify cursor movement and placement. For various procedures in SmartWare Spreadsheet (copying, entering data, etc.) the cursor must be located at the appropriate cell before the command is executed. Locate the cursor by use of:

     at rxcy

where rx is the row number and cy is the column number of the cell in which you want to place the cursor. This command must occupy a line by itself; commands that refer to the new cell location follow on subsequent lines. Consider the following project commands:

     at r10c3
     Edit Copy Right Single-cell Copies 1

The first line moves the cursor to the cell at row 10, column 3. The second line copies data from the current cell into the cell immediately to the right.

When you build a project file in Remember Mode, the program automatically includes the cursor address for commands in which the cursor location is necessary.

Sheet Goto. You can also specify cursor movement using various Sheet Goto commands. The four "Edge" options and the actions produced are as follows:
*** Sheet Goto Upper-Edge moves the cursor within its current column to the highest row in which data could be entered.
** Sheet Goto Lower-Edge moves the cursor within its current column to the lowest row in which data has been entered.
** Sheet Goto Right-Edge moves the cursor within its current row to the right-most column in which data has been entered.
** Sheet Goto Left-Edge moves the cursor within its current row to the left-most column in which data has been entered.

The four Sheet Goto "Next" options are as follows:
*** Sheet Goto Next-Left
** Sheet Goto Next-Right
** Sheet Goto Next-Up
** Sheet Goto Next-Down

Each "Next" option moves the cursor in the indicated direction according to the following rules:
1. If the cursor is on a blank cell, it moves in the specified direction until it finds a cell containing data. The cursor is placed on this filled cell.
2. If the cursor is on a filled cell, and the next cell in the specified direction is filled, the cursor moves in the specified direction until it finds a blank cell. The cursor is placed on the filled cell preceding this blank cell.
3. If the cursor is on a filled cell, and the next cell in the specified direction is blank, the cursor moves in the specified direction until it finds a filled cell. The cursor is placed on this filled cell.

You can use the "Next" options to control cursor movement and placement based on the structure of your worksheet. The series of filled and blank cells can define a path over which you can move the cursor.

Cursor. To move the cursor to the left, right, up, or down on the worksheet, use the Cursor command in the following format:

     Cursor direction

The direction can be Left, Right, Up, or Down. A Cursor direction command moves the cursor one cell from the current cell in the specified direction.


Entering Worksheet Information

There are two ways to enter worksheet information into a cell. Information can be entered directly, or it can be entered indirectly by use of the LET function and variables.


Direct Entry

While SmartWare is in Remember Mode, if you enter information into a cell in SmartWare Spreadsheet, the following prompt appears:

     Is data to be recorded in command file? (y/n)

If you answer Yes to record the information, the same information now entered also will be entered in the cell when the project is executed. In this case, commands in the following format might be stored in the project file, as follows:

     at rxcy
     Enter type  cell-entry

The type parameter can be Value, Text, Formula, Date1, Date2, Date3, Time12, or Time24 to specify the format in which you want to display the entered information. The coordinates rxcy represent the cell where information is entered, and the cell-entry is the information you actually enter into the cell.
NOTE: Notice that text to be entered into a cell must be enclosed in quotation marks. Embedded quotes must be doubled.

Example:

     at r1c1
     Enter Text "Greenleaf Inc. Income Statement"

If you choose not to record information by answering No, you may enter a prompting message. During project execution the project will pause at this cell, display the prompting message you entered, and wait for an input from the project operator. In this case, commands in the following format might be stored in the project file, as shown here:

     at rxcy
     Cursor prompt

The cell rxcy is where the operator's response will be entered, and prompt is the prompting message displayed when the project pauses.

Example:

     at r1c1
     Cursor "Enter the current year"

Another variation of the Cursor command allows you to specify additionally that the operator enter information in a format you designate. The complete format is as follows:

     at rxcy
     Cursor type  prompt

The type parameter can be Value, Text, Formula, Date1, Date2, Time12, or Time24 to specify the format of operator-entered information into the cell. The coordinates rxcy represent the cell into which information is entered, and the prompt is the prompting message displayed when the project pauses.

Example:

     at r1c5
     Cursor Value "Enter the weekly wage"


Indirect Entry

There are several methods available for entering information indirectly into a cell. You can use LET in conjunction with variables, as shown in the following example:

     LET r4c8 = $fee
        _OR
     LET $fee = r4c8

You can assign data to variables using the SSGET function, which retrieves information from a specified cell. The format for this would be:

     variable = SSGET(<"worksheet",>row,column)
NOTE: Use the LET assignment if the locations of the source and destination will be constant or if you are using external references. Use SSGET if the source or destination are likely to change.

The worksheet item refers to an external worksheet, and it is optional. If no worksheet is specified, the current worksheet is assumed. The row and column items specify the cell from which information is retrieved. Moreover, in this format any of the items can be expressed as formulas and/or variables. An example of this is:

     $fee = SSGET("Budget",4,14)

This example specifies that the information located at row 4, column 14 of the worksheet named Budget be placed in variable $fee.

Another way to enter information indirectly is by using the SSPUT function, which places information into a specified cell. The format for SSPUT is:

     SSPUT(data,<"worksheet",>row,column)

The worksheet item refers to an external worksheet and is optional. If no worksheet is specified, the current worksheet is assumed. The row and column items designate the cell into which the information specified by the data item is entered. Any of these items can be expressed as formulas and/or variables. An example of this is:

     SSPUT(32.48,$row,23)

This example specifies that the value 32.48 be placed at the row whose number is stored in the variable $row and at column number 23.


Worksheet Recalculation

In the SmartWare Spreadsheet, pressing {F5} recalculates as many formulas as necessary to update the worksheet. When you press {F5} while in Remember Mode, the command format Recalc is entered into the project file to specify the recalculation. When creating or editing a project file with an editor, you can use the command format Recalc wherever you wish a worksheet recalculation to occur during project execution.

The ISCALC function allows you to determine if the current worksheet has been modified since the last recalculation. ISCALC returns true (a value of 1) if the worksheet needs to be calculated and false (a value of 0) if it does not.


Locking and Unlocking Cells

In a project file, to specify that a cell be locked, use the SSLOCK command format:

     at rxcy
     SSLOCK CELL

where rxcy is the cell to be locked.

To specify that a cell be unlocked, use the following format:

     at rxcy
     SSUNLOCK CELL

where rxcy is the cell to be unlocked. To specify that all blank cells be locked, use SSLOCK BLANKS; to specify that all blank cells be unlocked, use SSUNLOCK BLANKS.


SmartWare Word Processor

This section describes project-specific information about SmartWare Word Processor, such as marking text, editing rulers, editing MCA rulers, and using various toggle commands.


Marking Text

Frequently, Word Processor commands affect a portion of text that must be marked. (For specific information about marking text, refer to Word Processor Manual.) When interactive marking must occur from within a project, the following keywords can be used to pause the project and prompt the user to mark the desired text.

Block, Column, Lines, and Point. These keywords indicate which portion of text will be marked. The selected marking "mode" can sometimes be toggled, as is possible when the commands are selected from the menu. Point is valid only as a destination marker and signals SmartWare Word Processor to prompt the operator to move the cursor to the desired location.

The following table shows the SmartWare Word Processor commands that require or use text marking and the marking keywords each accepts.

Block, Column, and Point | Edit Copy block/column To point Edit Move block/column To point
Block and Column | Edit Delete Edit Replace Document Find File Export Layout Font Change
Block | Document Dictionary Spellcheck Document References Index Add Document References TOC Add Layout Hidden-Text Add Layout Ruler Reformat
Column | Edit Sort Text
Lines | Document Dictionary Hyphenate Layout Keep Insert

In addition to those keywords that can be used to mark text interactively, the following keywords can be used to specify text without pausing the project. Because the text to be marked is a predefined area, such as a sentence or paragraph, there is no need for interactive response from an operator.

Word, Sentence, Line, Paragraph, Remainder, and Document. These keywords can be used with any of the commands for which Block can be used as a marking option. They are used to mark the appropriate portion of text at the current cursor position.

* (Star). The star is a destination marker that can be used wherever Point can be used. The * denotes the current cursor position.

[] (Brackets). Brackets can be used only with the Edit Copy and Move commands and are used to specify use of the copy buffer contents. Brackets can be used to specify either the source or destination.

Finally, you can specify from within a project file the exact location of text to be affected by a command. Wherever the Block, Column, and Lines keywords can be used you can also use an "absolute" specification with the following format:

     keyword:s#.#.#.#:s#.#.#.#

The keyword represents either Block, Column, or Lines, and the first four number signs (#) represent the section, page, line, and column or position numbers of the first character to be included in the marked text. The last four number signs represent the section, page, line, and column or position numbers of the last character (for a Column mark) or of the character immediately following the last character (for a Block mark) of the text to be marked.

In addition, the star (*), specifying the current cursor position, can be used as part of the marking specification. For example, Blocks:s1.2.10.5:* indicates that the block begins at section 1, page 2, line 10, column 5 and includes all the characters from that anchor to the current cursor position.


Ruler Editing

In addition to specifying marked text within a project, you can also control changes to the ruler by including the appropriate Layout Ruler commands, which require a string of control codes to change ruler settings. These commands include:

     Layout Ruler Edit Current changes
     Layout Ruler Edit Default changes
     Layout Ruler Edit Named changes
     Layout Ruler Insert Current changes
     Layout Ruler Reformat mark-specification  changes

In these command formats, changes represents the string specifying the desired format change. This string can include the following components:

l# | Set left margin at #, where # is in inches.
r# | Set right margin at #, where # is in inches.
i# | Set first line indent to #, where # is the number of inches from the left margin to indent (if # is > 0) or outdent (if # is < 0) the first line of the paragraph.
ntab(#) | Add a normal tab stop at position # (in inches) on the ruler line.
dtab(#) | Add a decimal tab stop at position # (in inches) on the ruler line.
cpi# | Change the displayed cpi of the ruler to # characters per inch.
ninc# | Add normal tab stops every # inches on the ruler line.
dinc# | Add decimal tab stops every # inches on the ruler line.
clear(#, #, ... ) | Clear the tab(s) at the specified inch positions.
clear(*) | Clear all tabs on the ruler line.
name(string) | Give the specified ruler format the name represented by the string. The name can include from 1 to 8 characters.


MCA Ruler Editing

It is also possible to define and edit columns by including the appropriate Document command followed by a string specifying starting and ending positions in inches. The start and end values are separated by a dash, while values for each column are separated by a comma or a space, as follows:

     Document Columns Define Linked "0.5--2.5, 3.0--4.5, 5.0--6.0"

A similar string must be included after Document Columns Edit Boundaries and Document Columns Edit Add Column commands. If you are adding a column or editing column boundaries, you must include each column in order.

Document Columns Edit Move and Document Columns Edit Delete require MCA marking specifications, as follows:

     entry:#:#
        _OR
     column:#:#

In this format, the number signs (#) before and after the colon represent the first and last entries or columns to be marked. Document Columns Edit Move also requires a destination, which is simply a number representing an entry or a column.

In addition to these special Word Processor commands, you should refer to Formula Reference Manual for information about Word Processor-specific functions, such as WPGET, WPINFO, and WPPUT.


Toggle Commands

The toggle commands have optional keywords that can be used in a project file to force the toggle status. The following list of these commands includes only those command formats that can be used in a project. The menu commands simply do not include On or Off, or in the case of File File-Type, Text or Document.

     Document Visible Hidden-Text On/Off
     Document Visible Marks All On/Off
     Document Visible Marks Hidden-Text On/Off
     Document Visible Marks Index On/Off
     Document Visible Marks Keep On/Off
     Document Visible Marks TOC On/Off
     Document Visible Newpage On/Off
     Document Visible Paragraphs On/Off
     Document Visible Rulers Main On/Off
     Document Visible Rulers Embedded On/Off
     Document Visible Tabs On/Off
     File File-Type Text/Document
     Layout Newpage Automatic On/Off
     Window Border On/Off


AUTOHELP

Type: Command
Scope: All
Formats:

     AUTOHELP ON
     AUTOHELP OFF

The AUTOHELP command controls the display of the Autohelp Line. AUTOHELP ON enables Autohelp; AUTOHELP OFF disables it.

Whether Autohelp is on or off at the beginning of project execution is determined by how global preferences are set. Preferences are selected using the Tools Preferences Global command. The AUTOHELP command overrides the Autohelp setting on the Global Preferences menu. Any change to the Autohelp setting during project execution remains in effect after project execution is complete.


BEEP

Type: Command
Scope: All
Formats:

     BEEP
     BEEP ON
     BEEP OFF
     BEEP numeric <message>

The BEEP command has three functions. Used without any parameters, BEEP produces a single tone. Used with the ON or OFF parameter, it can enable or disable the error and warning sounds produced by SmartWare. Used with the optional numeric expression and message parameters, it can produce a specified number of audible tones and display a message.

The numeric expression evaluates to the number of times the computer beeps. The message, if included, can be a text or numeric expression. If the expression is numeric, it is converted to text.

Whether BEEP is on or off at the beginning of project execution is determined by how global preferences are set. Preferences are selected using the Tools Preferences Global command. The BEEP command overrides the Beeper setting on the Global Preferences menu. Any change to the Beeper setting during project execution remains in effect after project execution is complete.


BIGOS

Type: Command
Scope: All
Formats:

     BIGOS  <command>

BIGOS is equivalent to the Tools OS module command in that you can execute operating system commands without exiting SmartWare.

Once BIGOS is executed in a project file, the project is suspended and you can execute operating system commands. To return to SmartWare and resume project execution, type exit at the operating system prompt. You can also include an optional operating system command in the command syntax; this will immediately execute the operating system command and then automatically return to SmartWare.


BUFFER

Type: Command
Scope: All
Formats:

     BUFFER variable SIZE number of bytes
     BUFFER variable SIZEOF template

The BUFFER command is used to allocate a buffer and attach it to a variable. Buffer variables are used with a number of Project Processing commands. Refer to the Project Processing Manual for more information about buffer variables. Also, see the discussion of the LOW BUFFER command.

There are two formats for using the BUFFER command. The number of bytes to be allocated is specified using the SIZE option and a numeric expression. The number of bytes represented by the numeric expression cannot be zero.

The second format is used to allocate a buffer large enough to contain a structure defined by a template. All data items in the template must be explicit, that is, no S (string) or M (memory) types can be used that do not include a length parameter. Refer to the Project Processing Manual for more information about templates.

The current contents of the variable are replaced with the allocated buffer.

The BUFFER command will return the address of a native memory buffer.

You may also copy one buffer to another and use it with a function, as shown in the following example:

     BUFFER  var SIZE 10

     var1 - var      'var1 contains copy of buffer in var
     myfunc(var)     'copy of buffer is passed to function

Buffer variables


BUTTON

Type: Command
Scope: All

A button is a specified area on the screen that, when clicked with the mouse, returns a designated keystroke. Since this keystroke is added to the keyboard buffer, applications that use buttons can be driven by the keyboard or mouse equally well. Typically, programmers create a type of menu that contains a set of buttons.

The BUTTON commands facilitate the creation, management and deletion of buttons. Generally, each button has the following attributes: screen coordinates, fg and bg colors, text, and a designated keystroke.

A set of buttons is initiated with the BUTTON INIT command. This will:

* Save and deactivate any existing buttons
* Open a set of 0 buttons and place it on the stack

After creating and displaying a button set, the INCHAR function can then be used to determine the appropriate program branch, just as if you were checking for keystrokes. When done with a button set, issue the BUTTON FINISHED command. This will:

* Free memory associated with the button set and remove it from the stack
* Restore the previous buttons

Example:

This example uses a variety of BUTTON commands and is meant to provide a general overview of BUTTON usage. Each BUTTON command is described in detail in the pages following this example.

     MAIN
        BUTTON INIT 0 15
        BUTTON CREATE AUTO-SIZE scrheight-3 1 {F5} "Next Record"
        BUTTON CREATE AUTO-SIZE scrheight-2 1 {F6} "Prev Record"
        BUTTON CREATE AUTO-SIZE scrheight-2 20 {Esc} "ESC-Finished"
        SCREEN CLEAR BOX scrheight-3 1 scrheight-1 scrwidth 15 0 NO-BORDER
        BUTTON DRAW ALL
        WHILE TRUE
           CASE INCHAR
              WHEN {f5}
                 DATA GOTO RECORD NEXT
              WHEN {F6}
                 DATA GOTO RECORD PREVIOUS
              WHEN {esc}
                 EXIT WHILE
           END CASE
        END WHILE
        BUTTON FINISHED
     END MAIN


BUTTON CHANGE-COLOR

Format:

     BUTTON CHANGE-COLOR fg bg key

This command changes the foreground and background colors of an existing button. The key parameter determines which button is affected.


BUTTON CREATE

Formats:

     BUTTON CREATE AUTO-SIZE row col key message
     BUTTON CREATE AT row1 col1 row2 col2 key message
     BUTTON CREATE XY x1 y1 x2 y2 key

These commands create buttons, with all the required attributes except color, but do not draw them on the screen. A BUTTON CREATE command determines the position, size, keystroke, and displayed message (usually) for a single button. Typically, multiple create commands are used to build a button set.

BUTTON CREATE AUTO-SIZE uses the message length to determine its size. To specify a button size, ignoring the message length, use BUTTON CREATE AT instead. If the screen is in graphics mode, BUTTON CREATE XY is required to position the button with x,y graphics coordinates. Note that, where commands use a pair of coordinates, these refer to the top left and bottom right corners.

The key parameter determines the keystroke placed in the keyboard buffer when a button is clicked or the appropriate key is struck. While there are a variety of ways to specify this value, a key constant is the best method; for instance, if the button should return the Alt-G sequence, use: {Alt-G}.

The message parameter is a text string that is displayed in the button area. Multi-line buttons can be created by using the tilde (~) as a new line indicator. Vertical and horizontal justification can be achieved by using spaces and tildes.


BUTTON DEFAULT-COLOR

Format:

     BUTTON DEFAULT-COLOR fg bg

This command sets the foreground and background colors of any buttons created after BUTTON DEFAULT-COLOR has been executed. You can assign a different color to every button by setting its default colors before issuing each BUTTON CREATE command.

Note that, in many cases, this command will not be necessary since BUTTON INIT sets the initial default colors.


BUTTON DELETE

Formats:

     BUTTON DELETE ONE key
     BUTTON DELETE ALL

BUTTON DELETE ONE removes the button specified by the key parameter. BUTTON DELETE ALL removes all buttons within a set but does not deactivate that set.


BUTTON DRAW

Formats:

     BUTTON DRAW ONE key
     BUTTON DRAW ALL

BUTTON DRAW ONE displays the button specified by the key parameter. BUTTON DRAW ALL displays all buttons within a set. Note that buttons must first be defined by the BUTTON CREATE commands.


BUTTON FINISHED

Format:

     BUTTON FINISHED
     BUTTON FINISHED ALL

The BUTTON FINISHED command completes a button set and removes it from the stack. This frees up memory associated with the button set, and restores the previous set. See the BUTTON INIT command.

The BUTTON FINISHED ALL command removes all button sets from the stack. Note that this command is issued by the system when a project file has been cancelled or a module change is performed.


BUTTON INIT

Format:

     BUTTON INIT fg bg

The BUTTON INIT command creates a new button set (with no buttons) and temporarily deactivates any existing buttons. The fg and bg parameters determine the default colors for the BUTTON CREATE commands. See the BUTTON FINISHED command.


BUTTON PAUSE

Format:

     BUTTON PAUSE

This command causes the current button set to be suspended. Buttons will not be painted to the screen nor will they generate keystrokes. To reactivate, use the BUTTON RESUME command.


BUTTON RESUME

Format:

     BUTTON RESUME

This reactivates a button set suspended by the BUTTON PAUSE command.


CASE

Type: Statement
Scope: All
Format:

     CASE <expression>
     WHEN expression
     commands
     WHEN expression
     commands
     <OTHERWISE>
     <commands>
     END <CASE>

The CASE statement evaluates an expression and directs the project file to execute a set of commands determined by the result of the expression.

A CASE structure can include a text or numeric expression, one or more WHEN statements, and an optional OTHERWISE statement. A WHEN statement includes the keyword WHEN followed by an expression or a condition. You can include any number of commands after each WHEN statement or after the OTHERWISE statement.

The CASE structure is terminated by the END CASE statement. Including CASE after END is optional; however, adding it makes it clear that it is the CASE statement that is complete, since END is also used in other statements in the SmartWare Programming Language.

The keyword CASE may or may not be followed by an expression. If you use a CASE expression, it is evaluated first. Then, each WHEN expression is evaluated in the order in which it occurs. The commands following the first WHEN expression that matches the result of the CASE expression are executed. If no match occurs and the OTHERWISE keyword was included, the commands following OTHERWISE are executed. If no match occurs and OTHERWISE was omitted, execution continues following the END CASE statement.

If you do not include a CASE expression, the first WHEN expression that evaluates to any value other than zero (true) is executed. If all WHEN expressions evaluate to zero, control is passed to the OTHERWISE statement.
NOTE: Regardless of how you construct a CASE statement, only one group of WHEN commands is executed.

Using an expression after CASE is most useful when you want to evaluate a discrete condition, that is, when it is feasible to list each value. Using CASE without an expression is most useful when you must evaluate conditions that occur over ranges. The following examples illustrate both uses of a CASE statement.

Example:

Expression After CASE

CASE (weight)
WHEN 1
shipping_cost = 1.00
WHEN 2
shipping_cost = 1.00
WHEN 3
shipping_cost = 1.00
WHEN 4
shipping_cost = 2.00
WHEN 5
shipping_cost = 2.00
WHEN 6
shipping_cost = 2.00
OTHERWISE
shipping_cost = 3.00
END CASE

No Expression After CASE
CASE
WHEN (weight <= 3)
shipping_cost = 1.00
WHEN ((weight > 3) AND
(weight <= 6))
shipping_cost = 2.00
OTHERWISE
shipping_cost = 3.00
END CASE

There can be certain conditions affecting flow of the program that you should consider. If a match cannot be found for the CASE expression, and an OTHERWISE statement is not included, no commands will be executed within the CASE structure, and the project file will continue executing after the END CASE statement.

If you wish to immediately abandon execution of a CASE structure, you can use the EXIT CASE command. This command causes project control to pass to the statement following END CASE.

Using the CASE statement can save you time and make your project more legible. Although the decision and branching capabilities of CASE can be reproduced using the IF command structure, it is easier to use the CASE statement.

Example. The variable $acct_number contains an account number in the format ###-##-A##, where # represents a single digit and A represents a single letter X, Y, or Z. Different sets of commands will be executed based on this code. In order to achieve the branching necessary to execute the proper set of commands with an IF structure, you have to use the ELSEIF statement. The MID function is used to extract the letter from the account number variable as part of a logical expression that is repeated in each IF statement, once for each of the three possible letters.

     $acct_number = "123-45-X67"
     IF MID($acct_number,8,1) = "X"
     MESSAGE "Letter X commands"
     ELSEIF MID($acct_number,8,1) = "Y"
     MESSAGE "Letter Y commands"
     ELSEIF MID($acct_number,8,1) = "Z"
     MESSAGE "Letter Z commands"
     ELSE
     MESSAGE "Incorrect letter commands"
     END IF

The same branching can be accomplished in a clearer, more readable format with a CASE structure. The expression that extracts the letter is entered only once, as the CASE expression. The WHEN statements contain only the letters that could be used; the long expression does not have to be repeated.

     $acct_number = "123-45-X67"
     CASE MID($acct_number,8,1)
     WHEN "X"
     MESSAGE "Letter X commands"
     WHEN "Y"
     MESSAGE "Letter Y commands"
     WHEN "Z"
     MESSAGE "Letter Z commands"
     OTHERWISE
     MESSAGE "Incorrect letter commands"
     END CASE


CLEAR

Type: Statement
Scope: All
Format:

     CLEAR list

Variables and arrays can be set to zero with the CLEAR project command. Only the contents of the variable or array are affected; the variable or array is not undefined.

The list may contain variable names, array names, or special keywords, which are described below. Items in the list may be separated by a comma or a space.

Variable names must be entered into the list just as they were declared. Array names should be entered into the list with a pair of trailing brackets to indicate the variable being cleared is an array. However, do not include array dimension information within the brackets. Examples of array entries include salaries[], zip_codes[], and stocks[].
IMPORTANT: When you clear an array, all elements in the array are set to zero.

There are eight special keywords that can be included as part of a CLEAR list. These keywords allow you to clear groups of variables and arrays according to how they were declared.

Keyword | Clears...
PUBLIC | all public variables declared in the current project file.
PUBLIC[] | all public arrays declared in the current project file.
EXTERNAL | all externally referenced public variables in the current project file.
EXTERNAL[] | all externally referenced public arrays in the current project file.
GLOBAL | all global variables declared in the current project file.
GLOBAL[] | all global arrays declared in the current project file.
LOCAL | all local variables declared in the current block, except function parameters.
LOCAL[] | all local arrays declared in the current block.

Using the CLEAR command is the same as assigning a value of zero to a variable or array element using the LET command or the assignment operator =. However, you can assign zero to only one variable or array element at a time. The CLEAR command's ability to set groups of variables and arrays to zero makes it an efficient alternative to using multiple LET commands.
NOTE: If a local variable or array has the same name as a global or public variable or array, the local version will be cleared when the name is included in a CLEAR list.

To set only one element of an array to zero, you must use either the LET command or the assignment operator =, as illustrated in the following example. You cannot use CLEAR.

     LET salaries[2,10] = 0

When working with arrays, you may want to clear a single row or column without clearing the entire array. Although you cannot use the CLEAR command to do this, you can avoid assigning a zero to each element individually by using a FOR loop.

Assume you have an array named parts that is declared to have 4 columns and 100 rows. The following example demonstrates how you could clear column 4 of the array parts[4,100].

The assignment command in the FOR loop will execute 100 times, once for each row in the array. The FOR loop variable #row is substituted in the array subscript to step through the array one row at a time. The fourth column of the current row will be cleared by assigning a zero to that element.

     FOR #row = 1 TO 100
     parts[4,#row] = 0
     END FOR

Examples. In the first example, the CLEAR command clears the variables called $name and $telephone as well as all elements in the array named employees.

     CLEAR $name employees[] $telephone

The next example clears all public arrays declared in this project file along with the variable #account.

     CLEAR PUBLIC[],#account

Finally, the last example shows how to clear all local variables and arrays declared in the current function, all global variables declared in this project file, and an array named stocks.

     CLEAR LOCAL LOCAL[] GLOBAL stocks[]


CLEARERROR

Type: Command
Scope: All
Format:

     CLEARERROR

CLEARERROR resets the number returned by the LERROR function to zero. The LERROR function returns the number of the last error that occurred as a result of a command failure. CLEARERROR, in combination with the LERROR function, can be used to determine whether an error occurred during the execution of a group of commands.

For example, a project might begin with a series of commands for loading files. If one or more fails to load, you would want to halt the project and display an error message. The following example accomplishes this in SmartWare Database.

Example:

     CLEARERROR
     ERROR OFF

     File Load Custom-View region1
     File Load Custom-View region2
     File Load Custom-View region3
     File Load Custom-View region4

     IF LERROR > 0
     SCREEN CLEAR BOX 5 15 8 65 15 4
     SCREEN PRINT 6 21 15 4 "Unable to access all data bases."
     SCREEN PRINT 7 18 15 4 \
     "Assemble the correct data bases and try again."
     MESSAGE "Press any key to continue"
     STOP
     END IF


CLOSE-PRINTER

Type: Command
Scope: All
Format:

     CLOSE-PRINTER

The CLOSE-PRINTER command clears the printer driver of text and signals the end of a print job composed of LPRINT or LPRINTRAW commands.
IMPORTANT: CLOSE-PRINTER is used in conjunction with the OPEN-PRINTER command to define print jobs composed solely of LPRINT or LPRINTRAW commands. Other commands resulting in printed output will give highly unpredictable results when used inside the OPEN--PRINTER/CLOSE--PRINTER loop. Also, you should not use both LPRINT and LPRINTRAW in the same print job; doing so will cause unpredictable results.

Example:

     OPEN-PRINTER
     LPRINT "Hello!"
     CLOSE-PRINTER

LPRINT and LPRINTRAW


CONTINUE

Type: Statement
Scope: All
Formats:

     CONTINUE
     CONTINUE FOR
     CONTINUE WHILE

The CONTINUE command is used in conjunction with looping structures created with FOR and WHILE statements. CONTINUE abandons the current iteration of a loop and returns to the FOR or WHILE statement.

SmartWare can check the commands preceding CONTINUE to determine whether a FOR loop or a WHILE loop is executing. Therefore, the keywords FOR or WHILE are usually not required. However, use of the optional keyword may make the project file easier to understand.

CONTINUE can also be used with nested loop statements, such as a WHILE loop included inside a FOR loop. In such cases the optional word FOR or WHILE must be used to identify which of the nested loop statements you wish to continue.

The looping structures allow you to execute the same commands repetitively for every member of a set. A common use is to step through a database and process every record. However, there may be times when you do not want to process all records.

In such cases, you can isolate only those records that need to be altered. If the number of unwanted items is small, it may take longer to separate them than it would take to skip them as the loop is executing. CONTINUE allows you to select the records that will be processed while the loop is executing.

Example. In this example, club members born before 1929 do not have to pay dues. Because this only affects two out of several hundred members, the IF structure is used to determine if the birthday field contains a date before January 1, 1929. If the date is earlier, the next record is accessed and control returns to the FOR statement.

     FOR counter = 1 TO members
     IF days([birthday]) < days("01-01-29")
     Data Goto Record Next
     CONTINUE FOR
     END IF
     LET [dues] = [dues] + 30
     Data Goto Record Next
     END FOR

FOR
WHILE


CZBREAK

Type: Command
Scope: All
Formats:

     CZBREAK ON
     CZBREAK OFF

CZBREAK controls a user's ability to interrupt project file execution by pressing Ctrl-Z.

CZBREAK ON allows a user to suspend or cancel project execution by pressing Ctrl-Z. CZBREAK OFF prevents a user from using Ctrl-Z to interrupt project execution. CZBREAK ON is the default status at the beginning of project execution.

Interrupting project execution is useful during development as a means of halting a project for revision or if the project is caught in a loop. However, once a project file is complete, you may wish to prevent a user from canceling execution and leaving work in an incomplete state.

CZBREAK commands can be placed in a project file anywhere after the variable declarations. The CZBREAK OFF command stays in effect until CZBREAK ON is issued.
IMPORTANT: Do not use CZBREAK OFF until a project is completely debugged and ready for use. Difficulties in executing a project in which Ctrl-Z is disabled could force a user to reboot the system and risk losing data.


DEBUG

Type: Statement
Scope: All
Formats:

     DEBUG ON
     DEBUG OFF

The DEBUG project commands are directly related to the Debug and No-Debug options that are available under Remember Tools Compile on the module menus.

When the text version of a project file is compiled, the command lines are stored in a form that you cannot read. However, a text version of the command lines must be available for debugging commands, such as TRACE, QUIET, and SINGLE--STEP, to function properly. Use of the DEBUG ON command causes the text version of the commands to be saved as part of the compiled project file. DEBUG OFF saves only compiled commands in the runtime project file.

The DEBUG commands in the project override the Debug options selected from the module menu. This allows you to place DEBUG ON and DEBUG OFF commands around problem areas of the project file to concentrate debugging efforts on a specific section.

QUIET
SINGLE-STEP
TRACE


DLL CALL

Formats:

     DLL CALL handle FUNCTION function
     DLL CALL handle FUNCTION function STACK template expression(s)
     DLL CALL handle ORDINAL ordinal
     DLL CALL handle ORDINAL ordinal STACK template expression(s)

This command calls an exported function from a Windows Dynamic Link Library (DLL).

The handle variable (derived from a DLL LOAD command) indicates the library that contains the function. Functions can be specified by name or by ordinal number.

DLL Calling Conventions

It is up to the programmer to determine the appropriate calling conventions used by DLL functions. The following table describes some of the possible conventions:

Type | Uses | Comment
Pascal | stack | Parameters are passed to functions via the stack. First item pushed onto the stack is the first item. This is a common convention for Windows 3.1 DLLs.
CDECL | stack | Parameters are passed to functions via the stack. Last item pushed onto the stack is the first item. This is a common convention for Win32, Windows95, and NT DLLs.
Register | register | Parameters are passed to functions via the registers. In this case, the STACK option is not used. Instead, set the registers with the SETREG function prior to the DLL CALL command.

The STACK option is used to place parameter values on the stack (refer to the Pascal and CDECL conventions above) rather than passing them through registers. Elements on the stack are pushed as 32 bit values (i.e., four bytes at a time) in reverse order (CDECL convention). The examples below use the CDECL convention.

The information placed on the stack is specified using a template (refer to the section titled Buffer/Memory Templates in the Project Processing manual). Basically, a template is made up of a variety of variable types such as LONG, POINTER, DOUBLE, etc. This is the same format used by the INTERRUPT, PACK, and UNPACK commands. The amount of data must be an even number of bytes, with a maximum of 64 bytes. See Example # 2.

Return Values

Register values are saved for access by the GETREG function. In most cases, the DLL function sets the EAX register. If the value is greater than 32 bits, the EDX register will be used.

Example # 1

In this example, the USER32 library is loaded and the MessageBoxA function is called. This DLL function takes four parameters: a LONG, two POINTERS, and another LONG which are specified in the template as "LPPL" of the DLL CALL command. The template is followed by the parameter values. Note that the style parameter tells MessageBoxA to display both the OK and Cancel buttons.

To find out which button the user pressed, the AX register is inspected with GETREG. MessageBoxA is called again, this time with only the OK button.

Finally, the USER32 DLL is unloaded.

'------- Example # 1 -----------------------------------
     MAIN
     LOCAL #dllhandle $title, $msg, #style

        DLL LOAD "user32.dll" #dllhandle

        $msg   = "Select OK or Cancel"
        $title = "SPL Message 1"
        #style = 1 ' OK and Cancel buttons

        DLL CALL #dllhandle FUNCTION "MessageBoxA" STACK "LPPL" 0 DOSPTR($msg) DOSPTR($title) #style

        CASE GETREG(ax)
        WHEN 1
        $msg = "OK was selected"
        WHEN 2
        $msg = "Cancel was selected"
        OTHERWISE
        $msg = "Unknown selection"
        END CASE

        $title = "SPL Message 2"
        #style = 0 ' OK button only
        DLL CALL #dllhandle FUNCTION "MessageBoxA" STACK "LPPL" 0 DOSPTR($msg) DOSPTR($title) #style

        DLL UNLOAD #dllhandle

     END MAIN

Example # 2

The second example creates an SPL "wrapper" for the MessageBoxA and CustomColorA DLL functions. These wrapper functions do not load the DLLs, but instead accept the library handle as a parameter - this is to avoid excessive loading and unloading of libraries.

MAIN is used to load the DLLs, define a color array, call the wrappers, and unload the libraries.

The DllMessageBox function is straight-forward. It's basically a generalized version of the first example.

The DllCustomColors function is a little bit more complicated because CustomColorA uses two structures. The first structure, represented by the buffer variable $customcolor, defines and returns the 16 custom colors. The second structure contains the parameters for CustomColorA, including $customcolor.

A pointer to a 16 element array, defined in MAIN, is passed to DllCustomColors. Within DllCustomColors, the value of each element is read and then PACKed into the $customcolor buffer variable. This, and the other CustomColorA parameters are PACKed into the $parameters buffer variable.

CustomColorA is called. Parameters are passed as a pointer using the DOSPTR function on the $parameters buffer variable. Internally, CustomColorA places the new colors into $customcolor. This is then UNPACKed and written to each element of the original array.

Because, the #color[] array now contains the color values defined by the user, CustomColorA presets those values the second time DllCustomColors is called.

     '------- Example # 2 -----------------------------------
     GLOBAL DllMessageBox(4)
     GLOBAL DllCustomColors(2)

     MAIN
     LOCAL Huser
     LOCAL Hcomdlg #colors[16]

        DLL LOAD "user32.dll" Huser
        DLL LOAD "comdlg32.dll" Hcomdlg

        IF DllCustomColors( Hcomdlg, ARRAYPTR( #colors[1] ) ) = 0
        DllMessageBox( Huser, "Message", "Cancelled", 0 )
        EXIT MAIN
        END IF

        IF DllMessageBox( Huser, "Message", "Edit Again?", 1 ) = 1
        DllCustomColors( Hcomdlg, ARRAYPTR( #colors[1] ) )
        END IF

        DLL UNLOAD Huser
        DLL UNLOAD Hcomdlg

     END MAIN

     '-------------------------------------------------------
     FUNCTION DllMessageBox( #hnd, $title, $msg, #style )
        '#style - 1 = OK and Cancel buttons - 0 = OK button only
        DLL CALL #hnd FUNCTION "MessageBoxA" STACK "LPPL" 0 DOSPTR($msg) DOSPTR($title) #style
        RETURN GETREG(ax)
     END FUNCTION

     '-------------------------------------------------------
     FUNCTION DllCustomColors( #hnd, AP_colors )
     LOCAL $parameters $customcolor #ctr #ptr #hold

        BUFFER $customcolor SIZE 64
        BUFFER $parameters SIZE 36

        #ptr = 1
        FOR #ctr = 1 TO 16
        #hold = READPTR( AP_colors, #ctr )
        PACK $customcolor[#ptr] "L" #hold
        #ptr = #ptr + 4
        END FOR

        PACK $parameters "LLLLPLLLL" 36 0 0 0 DOSPTR($customcolor) 2 0 0 0

        DLL CALL #hnd FUNCTION "ChooseColorA" STACK "P" DOSPTR($parameters)

        #ptr = 1
        FOR #ctr = 1 TO 16
        UNPACK $customcolor[#ptr] "L" #hold
        WRITEPTR( AP_colors, #ctr, #hold )
        #ptr = #ptr + 4
        END FOR

        RETURN GETREG(ax)

     END FUNCTION

Notes

Both USER32 and COMDLG32, used in the examples, are standard 32 bit Windows DLLs.

The Windows SDK documentation, as well as other publications, cover the standard Windows DLL function interface.

The suffix A used in DLL function names, such as MessageBoxA, indicates the use of ASCII rather than Unicode where W is used as the suffix. These are typically applied when functions use strings. Note that your documentation may or may not include the suffix.

DLL
DLL LOAD
DLL UNLOAD
DLL Callback Functions


DLL LOAD

Format:

     DLL LOAD dll_name handle

This command loads a Windows Dynamic Link Library (DLL). Libraries must be 32 bit (i.e., Win32S, Windows95, or NT).

        DLL LOAD "dll_name" #dll_handle

If the command is successful, a value greater than zero is placed in the handle variable. This handle is used in all subsequent operations with the specified library.

If the specified library is already loaded, the same handle is returned.

DLL
DLL CALL
DLL UNLOAD


DLL UNLOAD

Format:

     DLL UNLOAD handle

This command unloads a Windows Dynamic Link Library (DLL).

        DLL UNLOAD #dll_handle

If left loaded, libraries are automatically unloaded when SmartWare exits.

If the library was loaded by a process other than the DLL LOAD command, this command will not unload the library but instead decrements an internal counter that was originally setup or incremented by DLL LOAD. In cases where the DLL LOAD command was not used, the handle is simply invalid.

DLL
DLL CALL
DLL LOAD


ERROR

Type: Command
Scope: All
Formats:

     ERROR ON
     ERROR OFF

The ERROR command enables or disables display of SmartWare error messages during project execution. ERROR ON causes subsequent error messages to be displayed. ERROR OFF suppresses error messages. ERROR ON is the default setting at the beginning of project execution.
NOTE: ERROR OFF does not affect CERROR or LERROR.

Example:

     ERROR OFF
     File Load "parts.ws"
     File Load "orders.ws"
     File Load "prices.ws"

     IF (LERROR <> 0)
     MESSAGE "Couldn't load all necessary files - Project aborted"
     STOP
     END IF

     ERROR ON

In this example, a developer is loading a series of worksheet files essential to the continuation of a project. ERROR OFF is executed prior to loading, suppressing any error message produced if a file fails to load. Then an IF statement checks for errors. If an error occurred during loading, a message is displayed on the screen and processing is stopped. If loading was successful, ERROR ON is executed and processing continues.


ERRORMESSAGE

Type: Command
Scope: All
Format:

     ERRORMESSAGE error number <"message">

This command sets the value of CERROR (and consequently, LERROR) to a specified error number and displays either the corresponding SmartWare error message or a custom message. The error number should be a valid SmartWare error number. The message, when specified, can be any valid expression.

The ERRORMESSAGE command produces a tone if the Beeper setting is enabled on the Global Preferences menu or if the BEEP ON command has been used. The message is displayed in standard error message colors (white on red) and remains on the screen until a key is pressed.

Instead of letting SmartWare automatically display an error message when an error occurs, you can use ERROR OFF and ERRORMESSAGE to control when an error message is displayed. The first example illustrates this.

Example:

     CLEARERROR
     ERROR OFF
     File Load "names.doc"
     File Load "sizes.doc"
     File Load "colors.doc"

     IF (LERROR <> 0)
     ERRORMESSAGE LERROR "Failed to load all necessary files."
     STOP
     END IF

In the first example, LERROR is cleared using CLEARERROR. Automatic SmartWare error messages are suppressed with ERROR OFF. An attempt is then made to load a series of files. If one or more fails to load, LERROR will not equal zero, the custom error message will be displayed, and the project will be halted.
NOTE: Users can press F1 to get on-line help for SmartWare error messages, unless the help system has been disabled with the F1HELP OFF command. Help is called according to a SmartWare CERROR number assigned to each error message. Substituting error messages that do not relate to the SmartWare error called by the specified number may be confusing to a user.

     CLEARERROR
     ERROR OFF

     Tools File Erase "names.doc"
     Tools File Erase "sizes.doc"
     Tools File Erase "colors.doc"
     File Load "dates.doc"

     IF (LERROR = 2301)
     ERRORMESSAGE LERROR
     END IF

In this example, ERROR OFF, ERRORMESSAGE, and LERROR are used to isolate the error produced by a failure to load (error 2301, File not found). The normal SmartWare error message is displayed if the File Load command fails. If a Tools File Erase command fails, no error message is displayed.

CLEARERROR
ERROR


EVALUATE

Type: Command
Scope: All
Format:

     EVALUATE SmartWare command or expression

The EVALUATE command allows you to construct, compile, and execute certain project commands during project file execution.

EVALUATE is followed by a text expression. The text expression can include variables, functions, or anything that evaluates to text. The expression must evaluate to the exact format of a project command, module command, or assignment.

EVALUATE does not work with statements. The following table lists the statements that cannot be evaluated:

Invalid Statements

CASE | CLEAR | COMMENT | CONTINUE
DEBUG | EXIT | EXTERNAL | FOR/END FOR
FUNCTION/END FUNCTION | GLOBAL | IF/END IF | JUMP
KEYS | LABEL | LOCAL | LOCK
MAIN/END MAIN | PUBLIC | RETURN | UNLOCK
WHILE/END WHILE |  |  |

Although you can use expressions to specify parameters in a command format, you cannot use expressions in place of command keywords. For example, you could use two variables to specify the frequency and length of a tone generated by the SOUND command, as follows.

     SOUND freq len

You could not, however, build a command format substituting expressions for option keywords, as shown here.

     flag = "ON"
     BEEP & flag

This example would fail because the variable flag cannot act in place of a keyword.

EVALUATE is useful, however, when you want to combine several SmartWare keywords into a complete command during project execution. In the following example, a blue box is painted on the screen and the word "Hello" is printed in the middle of the box. The WHILE loop is then executed, which prints a menu on the screen. The user can choose a direction to scroll the text inside the box or quit. The SCREEN SHORTMENU command returns the number of the position of the menu item selected. If the user chooses a direction, the complete SCREEN SCROLL command is constructed and executed.

Example:

     LOCAL direct, menu

     direct = 1
     menu = "Up Down Left Right Quit"

     SCREEN CLEAR BOX 1 1 20 40 1 1
     SCREEN PRINT 10 17 14 1 "Hello"

     WHILE (direct < 5)
     SCREEN SHORTMENU direct menu direct "Choose a direction:"
     IF (direct < 5)
     EVALUATE ("SCREEN SCROLL  "|GROUP (menu, direct)| \
     "1 1 20 40 4 4 1")
     END IF
     END WHILE

The portion of the project that executes scrolling includes the SCREEN SCROLL command and the GROUP function, which determines the direction to scroll by inserting the text from the menu variable into the SCREEN SCROLL command. Next, the remaining portion of the SCREEN SCROLL format, which contains constants, is concatenated to complete the command. SmartWare then evaluates and executes the command, and the WHILE loop continues.

To better understand this example, refer to the explanation of the SCREEN SCROLL command in the Project Processing Manual and the GROUP function in Formula Reference Manual.
NOTE: Because these commands are evaluated as the project is executing, processing may be slow. Public variables can be used with or without quotation marks, but local and global variables must be used without quotation marks. Global functions are not recognized.

SCREEN SCROLL


EXECUTE

Type: Command
Scope: All
Formats:

     EXECUTE project
     EXECUTE project FROM--FILE
     EXECUTE project IN--MEMORY

The EXECUTE command allows you to execute another project file from the current project file. When EXECUTE is encountered during project execution, the current project file is suspended, and the new project file is executed. When the second file terminates, the original project file is resumed, and execution continues with the command following EXECUTE.

The ability to execute another project file from the current one allows you to create a main menu. Each selection on the main menu corresponds to a project file that handles all responsibilities for that selection. When the tasks are completed for a particular selection, the main menu is displayed, and another selection can be made.
IMPORTANT: If a project file executes another project file and the second project file contains a command such as STOP or Quit, the original project file is abandoned.

Normally, a project file is executed from disk, and portions of the file are loaded in memory when needed. If you use the IN--MEMORY option, the entire project file is loaded into memory before it is executed. The advantage to using the IN--MEMORY option is faster execution. For this option, no function in the project file can be greater than 64K, and enough memory must be available to load the project file. If there is not enough memory available, the project automatically runs from disk.

Example. The following example project file illustrates the concept of a main menu. The SCREEN commands are used to generate the menu and accept operator input. Depending on the selection, the CASE command executes one of three project files. When the new project file finishes, the JUMP command is executed, causing the set of SCREEN commands to be executed again. The operator can choose another option or quit.

     GLOBAL choice$
     LABEL main
     SCREEN CLEAR BOX 1 1 25 80 0 0
     SCREEN CLEAR BOX 5 20 14 60 1 1
     SCREEN PRINT  6 30 11 1 "Monthly Sales Update"
     SCREEN PRINT  8 23 14 1 "A) Enter sales for last month"
     SCREEN PRINT  9 23 14 1 "B) Graph year-to-date sales"
     SCREEN PRINT 10 23 14 1 "C) Print year-to-date sales report"
     SCREEN PRINT 11 23 14 1 "D) Quit"
     SCREEN PRINT 13 26 11 1 "Selection"

     SCREEN INPUT 13 23 14 0 1 choice$ MASK "[A-Da-d]"

     CASE UPPER(choice$)
     WHEN "A"
     EXECUTE "entsales"
     JUMP main
     WHEN "B"
     EXECUTE "gphsales"
     JUMP main
     WHEN "C"
     EXECUTE "prtsales"
     JUMP main
     END CASE


EXIT

Type: Statement
Scope: All
Formats:

     EXIT
     EXIT CASE
     EXIT FOR
     EXIT FUNCTION
     EXIT MAIN
     EXIT WHILE

The EXIT command enables you to abandon or exit from the current block. Once the current block is exited, project execution continues with the next command.

EXIT can be used alone to break out of the current command block, or it can be followed by an optional keyword. Unless EXIT is used in a nested loop block, SmartWare is able to determine what command block is being exited; however, for clarity you should use one of the optional keywords to make it clear which block is being exited. If you are using EXIT within a loop, you must include a keyword to identify which command block you wish to exit, or SmartWare will exit from the innermost block that includes an EXIT command.

EXIT CASE interrupts processing of the CASE structure and instructs SmartWare to continue execution with the command following the next END CASE command.

EXIT FOR or EXIT WHILE interrupts the current iteration of the FOR or WHILE loop and returns project file execution to the command following END FOR or END WHILE.

Exiting a function is interpreted the same way as encountering an END FUNCTION statement. END FUNCTION passes project file execution to the command following the one that originally called the function. In this case, the function will return 0 to the calling statement.

Although it is not required, you should end a MAIN structure with END MAIN for clarity. The EXIT MAIN command is equivalent to jumping to the END MAIN statement, so execution of the project file stops. If the project file was called by another project file, the original project file would resume execution.

CASE
FOR
FUNCTION
MAIN
WHILE


EXTERNAL

Type: Statement
Scope: All
Format:

     EXTERNAL list

The EXTERNAL command allows a project file to reference public variables, public arrays, and public functions declared in other project files.

The position of the EXTERNAL command within a project file is important. EXTERNAL commands cannot be used within a main block or within a function. If an EXTERNAL command is found within a main block or function, the project will not compile. If the variable, array, or function referenced by the EXTERNAL command is referenced in several sections of the project file, the EXTERNAL command should be placed above the main block. If only one function references the external item, the EXTERNAL command may be placed directly before that function.
IMPORTANT: You can compile projects that have external references without the variables, arrays, or functions actually being available; however, they must be available at the time the project is executed or a runtime error will occur.

Variable names must be entered in the EXTERNAL list exactly as they were declared. Array names should be entered into the list with trailing brackets to differentiate them from variable names. However, array dimensions are optional. If included, the sizes do not matter; only the number of dimensions is used for error-checking. The actual dimensions of the array as defined in the project where the array is declared will be used at runtime. For example, if stocks is a two-dimensional array, either stocks[] or stocks[1,1] is valid. Items in the list may be separated by commas or spaces.

Function names should be entered into the list with trailing parentheses to differentiate them from variable names or arrays. Optionally, you may enter a number within the parentheses that represents the number of parameters required by the function. Examples of function entries include boxtext(1) and create_file(2). Including the number of parameters gives SmartWare additional error-checking capability.

For example, suppose you call an external function using three parameters, but the EXTERNAL command indicates that four parameters are required. This discrepancy will be found when you compile, and you can then correct the error. If you call an external function using three parameters, and the EXTERNAL command does not specify the required number of parameters, your project file will compile without any errors; however, a runtime error will occur when you execute the project.

Example. This example shows how a variable can be accessed by two project files by using the PUBLIC and EXTERNAL commands. The variable is declared as public in the first project, and the EXTERNAL command is used to reference it in the second.

     'project1

     PUBLIC name

     MAIN
     name = "Lorri"
     EXECUTE "project2"
     END MAIN

     'project2

     EXTERNAL name

     MAIN
     MESSAGE "Hello" & name
     END MAIN

The ability to call a function that resides in another project file is important. There are common tasks that have applications in many different situations. For example, a function to request a filename from the project operator and then check the validity of the filename might be used in an entire group of project files. By declaring a function as public and making it available to all projects, you have to enter the commands only once. The EXTERNAL command can then be used in any project file that needs to use the function.

Example. This example illustrates the use of an external function. The EXTERNAL command in Project1 references a function in another project file that will be called. When Project1 is executed, it loads Project2, which contains the function filechk(). The PUBLIC command in Project2 makes the function filechk() available to Project1. In this project, the project operator is prompted for a filename, and the entry is stored in the variable $output_file. The IF statement is used to verify that the entry is a valid filename.

When filechk() is encountered, within the IF statement, the external function is called. The variable $output_file is passed to filechk() and is received into the local, generic variable name $filename. Filechk() examines every character of a text expression to make sure it contains only numbers and letters and is not greater than eight characters in length. If it discovers an incorrect character, an asterisk is stored in $filename to indicate that the filename was invalid. If the text expression is correct, $filename is not changed, and the RETURN command sends $filename back to the IF command as the result of the function.

If the result of the function is an asterisk, the operator must enter another name. If the result is not an asterisk, the filename is valid and can be used in the commands that follow END IF. The function filechk() could be used by other project files in this same manner.

     'Project1

     EXTERNAL filechk(1)
     GLOBAL $output_file

     MAIN
     LOAD "project2" IN--MEMORY

     LABEL get_a_name
     SCREEN SHORTINPUT $output_file "Enter an output filename: "

     IF filechk($output_file) = "*"
     JUMP get_a_name
     END IF

     END MAIN

     'Project2

     PUBLIC filechk()

     FUNCTION filechk($filename)
     LOCAL count, test_char

     IF LEN($filename) > 8
     $filename = "*"
     ELSE
     FOR count = 1 TO LEN($filename)
     test_char = ASC(MID($filename,count,1))

     IF NOT((test_char >= {0} AND test_char <= {9}) \
     OR                                         \
     (test_char >= {A} AND test_char <= {Z})  \
     OR                                         \
     (test_char >= {a} AND test_char <= {z}))

     $filename = "*"
     EXIT FOR

     END IF
     END FOR
     END IF

     RETURN $filename
     END FUNCTION

PUBLIC


F1HELP

Type: Command
Scope: All
Formats:

     F1HELP ON
     F1HELP OFF

The F1HELP command is used to control the availability of SmartWare's on-line help system while project execution is suspended.

F1HELP ON enables access to on-line help while a project is suspended or while it is interrupted by an error message. F1HELP OFF disables it and causes F1 to be treated as any other key, clearing error messages when pressed.

Help is always enabled before and after project execution, regardless of any F1HELP OFF commands issued within a project.

F1HELP is most commonly used to disable on-line help during the display of custom error messages. A custom error message is one substituted for a SmartWare error message using the ERRORMESSAGE command. A user pressing F1 after seeing a custom error message is likely to get inappropriate on-line help. However, using F1HELP OFF eliminates such conflict by disabling on-line help.

Example:

     LOCAL qty
     F1HELP OFF
     LABEL get_quantity
     SCREEN SHORTINPUT qty "Enter the number of items"
     IF VAL(qty) < 1
     ERRORMESSAGE 11 "The number of items can't be zero"
     JUMP get_quantity
     END IF
     F1HELP ON

This might follow a prompt requesting a number used to calculate several values, including the average price for a series of items. Since calculation of the average price would involve use of the input as a divisor, an entry of zero would cause error message number 11 Division by zero to be displayed. This message and on-line help relating to it would be inappropriate, so help is disabled and the alternate error message is displayed.

ERRORMESSAGE


FARCALL

Type: Command
Scope: All
Formats:

     FARCALL address
     FARCALL address STACK template  expression(s)

NOTE: FARCALL is intended for use in DOS. A run-time error message will be produced under Unix. Instead, use the Unix IPC commands which provide similar functionality.

The FARCALL command operates similarly to the INTERRUPT command, except that instead of an interrupt being executed, a far function call is executed to the given routine's memory address.

Unlike the INTERRUPT command, the registers are not set prior to the call; therefore, using the SETREG function has no effect on the FARCALL command. However, once the function has been executed, the contents of the register are saved for access by the GETREG function. This allows access to values returned by the function.

Because the arguments pushed on the stack through the STACK option are pushed in reverse order, this should be compatible with most compilers' function-calling syntax.

INTERRUPT


FCLOSE

Type: Command
Scope: All
Format:

     FCLOSE file-number

This command closes a file opened with the FOPEN command. The file number is a numeric expression that must evaluate to the integer previously assigned to a file opened with FOPEN. All files opened during project execution should be closed when execution is complete. Although SmartWare closes all files for you, it is good programming practice to include an FCLOSE command for each file opened with FOPEN.

Example:

     'Example 1

     FOPEN "data.txt" AS 4
     (etc.)
     FCLOSE 4

     'Example 2

     april = 4
     FOPEN "data.txt" AS april
     (etc.)
     FCLOSE april

Both examples open a file called data.txt as file number 4, then close the file. The second example substitutes the variable april for the file number in both the FOPEN and the FCLOSE commands.

Refer to the explanation of the FOPEN command in the Project Processing Manual for more information.

FOPEN


FIELD PROMPT

Type: Command
Scope: Database
Formats:

     FIELD  PROMPT  target  <help>
     FIELD  PROMPT  MULTIPLE  target  <help>

The field prompt commands each display the standard field prompter used within SmartWare Database. There are two field prompt commands:

The first field prompt command allows the user to select a single field to be returned to the target.

The field prompt multiple command allows the user to select a field string to be returned to the target.

The target is a Project Processing variable; the optional help string will appear in standard colors on the Status Line of your screen.


FHANDLE

Type: Command
Scope: All
Format:

     FHANDLE "file-number" INTO variable

FHANDLE stores the actual OS file handle associated with the project processing file number into the variable. The file must be open. This command could be used to determine the file handle for use with a DOS interrupt call such as the DOS interrupt 0x21 function 0x44 IOCTL functions.

NOTE: While the FHANDLE command does work in Unix, it is intended as a DOS command.


FOPEN

Type: Command
Scope: All
Format:

     FOPEN "filename" AS file-number <OPTIONS option-name option-name>

This command opens a file so that its contents can be manipulated using FPOSITION, FREAD, FSEEK, and FWRITE.

The filename parameter is the name and extension of the file to be opened. It can include a full path specification, if necessary.

The filenumber expression must evaluate to an integer from 1 through 20. This is the number by which the file is identified in FPOSITION, FREAD, FSEEK, FWRITE, and FCLOSE commands. Filenumbers do not have to be assigned sequentially and apply only while files remain open. A file opened as file number 5 could be closed and later reopened as file 17.

Two optional expressions are allowed. One specifies a path for the file while the other specifies a read/write mode. Either can be listed first, and either can be omitted. A path included in the filename takes precedence over a path specified in an option name or number.

The optional expression specifying a path must be one of the eight named constants below, or an expression that evaluates to an integer from 0 through 7. If a path is not included in the filename and a numeric path is not included, the current data path is used. The constants and their numeric equivalents are as follows:

DATAPATH (0). DATAPATH signifies the directory where data files are found and written. This path is determined through the Tools Directory New-Directory command or through the Data path setting on the module-specific Preferences menu you access when you select the Tools Preferences module command.

SYSPATH (1). The system path is the path where the SmartWare program files, such as SMART.AIF, are located. This is the directory where SmartWare was installed.

PAGEPATH (2). In DOS, the virtual memory swap file is the path where a temporary file is written if SmartWare has to overflow memory to the disk. In UNIX, this will be a null string.

NOPATH (3). If a filename does not include a path, NOPATH specifies the path the user accessed when he entered SmartWare. This option has the same effect as CURPATH.

HOMEPATH (4). The home path is the user's home directory. Under DOS, PATH(HOMEPATH) always returns the same as CURPATH.

DEFPATH (5). The default path is the data path for the Main Menu. It is also used by the SmartWare modules if no other path has been set through each module's Tools Preferences command. When SmartWare is first invoked, DEFPATH refers to the current directory, unless it is set otherwise by the -D switch on the command line or specified with Tools Preferences Global.

CMDPATH (6). The command path is set by the -D command line switch. However, once the datapath is changed using the Tools Preferences Global command, this path will be empty.

CURPATH (7). CURPATH refers to the current path, or the directory you have accessed when you enter SmartWare. It is used if no other data path is specified by -D or the Preferences commands. CURPATH, unlike NOPATH, contains the path designation.

The optional expression specifying a read/write mode must be one of the four named constants below, or an expression that evaluates to an integer from 10 through 13. If no mode is specified, exclusive read/write mode (10) is used. The constants and their numeric equivalents are as follows:

RW_MODE (10). Read/write mode allows access to the file for both reading and writing data. If the file is on a network, it cannot be opened by other users until the project executes an FCLOSE command.

RO_MODE (11). Read-only mode allows access to the file for reading data only. If the file is on a network, it cannot be opened by other users until the project executes an FCLOSE command. The file must already exist.

RO_SHARE (12). Read-only sharable mode allows access to the file for reading data only. If the file is on a network, access by other users is allowed simultaneously. The file must already exist.

RW_SHARE (13). Read/write sharable mode allows access to the file for reading and writing data. If the file is on a network, access by other users is allowed simultaneously. You should use this option with caution; two or more users with access to the same file might overwrite the other's work.

TD_MODE (32). Opens a device (PRN, LPT1, etc.) in text mode. In text mode, some characters have certain effects. For example, a CTRL Z will terminate input or output. This option will have no effect when used to open files.

BD_MODE (33). Opens a device (PRN, LPT1, etc.) in binary mode. All characters are input and output without interpretation. This option will have no effect when used to open files.

If the specified file does not exist, it is created as an empty file, unless one of the read-only options is used. FWRITE can be used to place data in the new file.

The maximum number of files that can be open at one time may be limited by the DOS FILES command in your CONFIG.SYS file. If you have difficulty opening as many files as you need, you may have to adjust the setting for this command. Consult your DOS manual for instructions on how to do this.
IMPORTANT: Be certain you thoroughly understand the format of files you alter using FOPEN and FWRITE. Changes that do not conform to the file's format may render it unrecognizable to the application for which it was created.

Example:

     'Example 1

     file1 = 4
     FOPEN "data.txt" AS file1 OPTIONS SYSPATH RO_MODE

This example opens an existing file named data.txt in the SmartWare directory in read-only mode as file number 4. The variable file1 is used in place of the less meaningful file number, and word constants are used to specify options.

FCLOSE
FPOSITION
FREAD
FSEEK
FWRITE


FOR

Type: Statement
Scope: All
Format:

     FOR counter variable = numeric TO numeric < STEP numeric>
     commands
     END <FOR>

FOR loops are used to repeat a set of commands a specified number of times. The FOR statement is composed of four parts that control the execution of the loop. These parts include the counter variable, which counts the number of cycles through the loop; an expression or variable that specifies the initial value of the counter variable; an expression or variable that specifies the value that will terminate the loop; and an optional expression or variable defining the increment (step) by which the counter variable is increased or decreased.

The counter variable, like all variables, must be declared before it can be used in a FOR loop. When the FOR loop is first encountered, the counter variable is assigned the value of the first numeric expression.

The lower limit and upper limit numeric expressions (on either side of the keyword TO in the format shown) together determine the number of cycles through the loop. These expressions define a beginning and ending value. The loop begins with the value of the first expression and continues until the counter variable is greater than the value of the second expression (if STEP is positive), or until it is less than the value of the second expression (if STEP is negative).

The word STEP and a numeric expression together define the increment by which the counter variable is increased or decreased each time the loop is executed. They are optional parts of a FOR statement. If you do not specify a step, the program assumes the value to be one. To decrement the counter variable, you can specify a negative number.

At the end of each cycle of the FOR loop, the counter variable, which has been initialized to the value of the first numeric expression, is automatically altered by the increment specified in the step value, until it is greater than the value of the second numeric expression. When the counter equals the second numeric expression, the loop is executed a final time, and execution continues with the command following the loop structure. The counter variable will contain the value that was greater than or less than the second expression when the loop is complete.

The end of the FOR loop is indicated by END FOR. The keyword FOR following END is optional; however, adding it makes it clear that it is the FOR loop that is complete, since END is used elsewhere in Project Processing.

A FOR loop is very useful when you must execute a set of commands a specific number of times. In addition to using constants in a numeric range, you can use variables to vary the duration of the loop.

Two support commands are available for use with the FOR loop, CONTINUE FOR and EXIT FOR. CONTINUE FOR abandons the current iteration of the loop and returns to the FOR statement. The counter variable is adjusted and the next iteration begins. EXIT FOR abandons the FOR loop entirely.

Example. A very common use of the FOR loop is to stop at each record of a Database view to perform a calculation. Although the number of records in a view is dynamic, you can use the PRECORDS function to find the total number of records prior to executing the FOR loop.

     LOCAL #counter

     Data Goto Record First
     FOR #counter = 1 TO PRECORDS

     (Calculate data for this record
     or process record information)

     Data Goto Record Next
     END FOR

CONTINUE
EXIT


FPOSITION

Type: Command
Scope: All
Format:

     FPOSITION file-number INTO variable

FPOSITION stores the location of the file pointer for the file specified by the file number into a named variable. The file must have been previously opened using FOPEN.

The file number represents a file previously opened and must evaluate to an integer previously assigned to a file opened with FOPEN. The variable indicates where the pointer position is to be stored.

The pointer position is the current location, expressed in bytes from the beginning of a file, where data will be written to or read from the file. Position 0 describes the location of the first byte in the file, position 1, the second, etc. When a file is opened, the file pointer is always at the beginning of the file.
NOTE: FPOSITION does not change the file pointer position, but it does store that information in a variable. Use FSEEK to change the file pointer position.

Example:

     FOPEN "data.txt" AS 4
     FREAD 4 INTO january
     FREAD 4 INTO february
     FREAD 4 INTO march
     FPOSITION 4 INTO current

Here, the file data.txt is opened as file number 4. The first three items of data are stored in variables, and FPOSITION is used to store the location of the next entry in the variable current. The next time data.txt is opened, current can be used with FSEEK to access the next item of data.

FOPEN
FSEEK


FREAD

Type: Command
Scope: All
Formats:

     FREAD file number INTO variable
     FREAD file number LENGTH  length INTO variable
     FREAD file number BINARY length INTO variable

FREAD reads data from an open file and stores it in a named variable. FREAD used with no options reads one line of text at a time from a text file, which must be terminated by a line feed. The line of text is placed in a variable with the line feed and carriage return removed.

The file number must evaluate to the integer assigned to the open file with FOPEN. The variable indicates where the data is to be stored.

After FREAD is executed, the file pointer is advanced to the beginning of the next line of text. The first FREAD format, because it is used with text expressions, may only copy part of a text line into the variable if there is a zero byte (NULL) in the line.

FREAD LENGTH reads the number of characters specified by the length parameter into a variable. Line feeds and carriage returns, if present, are not removed. This format could be used for reading parts of text lines from a file, or reading a file that is text but is not broken into lines. This command can also be used to read 1 byte at a time out of a non-text (binary) file, but doing this is very slow.

FREAD BINARY reads directly from a true binary (non-text) file. The number of bytes specified by the length parameter are read and placed in a buffer variable and can then be examined using the PACK and UNPACK commands. If the length is zero, the variable must already be a buffer variable, and the length of the buffer is used. See the explanations of PACK and UNPACK and the section titled Buffer Variables in the Project Processing Manual for more information.

Using the LENGTH or BINARY options of the FREAD command, the end of the file is reached when the last byte in the file is read. However, using FREAD alone, the end of the file may be reached either when the last byte is read, or when an ASCII EOF character (^Z) is found. This is a special character that is used to mark the end of the text in a text file. If this character is found, it is not read, but the EOF flag will be set. Many text editors, including the SmartWare Tools Text-Editor, write this character at the end of files.

You can also use the FACTUAL function to return the number of bytes read. This can be used to test whether less than the requested amount was read to determine whether the end of the file was reached during the read.

Example:

     FOPEN "data.txt" AS 4
     FREAD 4 INTO january
     FREAD 4 INTO february
     FREAD 4 INTO march
     FPOSITION 4 INTO current
     FCLOSE 4

In the first example, the file data.txt is opened as file number 4, the first three items of data are stored into variables, the pointer position is stored in the variable current, and the file is closed.

     FOPEN "data.txt" AS 17
     FSEEK 17 current
     FREAD 17 LENGTH 1 INTO april
     FCLOSE 17

In the second example, the file from the first example is reopened as file number 17. Using FSEEK and the value stored in the variable current, the file pointer is moved back to its final position in the first example, and one byte is copied to the variable april.

FOPEN


FSEEK

Type: Command
Scope: All
Formats:

     FSEEK file-number  position
     FSEEK file-number EOF

FSEEK moves the file pointer to a specific location in an open file.

The file number must evaluate to the integer assigned to a file previously opened with FOPEN. The position is the location in the file to which the file pointer is to be moved.

The pointer position is the location, expressed in bytes from the beginning of a file, where data will be written to or read from the file. Position 0 describes the location of the first byte in the file, position 1, the second, etc. When a file is opened, the file pointer is always at the beginning of the file.

When EOF is used as a parameter, the cursor is moved to the byte after the last byte in the file, including an end-of-file character (ASCII 26), if present.
IMPORTANT: When you position a file pointer using the EOF parameter and then write to that file, remember that the inserted bytes may be past the end-of-file character and are, therefore, invisible to ordinary text editors, including SmartWare's text editor and the SmartWare Word Processor. The EOF parameter is best used with files that were created with FOPEN that have no end-of-file character.
NOTE: You may get unpredictable results if you specify a numeric value greater than the number of bytes in the file. No error checking occurs before FSEEK relocates the file pointer.

Example:

     FOPEN "data.txt" AS 4
     FSEEK 4 current
     FREAD 4 INTO file2

In this example, data.txt is opened as file number 4, and FSEEK is used to move the file pointer to a location previously stored in the variable current. Next, an item of data is read into a variable.

FOPEN


FTRUNCATE

Type: Command
Scope: All
Formats:

     FTRUNCATE filenumber

FTRUNCATE shortens or erases the user file opened by the filenumber parameter. The file is truncated beginning at the current position but retains file permissions.


FUNCTION

Type: Statement
Scope: All
Format:

     FUNCTION name(argument names)
     commands
     END <FUNCTION>

The FUNCTION statement structure is used to create a subset of commands that accomplish a specific task. Arguments are generally passed to the function, which returns a result based on those arguments.

Project file functions are similar to SmartWare functions. SmartWare functions support each module by giving you access to prewritten routines that can accelerate the development of complex formulas. Project file functions support and accelerate project development because, once written, they can be referenced by many project files.

A function call can stand alone as a complete statement, or it can be included in an expression. For example, both of the following are valid uses of Project Processing functions.

     load_data()
     cust_name = find_name(acct#)

All Project Processing functions that are called must be declared before the main block. Function structures themselves are located below the main block. Functions existing inside of the current project should be declared using the GLOBAL or PUBLIC statement. Functions defined outside of the current project should be declared using the EXTERNAL statement. See the discussion of EXTERNAL functions below for more information.

The function statement includes the keyword FUNCTION, the name of the function, and a set of parentheses. The parentheses following the function can include function arguments. Argument names are variable names that will be used within the function to refer to the arguments passed when the function is called. Within the function, these act as local variables, except that they are pre-initialized with the passed values.

Up to 25 arguments can be included in a function. Multiple arguments are separated by commas. If the number of arguments passed to a function differs from the number of arguments expected by the function, an error will occur. To increase SmartWare's ability to check for errors in the number of arguments being passed, you can include the expected number of arguments in the function declaration statement.

Example:

     FUNCTION tax(gross_income, exemptions, tax_rate)

In this example, gross_income, exemptions, and tax_rate are used in the function to refer to the first, second, and third values passed to the function. tax(15000,3,.15) assigns the value 15000 to gross_income, 3 to exemption, and .15 to tax_rate when the function is entered. The function can then perform calculations on the arguments passed by using the argument names as follows:

     RETURN (gross_income - (2000 * exemptions)) * tax_rate

This will calculate and return the tax for any values passed to the function. In the example, the return equals (15000 - 12000 * 3)) * .15, or 1350.

Each argument can be declared as passed by value or by reference. An argument passed by value gets a copy of the value passed in the function call. An argument declared to be passed by reference gets a reference to the variable passed in the function call. Use the REF keyword to pass an argument by reference.

Example:
     GLOBAL change_me()
     MAIN
        local i
        i = 3
        change_me(i)
        message str(i) 'i now equals 5 because it was passed as reference
     END MAIN

     FUNCTION change_me(REF arg)
        arg = 5
     END FUNCTION

In the following example, if you were going to declare a function draw_menu that expected six arguments, you could use the following statement to indicate that this function is only referenced in the current project and that it expects six arguments.

     GLOBAL draw_menu(6)

Variables used to receive arguments sent to the function do not have to be declared anywhere in the project file; they are automatically treated as local variables.

Within the function block you can place any module or project commands except GLOBAL, PUBLIC, and EXTERNAL. The RETURN command is used within a function to return a result to the command that called it. RETURN is described in detail in the Project Procesing Manual and is used below in the description of the FUNCTION statement structure.

The end of the function is indicated by END FUNCTION. The keyword FUNCTION is optional; however, adding it makes it clear that it is the function statement that is complete, since END is also used in other statements in the SmartWare Programming Language.
IMPORTANT: You should not declare a Project Processing function with the same name as a SmartWare function. Doing so may cause unpredictable results.

A function is called any time the name of the function is encountered, whether as a statement or as part of a formula or equation. Project control then passes to the FUNCTION structure. If arguments are passed to the function, they are used within the function to produce a result or to affect the operation of the function. When the function ends, a result is returned to the statement that called the function.

Once a result is returned, it is sent to the calling statement. If the calling command was a LET command or an assignment statement using the operator =, the result is placed into the target. If the function was called as part of a command, the result is used as part of the command. The result is lost, as in the case of a stand-alone call, when the calling statement does not use the result.

Three commands can cause a function to end and return a result. The RETURN command enables you to return the result of an expression to the calling statement. RETURN can also be used without an expression to return zero. The EXIT FUNCTION command can be used if a function must end when a certain condition exists. EXIT FUNCTION will immediately abandon the function and return a zero. If the END FUNCTION command is encountered, the function will terminate and return a zero.
NOTE: If a function terminates without using a RETURN command, (i.e., by reaching the END FUNCTION statement), SmartWare returns a numeric zero by default.

External Functions. You can call a function residing in a project file other than the current one. To do this, you must use Project Processing commands to link the calling project file to the project file that contains the FUNCTION structure.

To call an external function, make certain the project file containing the function you want to call is loaded or executing. If it is not loaded, an error will occur during execution. The file containing the function must use a PUBLIC statement to make the function available to other project files. The calling project file must include an EXTERNAL statement to instruct SmartWare to look for the function in other project files.

Once this link is established, the flow from the function call to the FUNCTION command structure and back is the same as if the FUNCTION command structure resided in the current project file.

Examples. These examples illustrate calls to internal and external functions and show how arguments can be passed and results received.

The first example uses a function to display a commonly used prompt. The function call stands alone and, since the text is always the same, does not include any arguments. The function prints a message and then waits for a key to be pressed. END FUNCTION causes control to return to the main section and execution to proceed after the function call.

     GLOBAL any_key()
     MAIN
     any_key()
     END MAIN

     FUNCTION any_key()
     SCREEN PRINT 1 28 14 0 "Press any key to continue"
     MESSAGE
     END FUNCTION

The next example displays a single line of text in a box in the center of the screen. As in the first example, the function call stands alone. However, this time an argument supplies text to the function. The left and right column limits, as well as the vertical center of the screen, are calculated before printing the box. Finally, the text is printed in the box. END FUNCTION causes control to return to the main block and execution to proceed after the function call.

     GLOBAL box_text(1)

     MAIN
     LOCAL msg_text
     SCREEN PRINT 20 1 10 0 "Enter the text you want to display"
     SCREEN INPUT 21 1 14 0 76 msg_text
     IF (msg_text = "")
     box_text("No message")
     ELSE
     box_text(msg_text)
     END IF
     END MAIN

     FUNCTION box_text(txt)
     LOCAL left_col, right_col, middle

     left_col = INT((SCRWIDTH - LEN(txt)-2) / 2)
     right_col = left_col + LEN(txt) + 2
     middle = SCRHEIGHT/2

     SCREEN CLEAR BOX (middle-1) left_col (middle+1) \
     right_col 11 1
     SCREEN PRINT middle (left_col+2) 11 1 txt
     MESSAGE "Press any key to clear message"
     END FUNCTION

The third example illustrates how a function can be called as part of an expression. This project file calculates an employee bonus based on the rules of a profit sharing program. The employee salary and length of service are required to calculate the bonus amount. The LET command initializes #bonus by multiplying the employee salary by the appropriate percentage. This percentage varies with the length of service, so a function is used to calculate the percentage before it is multiplied by the salary. The function returns either .06 or .03, which is multiplied by the salary. The amount of the bonus is stored in #bonus.

     MAIN
     LOCAL #salary,#service,#bonus
     SCREEN SHORTINPUT #salary "Enter salary:"
     #salary = VAL(#salary)

     SCREEN SHORTINPUT #service "Enter months of service:"
     #service = VAL(#months)

     #bonus = #salary * salary_pct(#months)
     MESSAGE "The profit sharing bonus is"&FORMAT(#bonus,"2$")
     END MAIN

     FUNCTION salary_pct(#service)
     IF #service > 6
     RETURN .06
     ELSE
     RETURN .03
     END IF
     END FUNCTION

The final example illustrates the use of an external function to extract initials, given a first and last name. The file project1 is executed first and loads project2, which contains a public function, get_initials(). Project1 can access get_initials() because of the EXTERNAL command at the top of the file. The first name and last name are requested in separate SCREEN SHORTINPUT commands. With this information, the local variable initials is assigned the value returned by the external function get_initials. Since the link has been established, the first and last names are sent to the function where the first letters are extracted. The RETURN command places periods after each of the letters and then sends the result back to where the variable initials is assigned a value. The result is placed into the variable initials.

     'project1

     EXTERNAL get_initials(2)
     MAIN
     LOCAL first_name, last_name, initials
     LOAD "project2" IN--MEMORY
     SCREEN SHORTINPUT first_name "Enter the first name: "
     SCREEN SHORTINPUT last_name  "Enter the last name: "
     initials = get_initials(first_name, last_name)

     SCREEN PRINT 2 2 15 1 \
     "The initials for the name "| first_name&last_name
     SCREEN PRINT 3 2 15 1 "are "|initials
     MESSAGE "Press any key to continue"
     END MAIN

     'project2

     PUBLIC get_initials(2)
     FUNCTION get_initials(first,last)
     first = UPPER(LEFT(first,1))
     last = UPPER(LEFT(last,1))
     RETURN first|"."|last|"."
     END FUNCTION
NOTE: Using the TRANSFER command in a function is not recommended due to unpredictable results. TRANSFER should always be used in the main block.

EXTERNAL
GLOBAL
PUBLIC
RETURN
REF


FUNIQ

Type: Command
Scope: All
Formats:

     FUNIQ filename AS filenumber INTO filename-variable

FUNIQ creates and opens a unique file under the specified filenumber.

The filename parameter is the path and filename of a file to be created if the current environment does not support unique file creation. A unique file is created in the path referenced by filename. The name of the file created is returned in the filename-variable.

If the current environment does support unique file creation, and the filename given has no path, the unique file will be created in the root directory of the current drive.


FWRITE

Type: Command
Scope: All
Formats:

     FWRITE file number FROM data
     FWRITE file number LENGTH  length FROM data
     FWRITE file number BINARY length FROM variable

This command writes data to a specified file previously opened with the FOPEN command. The file number parameter must evaluate to the integer assigned to the file with FOPEN. The data can be a numeric or can be a text expression. If it is numeric, it is automatically converted to text.

The FROM format writes one line of text to the file at the current file pointer position. In DOS, a carriage return/line feed pair is automatically appended to the line; in Unix, only the line feed is appended.

The LENGTH format writes the number of bytes specified by the length parameter to the file with no carriage return or line feed. This can be used to write fragments of text or single binary bytes.
IMPORTANT: Be careful to specify a length less than or equal to the number of bytes in the source data. Specifying a length greater than the number of bytes in the source data will cause the remainder of the space to be filled with random characters from memory.

Using the BINARY keyword, FWRITE can write a true binary file or record at the current file position directly from the specified variable. This variable must be a buffer variable, and the data is generally placed in the buffer using the PACK command. See the section titled Buffer Variables in the Project Processing Manual, as well as the discussion of the PACK command in this alphabetical listing. If the length specified is longer than the variable buffer, an error will occur. A length of zero will write the entire buffer.

If the file pointer is anywhere except the end of the file, the FWRITE command overwrites existing information in the target file. For example, if the file pointer is positioned at the beginning of a file and FWRITE is used to write the expression "New data" into the file, eight characters, plus a carriage return (and line feed in DOS), will be written over the first ten existing characters in the file.

After FWRITE is executed, the file pointer is advanced to the byte immediately following the last byte written.
IMPORTANT: Be certain you thoroughly understand the format of files you alter using FOPEN and FWRITE. Changes that do not conform to the file's format may render it unrecognizable to the application for which it was created.

Example:

     FOPEN "data.txt" as 7
     FWRITE 7 FROM january
     FWRITE 7 FROM february
     FWRITE 7 FROM march

     FPOSITION 7 INTO current
     FCLOSE 7

In the first example, the file data.txt is opened as file number 7 and data from the variables january, february, and march is written to the file, each followed by a carriage return/line feed combination. The pointer position is then stored in the variable current, and the file is closed.

     FOPEN "data.txt" AS 3
     FSEEK 3 current
     FWRITE 3 LENGTH 12 april

     FCLOSE 3

In the second example, the file from the first example is reopened as file number 3. Using FSEEK and the value stored in the variable current, the file pointer is moved back to its final position in the first example, and 12 bytes are written from the variable april. Since the LENGTH parameter is used, no carriage return or line feed is written.

FOPEN


GLOBAL

Type: Statement
Scope: All
Format:

     GLOBAL list

The GLOBAL statement declares variables, arrays, and functions as global. A variable that is declared global can be used in the main block and in any function block in a project file. When variables or arrays are declared, they are initialized with a value of zero. Memory for global variables and arrays is allocated when the project file executes.

The GLOBAL statement must be placed outside of main and function blocks. GLOBAL variable and array declarations are usually placed before the main block. However, it is acceptable to place global declarations after the main block, as long as they are not within a function. If a GLOBAL statement is found inside of the main block or a function block, the project file will not compile.

Function declarations must precede any reference to that function or an error will occur, and the project will not compile. Global function declarations define those that will be used in function statements later in the project but are not known outside of the current project file. Function names must be followed by a pair of parentheses and may optionally include a single number, which is the number of arguments the function will take. For example, tax() and tax(3) are both valid.

The declaration list may contain variables, arrays, or functions and can be separated by either a space or a comma. Names must adhere to the rules described in Project Processing and may be the same as local variables and arrays. All global variables, arrays, and functions must have unique names and cannot duplicate public variable, array, or function names declared in the same project file.
NOTE: When a local variable has the same name as a global or public variable, the local variable takes precedence. The same rule applies to duplicate array names.

Array list entries require more than a name; the array dimensions must also be included. The array dimensions must immediately follow the array name and be enclosed in brackets. Arrays can have up to three dimensions. If the array has multiple dimensions, they must be separated by commas. Examples of one-, two-, and three-dimensional arrays are names[20], sales[52,7], and appts[12,31,8]. For more information on array dimensions, refer to Project Processing.

GLOBAL variables and arrays can be referenced throughout the currently executing project file. When execution of the project file is complete, the variable or array is automatically deallocated. Deallocation not only deletes the contents but frees the memory that the variable or array was occupying. By managing memory in this manner, the amount of available memory is always maximized for the project currently executing.
NOTE: GLOBAL variables are only known to those commands that physically follow the GLOBAL statement in the text version of the project file. For example, if a variable is declared before the main block, it is known to the entire project file. If the variable is declared after the main block and in between function blocks, it is only known to those functions that follow the GLOBAL statement.

If another project file is executed from within a project where global variables and arrays have been declared, the global variables and arrays will not be deallocated because the source project file is not finished executing. Even though these variables are not deallocated, they cannot be referenced in the destination project file due to their range restriction. In contrast, the TRANSFER command will cause the variables to be deallocated because the source project file will be abandoned.

MAIN
FUNCTION
TRANSFER


GRAPHICS

Type: Command
Scope: All

This series of graphic project processing commands provides programmers with access to all of the fundamental graphic functions used in the spreadsheet graphing module. Special features have been added for project processing.

Here are some basic rules regarding the command lists that follow:

All coordinates are integers.
The x axis increases from left to right.
The y axis increases from top to bottom.
By default, (0,0) is the top left corner of the screen, and the bottom right corner is device specific (16383,16383 for metafiles). You can change the range of legal coordinates using GRAPHICS SET WINDOW.
Ellipses are specified by a rectangle in which the ellipse is inscribed.
If a line width greater than 1 is specified, then the stroke is centered on the idealized zero-width curve implied by the given coordinates. This means that a stroked rectangle with line width of 10 will be taller and wider than a stroked rectangle with a line width of 1.

These examples use a variety of GRAPHICS commands and are meant to provide a general overview of GRAPHICS usage. The second example in particular shows the method in which polygons are created. Each of the GRAPHICS commands is described in detail in the following pages:

Example 1:

     MAIN
        GRAPHICS OPEN SCREEN
        GRAPHICS DRAW PIE 40 40 500 500 0 200
        GRAPHICS SET FOREGROUND c_grey
        GRAPHICS SET TEXT-FONT font_script
        GRAPHICS SET TEXT-HEIGHT 20
        GRAPHICS DRAW TEXT 50 150 "Press any key..."
        MESSAGE
        GRAPHICS CLOSE
     END MAIN

Example 2:

     MAIN
        GRAPHICS OPEN SCREEN
        GRAPHICS POLYGON START
        GRAPHICS POLYGON VERTEX 250 50
        GRAPHICS POLYGON VERTEX 150 150
        GRAPHICS POLYGON VERTEX 200 250
        GRAPHICS POLYGON VERTEX 300 250
        GRAPHICS POLYGON END
        GRAPHICS DRAW POLYGON
        GRAPHICS DRAW TEXT 50 150 "Press any key..."
        MESSAGE
        GRAPHICS CLOSE
     END MAIN


GRAPHICS BITMAP

Format:

     GRAPHICS BITMAP DRAW bitmap-variable x y
     GRAPHICS BITMAP DRAW bitmap-variable x y REMAP
     GRAPHICS BITMAP READ bitmap-variable filename
     GRAPHICS BITMAP SAVE bitmap-variable x1 y1 x2 y2
     GRAPHICS BITMAP WRITE bitmap-variable filename

These commands manipulate bitmaps which are stored in bitmap variables. The format of a bitmap depends on the graphics mode in use (this ensures that drawing to the screen is fast). Consequently, GRAPHICS BITMAP commands only work when the screen is open.

The BITMAP DRAW commands display a bitmap on the screen, aligning its upper left corner with the specified x, y coordinate. By default, the bitmap's palette is ignored and pixel data is simply copied to the screen. The appearance of the bitmap will be determined by the current display palette. For example, you may have saved a part of the screen and now want to restore that part to its original appearance. If the REMAP option is given then, after drawing the bitmap, its palette will be copied to the display palette. You would normally do this if you are in a 256 color graphics mode and want to display a 256 color bitmap of a scanned photograph.

The BITMAP READ commands place the contents of a BMP file into a bitmap variable. By default, the bitmap's palette is reordered so that (in 4 and 8 bit per pixel graphics modes) the first 16 colors correspond to the standard ANGOSS SmartWare colors. This reordering is performed so that background text and graphics do not change to random colors when using BITMAP DRAW with the REMAP option. This should retain the actual appearance of a bitmap however, the reordering may not be successful if the bitmap's palette does not contain close analogs of each of the SmartWare colors.

The BITMAP SAVE command copies a portion of the screen, determined by the given top left and bottom right coordinates, into a bitmap variable. The bitmap's palette will match the current display palette (the display palette can change: see GRAPHICS BITMAP DRAW and GRAPHICS PALETTE RESTORE).

The BITMAP WRITE command writes a bitmap to the specified file.

Limitations:

Bitmap files come in four varieties: they may have 1, 4, 8, or 24 bits per pixel (bpp). ANGOSS SmartWare however, supports graphics modes with 1, 2, 4, or 8 bpp. Writing a bitmap to a file works if the bitmap has: 1, 4, or 8 bpp. Reading a bitmap from a file works in the following circumstances:

1 bpp files can be read in all graphics modes.
4 bpp files can be read in a 4 or 8 bpp graphics mode.
8 bpp files can be read in an 8 bpp graphics mode.

Bitmap Variables:

These variables will only work with the GRAPHICS BITMAP commands (you will not be able to FWRITE them) though, they are declared in the same way that numeric and string variables are. Bitmaps are passed by reference, not by value. For instance, if bm1 is a bitmap variable then bm1 = bm2 causes both variables to point at the same object. The same thing happens when a bitmap variable is passed as an argument to a function: only the pointer is copied rather than the entire bitmap. Internally, a reference count keeps track of how many variables are currently pointing to the bitmap. When the reference count reaches zero, the bitmap is freed.


GRAPHICS BMPLIB

Formats:

     GRAPHICS BMPLIB OPEN handle list CONSTANT
     GRAPHICS BMPLIB OPEN handle list REFRESH
     GRAPHICS BMPLIB READ handle file bmp_var DIRECT
     GRAPHICS BMPLIB READ handle file bmp_var REMAP
     GRAPHICS BMPLIB DROP handle file
     GRAPHICS BMPLIB CLOSE handle

The GRAPHICS BMPLIB commands simplify the management of bitmap files by creating bitmap libraries. These libraries are also efficient since bitmap files are loaded once and then read from memory thereafter.

BMPLIB OPEN

This opens a library and writes a number to the handle variable. Files are loaded from the path list. Paths in this list are separated by a semi-colon (;) in DOS and a colon (:) in Unix. The REFRESH variation of the command checks the date/time stamp of a bitmap file whenever it is accessed and reloads it if required. The CONSTANT variation does not perform a refresh once the file is loaded. Because it is faster, CONSTANT is recommended for normal use while REFRESH is recommended during a development phase.

BMPLIB READ

This causes the bitmap variable to reference a bitmap file. If the bitmap file is not already in the library specified by the handle, it will be added to the library using the path set in the OPEN command. If the REMAP option is given, the bitmap's palette will be copied to the display palette. The DIRECT option suppresses the display palette reordering.

BMPLIB DROP

This unloads one bitmap file from the library.

BMPLIB CLOSE

This frees the library, unloading all bitmap files that are not referenced by bitmap variables through the READ command.


GRAPHICS CLOSE

Format:

     GRAPHICS CLOSE

The GRAPHICS CLOSE command completes the graphics environment. An open graphics file is written at this time or an open graphics screen is returned to normal. Refer to the GRAPHICS OPEN command.


GRAPHICS CONVERT

Format:

     GRAPHICS CONVERT BMP-TO-CGM bmp-filename cgm-filename
     GRAPHICS CONVERT CGM-TO-BMP cgm-filename bmp-filename width <height>

These commands convert graphics files to and from bitmap (BMP) and CGM format. The GRAPHICS CONVERT CGM-TO-BMP command has a specified width and height. The height, if omitted or 0, is automatically chosen to preserve the metafile's aspect ratio.


GRAPHICS DRAW

Format:

     GRAPHICS DRAW ARC x1 y1 x2 y2 angle-start angle-delta
     GRAPHICS DRAW BMP-FILE bmp-filename x y
     GRAPHICS DRAW BMP-FILE bmp-filename x1 y1 TO x2 y2
     GRAPHICS DRAW CGM-FILE cgm-filename x1 y1 x2 y2
     GRAPHICS DRAW LINE x1 y1 x2 y2
     GRAPHICS DRAW OVAL x1 y1 x2 y2
     GRAPHICS DRAW PIE x1 y1 x2 y2 angle-start angle-delta
     GRAPHICS DRAW PIXEL x y
     GRAPHICS DRAW POLYGON
     GRAPHICS DRAW RECTANGLE x1 y1 x2 y2
     GRAPHICS DRAW TEXT x y string

These commands draw the specific graphic object to the screen or file depending on the GRAPHICS OPEN command used to initiate the graphics environment. Attributes, such as foreground color and line type, will have default values or can be set with GRAPHICS SET prior to issuing a draw command.

The most fundamental of these commands is DRAW PIXEL. In this case, only the point specified by the x, y coordinate is drawn using the current foreground color. The DRAW LINE command draws a line from the start to the end coordinates. This line is affected by the current settings of foreground color, line type and line width. If the current line width is greater than one, then the stroke is centered on the idealized zero-width curve implied by the given coordinates.

DRAW RECTANGLE and DRAW OVAL are specified by a top left and bottom right coordinate set. The oval's shape and size are determined by the imaginary rectangle in which it is inscribed. Note that the pixel at x2, y2 is included in the rectangle; this means that the height of the rectangle is (y2 - y1) + 1. Lines in these objects are affected by the current settings of foreground color, line type and line width.

Arcs and pies are drawn from the x1, y1 coordinate to the x2, y2 coordinate and are specified by an ellipse which is, in turn, determined by a starting angle and a delta angle which the figure subtends. Angles are measured in 1/10 degrees; 3600 makes a circle. Angles are measured beginning from the vector extending to the right from the centre of the ellipse and proceeding counterclockwise. The DRAW ARC and DRAW PIE command produce a stroked geometric figure affected by the current settings of foreground color, line type and line width.

DRAW TEXT prints the passed string beginning at the specified x, y coordinate. The appearance of the characters is affected by the current settings of foreground color, text font and text height. Note that printing text in graphics mode, unlike the SCREEN commands in text mode, is not affected by the background color setting.

DRAW POLYGON has no parameters because its size, shape, and location are determined by the previous set of GRAPHICS POLYGON START, VERTEX, and END commands. Lines in these objects are affected by the current settings of foreground color, line type and line width.

DRAW BMP-FILE and CGM-FILE send the specified file to the current output device within the area determined by the top left and bottom right coordinates. Scaling is arbitrary. If the TO option is omitted from DRAW BMP-FILE, then x2, y2 are computed from the bitmap's width and height.


GRAPHICS FILL

Format:

     GRAPHICS FILL RECTANGLE x1 y1 x2 y2
     GRAPHICS FILL POLYGON
     GRAPHICS FILL OVAL x1 y1 x2 y2
     GRAPHICS FILL PIE x1 y1 x2 y2 angle-start angle-delta

Similar to GRAPHICS DRAW, these commands draw and fill the specific geometric object to the screen or file depending on the GRAPHICS OPEN command used to initiate the graphics environment. Attributes, such as background color and fill type, will have default values or can be set with GRAPHICS SET prior to issuing a fill command.

FILL RECTANGLE and FILL OVAL are specified by a top left and bottom right coordinate set. The oval's shape and size are determined by the imaginary rectangle in which it is inscribed. Note that the pixel at x2, y2 is included in the rectangle; this means that the height of the rectangle is (y2 - y1) + 1. These objects are affected by the current settings of foreground color, background color, and fill type.

Pies are drawn from the x1, y1 coordinate to the x2, y2 coordinate and are specified by an ellipse which is, in turn, determined by a starting angle and a delta angle which the figure subtends. Angles are measured in 1/10 degrees; 3600 makes a circle. Angles are measured beginning from the vector extending to the right from the centre of the ellipse and proceeding counterclockwise. The FILL PIE command produces a filled geometric figure affected by the current settings of foreground color, background color, and fill type.

DRAW POLYGON has no parameters because its size, shape, and location are determined by the previous set of GRAPHICS POLYGON START, VERTEX, and END commands. These objects are affected by the current settings of foreground color, background color and fill type.


GRAPHICS OPEN

Format:

     GRAPHICS OPEN BMP-FILE bmp-filename width height
     GRAPHICS OPEN CGM-FILE cgm-filename
     GRAPHICS OPEN CGM-FILE cgm-filename WINDOW x1 y1 x2 y2
     GRAPHICS OPEN SCREEN

These commands open a specific graphic environment which is required whenever graphics are displayed or files are created. Once the environment is established, the GRAPHICS SET, DRAW, FILL, and BITMAP commands can be used. The GRAPHICS CLOSE command completes this environment.

The OPEN BMP-FILE command opens a bitmap file as the graphics output device. Graphics operations are written to a bitmap having a size specified by the width and height parameters. The OPEN CGM-FILE command opens a bitmap file with a default size of (0,0) by (16383,16383). To create a different size, use the WINDOW option and specify the top left and bottom right coordinates. Both the BMP and CGM are written to the named file when the GRAPHICS CLOSE command is executed.

The OPEN SCREEN command uses the screen as the output device. It puts the screen into the graphics mode specified by the TOOLS PREFERENCES HARDWARE setting. The current screen will not be cleared if a WYSIWYG text mode is in use and if this text mode corresponds to the same video mode as the graphics mode. Note that error messages during screen drawing may not be displayed unless the screen is in WYSIWYG mode.


GRAPHICS PALETTE RESTORE

Format:

     GRAPHICS PALETTE RESTORE

This command restores the display palette to the default setting. Typically, it is used to restore the palette after it has been changed by a GRAPHICS BITMAP DRAW command with the REMAP option.


GRAPHICS POLYGON

Format:

     GRAPHICS POLYGON START
     GRAPHICS POLYGON VERTEX x y
     GRAPHICS POLYGON END

These commands create a polygon in memory before the GRAPHICS DRAW or FILL commands operate on it. To initiate a polygon, execute GRAPHICS POLYGON START. Multiple VERTEX commands are then use to form the polygon from one point to the next by specifying the coordinates of each point. A polygon is completed but not drawn when the GRAPHICS POLYGON END command is executed. Refer to the second example in the GRAPHICS command description.

See also the GRAPHICS DRAW POLYGON and the GRAPHICS FILL POLYGON commands.


GRAPHICS PRINT

Format:

     GRAPHICS PRINT BMP-FILE bmp-filename
     GRAPHICS PRINT BMP-FILE bmp-filename LANDSCAPE
     GRAPHICS PRINT BMP-FILE bmp-filename PORTRAIT
     GRAPHICS PRINT CGM-FILE cgm-filename
     GRAPHICS PRINT CGM-FILE cgm-filename LANDSCAPE
     GRAPHICS PRINT CGM-FILE cgm-filename PORTRAIT

These commands send the specified format to the current printer. Files can be printed in either LANDSCAPE or PORTRAIT mode. If neither is given, portrait is assumed by default.


GRAPHICS SET

Format:

     GRAPHICS SET BACKGROUND color
     GRAPHICS SET CLIP-AREA x1 y1 x2 y2
     GRAPHICS SET FOREGROUND color
     GRAPHICS SET LINE-TYPE line-type
     GRAPHICS SET LINE-WIDTH line-width
     GRAPHICS SET FILL-TYPE fill-type
     GRAPHICS SET RESTORE buf_var
     GRAPHICS SET SAVE buf_var
     GRAPHICS SET TEXT-FONT font
     GRAPHICS SET TEXT-HEIGHT text-height
     GRAPHICS SET WINDOW x1 y1 x2 y2

These commands set a variety of default parameters used by the GRAPHICS DRAW and FILL commands. Using this type of structure differs from the SCREEN commands in that, each time you draw a graphic, you do not need to specify parameters such as foreground and background colors. Instead, a GRAPHICS SET command specifies a particular parameter for subsequent DRAW and FILL commands until it is reset or the graphics environment is closed.

The SET SAVE and SET RESTORE commands allow the storing and subsequent retrieval of all conditions set by the GRAPHICS SET commands. This makes it easy to manage different settings. A common use is to save the settings upon entry to a subroutine and restore upon exit so that calling routines are not affected.

The SET CLIP-AREA coordinates specify a rectangle. Any screen writes that occur outside of the clipped area will not be displayed. To restore the full screen, use:

     GRAPHICS SET CLIP-AREA gr_x1 gr_y1 gr_x2 gr_y2

The related functions below return the currently clipped coordinates:

     GR_CLIPX1, GR_CLIPY1, GR_CLIPX2, GR_CLIPY2

The color, line type, fill type, and text font versions of the GRAPHICS SET commands have constants associated with them:

COLOR | COLOR
0 c_black | 1 c_dark_blue
2 c_dark_green | 3 c_dark_cyan
4 c_dark_red | 5 c_dark_magenta
6 c_brown | 7 c_grey
8 c_dark_grey | 9 c_blue
10 c_green | 11 c_cyan
12 c_red | 13 c_magenta
14 c_yellow | 15 c_white
FILL-TYPE | FILL-TYPE
1 fill_solid | 2 fill_hline
3 fill_vline | 4 fill_grid
5 fill_dbl_hline | 6 fill_dbl_vline
7 fill_dbl_grid | 8 fill_rdiag
9 fill_ldiag | 10 fill_lattice
11 fill_dbl_rdiag | 12 fill_dbl_ldiag
13 fill_dbl_lattice |
TEXT-FONT | TEXT-FONT
1 font_sans_serif_medium | 2 font_sans_serif_medium_italic
3 font_sans_serif_bold | 4 font_sans_serif_bold_italic
5 font_serif_medium | 6 font_serif_medium_italic
7 font_serif_bold | 8 font_serif_bold_italic
9 font_monospaced_medium | 10 font_monospaced_medium_italic
11 font_monospaced_bold | 12 font_monospaced_bold_italic
13 font_script | 14 font_gothic
15 font_greek | 16 font_small_caps
17 font_l_graphic | 18 font_b_graphic
19 font_symbol | 20 font_dingbat2
21 font_dingbat1 |
LINE-TYPE | LINE-TYPE
1 line_solid | 2 line_dash
3 line_dot | 4 line_dash_dot
5 line_dash_dot_dot | 6 line_dash_dash_dot

The GRAPHICS SET commands have a default value (it is not necessary to use them at all providing that you accept these values and do not wish to change them). The defaults are:

BACKGROUND | 0 (c_black)
FOREGROUND | 15 (c_white)
LINE-TYPE | 1 (line_solid)
LINE-WIDTH | 1 (no constant)
FILL-TYPE | 1 (fill_solid)
TEXT-FONT | 1 (font_sans_serif_medium)
TEXT-HEIGHT | 25 (no constant)
WINDOW | device specific

To determine what the current settings are, use the graphics functions. These functions all begin with a gr_ prefix. For example, to discover the current background color, use the gr_background function.

The GRAPHICS SET WINDOW command is a little different. The top left and bottom right coordinates are determined by the output device. A 640x480 VGA mode, for example, will have (0,0) as the top left coordinate and (639,479) for the bottom right. To determine the current size, use the gr_x1 and related functions.


GRAPHICS WINDOW

Formats:
     GRAPHICS WINDOW TITLE text
     GRAPHICS WINDOW CURSOR number

TITLE

This command allows you to change the title bar of the application window. Note that it only works when running the MS Windows or X11 versions and has no effect in the DOS and Unix character versions.

CURSOR

This command changes the window cursor's shape. The number specifies which cursor to use for the current window:

# Constant | Type
0 cursor_default | default cursor
1 cursor_left_pointer | left-pointing arrow
2 cursor_right_pointer | right pointing arrow
3 cursor_cross | cross-hair
4 cursor_wait | hour-glass/watch
5 cursor_beam | "I" beam


IF

Type: Statement
Scope: All
Format:

     IF logical
     commands
     END <IF>

The IF statement is used to conditionally execute commands in a project file. You can use three forms of the IF structure by adding the keywords ELSE and ELSEIF.

The simplest form of the IF structure allows you to conditionally execute a single set of commands. The logical expression after the keyword IF dictates whether the commands following the IF statement will be executed.

If the logical expression evaluates to true (any value except zero), the commands within the IF structure are executed. If the logical expression evaluates to false (zero), the commands within the IF structure are not executed, and the project file continues execution with the command following END IF.

END IF indicates the end of the structure. The keyword IF following END is optional; however, adding it makes it clear that it is the IF statement that is complete, since END is also used in other statements in the SmartWare Programming Language.

Example. This example shows how an invalid password can be identified and rejected with an IF structure. After the password is entered, it is tested in the first line of the IF structure. The variable password is forced to lowercase before it is compared with the true password. If the operator entry does not match the correct password (i.e, the statement is true), the commands within the IF structure are executed. The JUMP command sends project control back to the LABEL get_password line, where the process will repeat until the operator enters the correct password.

     LOCAL password

     LABEL get_password
     SCREEN SHORTINPUT password "Enter the password:"
     IF LOWER(password) <> "pubs"
     BEEP 2 "Invalid password - Please try again"
     JUMP get_password
     END IF


IF-ELSE

Adding ELSE to the basic IF structure allows you to specify two command sets. One set is executed if the logical expression is true and the other if the logical expression is false.

The format for this command is:

     IF logical
     commands
     ELSE
     commands
     END <IF>

If the logical expression is true, the commands between the IF statement and the ELSE statement are executed. If the logical expression is not true, the commands between the ELSE statement and the END IF statement are executed.

Example. This example uses an IF structure with an ELSE statement to determine camping fees. The number of nights is entered along with the resident code. If the camper is a resident, the fee is calculated by multiplying the number of nights by three dollars. If the camper is not a resident, the fee is calculated by multiplying the number of nights by five dollars.

     LOCAL nights, code, rate

     SCREEN CLEAR BOX 2 2 6 35 11 1
     LABEL get_nights
     SCREEN PRINT 4 4 15 1 FORMAT "L30" "Enter the number of nights"
     SCREEN INPUT 4 31 11 1 3 nights MASK "*3{#}"
     nights = VAL(nights)

     IF nights = 0
     BEEP
     JUMP get_nights
     END IF

     SCREEN PRINT 4 4 15 1 FORMAT "L30" "Resident or Non-Resident? "
     SCREEN INPUT 4 31 11 1 1 code MASK "[RrNn]"

     IF LOWER(code) = "r"
     rate = 3
     ELSE
     rate = 5
     END IF

     SCREEN PRINT 4 4 14 1 FORMAT "M30" \
     "The camping fee is "|FORMAT((nights*rate),"2$")

     MESSAGE "Press any key to exit"


IF-ELSEIF

An IF structure may be further expanded with the ELSEIF statement to evaluate a number of logical expressions in sequence. When one of the logical expressions specified by an IF or ELSEIF statement is true, the statements following that logical expression are executed.

The format for this command is:

     IF logical
     commands
     ELSEIF logical
     commands
     <ELSE>
     <commands>
     END <IF>

The logical expressions are evaluated in the sequence in which they occur in the IF structure. If more than one of the logical expressions are true, only the commands following the first true logical expression are executed.

If the logical expression in the IF statement is the first true expression, the commands between the IF statement and the first ELSEIF statement are executed. If a logical expression in an ELSEIF statement is the first true expression, the commands immediately following the ELSEIF statement and preceding the next ELSEIF or ELSE statement are executed.

If there is a chance that none of the logical expressions will be true, the ELSE statement can be used to specify a set of commands to be executed. If the optional ELSE statement is not included and none of the logical expressions is true, the project continues after the END IF statement.

Examples. The following example demonstrates how the IF-ELSEIF structure can be used to execute different commands based on several logical expressions. Suppose the owners of the campground decide to give campers one night free if they stay at least one week and two nights free if they stay two weeks or more.

     LOCAL nights, code, rate, free
     SCREEN CLEAR BOX 2 2 7 35 11 1
     LABEL get_nights
     SCREEN PRINT 3 4 15 1 FORMAT "L30" "Enter the number of nights"
     SCREEN INPUT 3 31 11 1 3 nights MASK "*3{#}"

     nights = VAL(nights)

     IF nights >= 14
     free = 2
     ELSEIF nights >= 7
     free = 1
     ELSEIF nights = 0
     BEEP
     JUMP get_nights
     END IF

     SCREEN PRINT 3 4 15 1 FORMAT "L30" "Resident or Non-Resident? "
     SCREEN INPUT 3 31 11 1 1 code MASK "[RrNn]"

     IF LOWER(code) = "r"
     rate = 3
     ELSE
     rate = 5
     END IF

     SCREEN PRINT 3 4 14 1 FORMAT "M30" \
     "The camping fee is "|FORMAT((nights-free)*rate,"2$")

     IF free > 0
     SCREEN PRINT 5 4 15 1 FORMAT "M30" \
     "They received "|STR(free)|" nights free"
     SCREEN PRINT 6 4 15 1 FORMAT "M30" \
     "and a discount worth "|FORMAT((free*rate),"2$")
     END IF
     MESSAGE "Press any key to exit"

As mentioned before, the logical expressions are evaluated in sequence. The sequence in which you enter them can greatly affect the accuracy of the IF structure. The next example uses an IF structure to determine which prize a sales representative will receive based on monthly sales.

The sequence of logical expressions is critical in this case. If the order were reversed, the logical expression testing for sales greater than or equal to $1,000 would come first. Therefore, sales of $10,000 would cause this condition to be true, and the sales representative would receive a radio instead of a television.

     LOCAL #sales, gift

     SCREEN SHORTINPUT #sales "Enter this month's sales:"
     #sales = VAL(#sales)

     IF #sales >= 10000
     gift = "Television"
     ELSEIF #sales >= 5000
     gift = "Compact Disc Player"
     ELSEIF #sales >= 1000
     gift = "Radio"
     ELSE
     gift = "nothing"
     END IF

     MESSAGE FORMAT(#sales,"2$")&"in sales results in a"&gift|"."


Nested If Structures

IF statement structures may be nested to produce complex decision trees. Nesting IF structures allows you to create virtually any number of IF command formats.

Example. This example adds an additional factor to the camping fee calculation. Senior citizens receive a two dollar discount per night. The project uses a nested IF structure to calculate the camping fee. The fee calculation IF structure first branches based on the value of the resident or non-resident code. Within each of these blocks is a nested IF structure that tests whether the camper is a senior citizen and then assigns the nightly camping fee to the variable rate.

     LOCAL nights, code, rate, free, senior

     SCREEN CLEAR BOX 2 2 9 35 11 1
     LABEL get_nights
     SCREEN PRINT 3 4 15 1 FORMAT "L30" "Enter the number of nights"
     SCREEN INPUT 3 31 11 1 3 nights MASK "*3{#}"

     nights = VAL(nights)

     IF nights >= 14
     free = 2
     ELSEIF nights >= 7
     free = 1
     ELSEIF nights = 0
     BEEP
     JUMP get_nights
     END IF

     SCREEN PRINT 3 4 15 1 FORMAT "L30" "Resident or Non-Resident?"
     SCREEN INPUT 3 31 11 1 1 code MASK "[RrNn]"
     SCREEN PRINT 3 4 15 1 FORMAT "L30" "Senior citizen discount?"
     SCREEN INPUT 3 31 11 1 1 senior MASK "[YyNn]"

     IF LOWER(code) = "r"
     IF senior == "y"
     rate = 1
     ELSE
     rate = 3
     END IF
     ELSE
     IF senior == "y"
     rate = 3
     ELSE
     rate = 5
     END IF
     END IF

     SCREEN PRINT 3 4 14 1 FORMAT "M30" \
     "The camping fee is "|FORMAT((nights-free)*rate,"2$")

     IF free > 0
     SCREEN PRINT 5 4 15 1 FORMAT "M30" \
     "They received "|STR(free)|" nights free"
     SCREEN PRINT 6 4 15 1 FORMAT "M30" \
     "and a discount worth "|FORMAT((free*rate),"2$")|"."
     END IF
     IF senior == "y"
     SCREEN PRINT 8 4 11 1 FORMAT "M30"\
     "Senior discount was "|FORMAT(2*nights,"2$")
     END IF
     MESSAGE "Press any key to exit"


INPORT

Type: Command
Scope: All
OS: DOS Only
Format:

     INPORT port-number  variable

NOTE: A run-time error message will be produced under Unix.

Disigned for use in DOS, the INPORT command retrieves a value from the specified processor I/O port and stores it in the target variable.

In the context of the INPORT command, the term "port" refers to one of the 65,536 eight-bit I/O ports through which the CPU can exchange information with other components in the computer (e.g., video controller, sound generator, math coprocessor, etc.).


INTERRUPT

Type: Command
Scope: All
OS: DOS Only
Format:

     INTERRUPT interrupt-number
     INTERRUPT interrupt-number STACK template expressions

The INTERRUPT command allows you to execute an 80x8x software interrupt using the specified interrupt-number. Using INTERRUPT, you can directly access BIOS and DOS functions, as well as TSR (Terminate and Stay Resident) programs.
IMPORTANT: The INTERRUPT command allows access to programs, drivers, and machine-level functions not normally available from within an application package. It should be used only by an experienced programmer familiar with machine-level operations. Misuse can result in a system failure and loss of data.

Before an INTERRUPT command can be executed, the values of the hardware registers (AX, BX, etc.) must be initialized using the SETREG function. If no changes were made to the registers since SmartWare was accessed, all the registers will be set to zero, except the DS and ES registers. Those will contain the DS segment of SmartWare and the processor FLAGS, which will have interrupts enabled. The SS, SP, CS, and IP registers are not under the user's control.

When the INTERRUPT command is executed, the current state of the machine is saved, the hardware stack is loaded with the specified information (if the STACK option is used), the registers are loaded with the SETREG values, and the interrupt is invoked. Once the interrupt is complete, the current register values are saved for access by the GETREG function, the stack is cleared, and the machine state is restored.
NOTE: For information about the SETREG and GETREG functions, see the Formula Reference Manual. A run-time error message will be produced under Unix.


Placing Information on the Hardware Stack

The STACK option provides for placing information on the hardware stack prior to the interrupt being invoked. The information to be placed on the stack is specified using a template, as discussed in the section titled Buffer/Memory Templates in Project Processing. This is the same format as is used in the PACK and UNPACK commands. The amount of data must be an even number of bytes and must be 64 bytes long or less. The data is pushed on the stack in reverse order.

Example:

     PUBLIC ax_reg
     SETREG (AX,0x0200)
     INTERRUPT 0x16
     ax_reg = GETREG (AX)

     IF (BITAND(ax_reg,1))
     MESSAGE "Right shift key is pressed"
     ELSE
     MESSAGE "Right shift key is not pressed"
     END IF

The example demonstrates the use of the INTERRUPT command to determine the status of the right shift key, using service 2 (get shift status) of BIOS interrupt hex 16. This interrupt assumes the service number to be in the AH register, (the upper half of the AX register). The service value 2 is loaded into AH by loading both halves of the AX register using the SETREG function. INTERRUPT is then executed, returning the shift status into AL (the lower half of the AX register). The value of the AX register is stored for inspection in the variable ax_reg. If bit 0 is on (equal to 1), the right shift key is pressed; otherwise it is not.

Buffer/memory templates
PACK/UNPACK


JUMP

Type: Statement
Scope: All
Format:

     JUMP label

The JUMP statement transfers project control to a specific location in the current project file marked by a LABEL statement.

The specified label must match that used in a LABEL statement in the same project file. When a JUMP statement is executed, the project file continues execution at the specified LABEL statement.
NOTE: Multiple JUMP statements may point to the same LABEL statement. However, all of the LABEL statements in a function must be unique.

JUMP and LABEL statements are very useful for repeating an operator input command if the input is invalid. For example, yes or no responses are commonly requested in project files. In these situations, y or n should be the only acceptable responses. If the operator presses another key by mistake, the mistake should be identified and the operator should be allowed to correct the entry.

Example. The example uses JUMP and LABEL to return to an operator input command. After the operator responds, an IF structure is used to check the contents of the variable. The variable must contain a y or n and can be uppercase or lowercase because the == operator is used in the IF statement. If the contents of the variable is not y or n, the JUMP statement passes control to the LABEL statement, where the operator is prompted for a new entry. The operator cannot proceed until a correct response is entered.
NOTE: Remember from Formula Reference Manual that the operator == converts all text to lowercase to compare it without reference to case.
IMPORTANT: If a JUMP statement specifies a LABEL location that occurs later in the project file and makes a section of the project inaccessible, an error will occur when the project is compiled. To avoid this, place a LABEL statement following the JUMP statement.

     LOCAL $print

     LABEL get_input
     SCREEN SHORTINPUT $print "Do you want to print? (y/n):"
     IF NOT($print == "y" OR $print == "n")
     BEEP
     JUMP get_input
     END If

IF
LABEL


KEY

Type: Command
Scope: All
Formats:

     KEY DEFINE key keylist
     KEY REMOVE key

The KEY commands allow you to define and remove keyboard macros during project execution. A KEY command defines macros that will later be used in a KEYS statement.

The key in both formats is the redefined key, which must evaluate to the text of a valid key name, as specified in the KEYS statement. The keylist is the list of keystrokes issued when the redefined key is pressed or used in a KEYS statement. This must evaluate to the keylist format specified in the KEYS statement.

To avoid conflict with Quick Keys and operator-defined macros, you may assign definitions to numbered "keys" not accessible from the keyboard. They are represented by a pound sign (#) followed by a number from 896 to 1023. These special keys can be defined and used only in Project Processing.

To use a KEY DEFINE macro during project file execution, it must be included in a KEYS statement. Because the key redefined with the KEY DEFINE command is a macro, the KEYS statement that invokes the macro must either contain the keyword LOOKON at the beginning of the KEYS statement or the keyword LOOK immediately preceding the macro key.

The KEY REMOVE command clears from memory a specified macro, whether created in Project Processing or from a module menu. The KEY REMOVE command is the only means of clearing a KEY DEFINE macro from within Project Processing. A KEY DEFINE macro accessible from the keyboard can be cleared using Tools Macros Clear from a module menu. All macros are cleared from memory when you exit the current SmartWare module.

Example:

     KEY DEFINE "Alt-N" """My name is "|user_name|"!"""
     Tools Text-Editor "letter"
     KEYS Look,Alt-N,Enter
     KEY REMOVE "Alt-N"

These statements show how to redefine and invoke the Alt-N key to output a string that includes a variable.
IMPORTANT: If you want to include a double quotation mark in a macro definition, you must use two consecutive double quotation marks. The previous example demonstrates how to incorporate double quotation marks into a string.

     dn_arrows = 5
     KEY DEFINE "#1000" "repeat,#"|STR(dn_arrows)|",Down"
     KEYS LOOK,#1000
     KEY REMOVE "#1000"

This example demonstrates how you could define and use a "numbered" macro key. When this macro is invoked, it simulates pressing the down arrow key five times. By assigning a new value to the dn_arrows variable, you can easily redefine the action produced by the macro key. For more information, refer to the discussion of KEYS statements and macros in the Project Processing Manual.

KEYS


KEY NAME

Type: Command
Scope: All
Format:

     KEY NAME keycode   variable

The KEY NAME command is used to find the name SmartWare uses to describe a key. These key names are used in macros and in KEYS statements.

The keycode parameter is any numeric expression that evaluates to a key's value. The variable is used to store the text name of the key.
NOTE: To obtain the SmartWare key value of a specified key, use the KEYVALUE function. See Formula Reference Manual for more information.

Example:

     LOCAL name
     SCREEN PRINT 22 1 FGPLEASING BGPLEASING "Type any key:"
     KEY NAME INCHAR name
     MESSAGE "You just typed <"|name|">"

This example project displays the Type any key: message on line 22 of the screen and then uses the INCHAR function to pause until a key is pressed and returns the value of the key. The KEY NAME command then converts this value to a name and places it in the variable called name. The MESSAGE command displays a message that includes the key name. For example, if you press the Alt-X key, the message reads You just typed <Alt-X>.

KEYS
MESSAGE


KEYS

Type: Statement
Scope: All
Format:

     KEYS keylist

The KEYS statement enables you to output keystrokes during project file execution. KEYS statements are only effective following a command that anticipates a keyboard entry.

The most common use of the KEYS statement is after one of the SUSPEND commands. These commands cause the project file to pause and return control to a SmartWare application. A KEYS statement placed directly after SUSPEND can take the place of an operator entering keys and output the contents of the keylist.
NOTE: If a project file is paused with one of the SUSPEND commands, it will remain in Command Mode or Enter Mode until F8 is pressed. If you include a KEYS statement following a SUSPEND command, and you want the project to continue when the keylist is exhausted, F8 should be the last key in the keylist. If a SUSPENDONE command is used in conjunction with a KEYS statement, the project will pause only until one complete command has been executed. In this case, the last key doesn't have to be F8.

In addition to the SUSPEND commands, there are other commands that pause project file execution and wait for keyboard input. For example, Tools Preferences Global produces an option screen that is displayed until you press F10. If a KEYS statement is placed directly after a command such as this, the keylist will be executed. F10 should be the last key in the keylist in order to automatically finish this command and resume project execution.


Keylist

The keylist is composed of terms that represent keystrokes. Individual terms in the list must be separated by commas. The keylist can contain character terms, activity control terms, and macro control terms.
NOTE: Macro is a word borrowed from the Tools Macros module command, which is used to create keyboard macros. A KEYS command keylist can contain the same terms as a macro definition. To be consistent, macro control terms describe the set of special keywords that increase the functionality of a macro definition or a keylist.


Character Terms

Character terms represent keys that produce specific characters. When executed, a character term outputs a value that produces a single character. Character terms can represent any of the characters associated with the ASCII values 1-255.

The simplest character terms are the standard characters found on the keyboard. These characters include 0-9, a-z, A-Z, @, $, etc. A single character may stand alone as long as it is separated by commas from previous and following keylist items. Consecutive characters do not have to be separated from each other by commas if they are enclosed, as a group, in quotation marks ("tpg"). A group of characters must be separated from the previous and following terms by commas.

Characters with ASCII values below 32 or above 126 are not represented on the keyboard. These characters may be produced by entering the # symbol, followed by the ASCII value of the character, as a character term in the keylist.

Selected ASCII characters can be produced with special character terms. Most of these special character terms produce common low ASCII characters.

ASCII Value | Character Term | ASCII Value | Character Term
7 | aBell | 8 | aBs
9 | aTab | 10 | aLf
11 | aVtab | 12 | aForm
13 | aCr | 26 | aEOF
27 | aEsc | 255 | aFF


Activity Control Terms

Activity control terms represent keys that initiate an action but do not produce characters. These keys include Quick Keys, function keys, and macro keys that you define. Activity control terms are abbreviations of these action keys. Many activity control terms represent key combinations where one key must be pressed and held while a second key is pressed. The valid activity control terms are listed in the following table. The caret (^) is used to represent the Control key and lowercase s is used to represent the Shift key.

Alt-1 to Alt-0 | Alt-A to Alt-Z | Alt- | Alt=
Alt-F1 to Alt-F12 | ^2 | ^6 | ^a to ^g
^k | ^l | ^n to ^z | ^-
^\ | ^] | ^Bs | sTab
^Home | ^End | ^PgUp | ^PgDn
^Left | ^Right | ^Cr or ^Enter | ^F1 to ^F12
F1 to F12 | sF1 to sF12 | Bs | Tab
Home | End | PgUp | PgDn
Up | Down | Left | Right
Ins | Del | Cr or Enter | Esc


Macro Control Terms

Macro control terms do not represent keys. They are special options used in a keylist that expand the functionality of a KEYS statement.

CLEAR. This keyword clears the keyboard buffer of any keys that may have been pressed by the operator. This term does not clear the remainder of the keylist. CLEAR is useful for ensuring that unintended keys are not supplied to the keylist.

For example, you could begin the SmartWare Word Processor command File Load and fill in part of the filename. If the operator presses keys while the first part of the keylist is being executed, they will be temporarily ignored but will be retained. When the keylist actually does request a key, one of the previously ignored keys will be supplied before the operator has a chance to react. The CLEAR macro control term eliminates this problem.

     SUSPENDONE
     KEYS Alt-L, "region", CLEAR, KEY, Enter

COMMENT. This keyword allows comments to be embedded within the keylist. Text enclosed in quotes between two COMMENT macro control terms is ignored. If COMMENT is inserted into the keylist once, everything after it, to the end of the keylist, is ignored. Comments can help make a KEYS statement easier to understand. However, they do take up memory and should be used sparingly.

     SUSPENDONE
     KEYS Alt-L, "region", CLEAR, KEY, COMMENT, "Key, lets operator"
     KEYS COMMENT "finish filename", COMMENT, Enter

DELAYOFF. This keyword sets the execution speed of the keylist to the default. The default execution speed represents the fastest speed at which a keylist can be output on a specific computer. DELAYOFF is used to turn off a delay begun earlier in a project file by the DELAYON keyword. DELAYOFF is the default setting.

DELAYON, #?. This keyword controls the speed at which the keylist is output. If an operator needs to see the keylist being placed on a screen, the computer's default speed may be too fast. Using DELAYON will allow the keylist to be output at a speed the operator is comfortable with.

A number from 1-1000 is entered after the #, in place of the ?, and represents the number of 1/100ths of a second to be delayed. When it follows DELAYON, the character #? is not considered a character term.

     Tools Text-Editor "test"
     KEYS DELAYON, #20, "abcdefghijklmnopqrstuvwxyz"

KEY. This keyword pauses output of the keylist and waits for a single keystroke from the keyboard. The keystroke not only resumes execution of the keylist but is output as part of the keylist. Using KEY, you can begin a command but let the operator choose how to finish it.

For example, you could start the SmartWare Spreadsheet command Window Titles Fix, let the operator choose columns or rows, complete the command and resume project file execution.

     SUSPENDONE
     KEYS Alt-Z, "wtf", KEY, 1, Enter

LOOK. This keyword instructs SmartWare to use the macro key definition, of the next term only, instead of the key (if a macro has been defined for that key). Macro key definitions will not be executed unless LOOK or LOOKON is used.

For example, Alt-X allows you to edit the last command executed. If you do not use this key, you may decide to redefine it. In order to take advantage of your macro key definition within a keylist, you must use LOOK before Alt-X.

     SUSPEND
     KEYS LOOK, Alt-X

NOLOOK. NOLOOK is the opposite of LOOK. It instructs SmartWare to ignore the macro key definition, of the next term only, and output the key.

For example, Alt-Y switches the module to Enter Mode. Interactively, Alt-Y is not a critical key because you can use Escape to change modes. For this reason, an operator may redefine Alt-Y to do something else. However, you may want to use it in a KEYS command to ensure that the module is in enter mode. NOLOOK will suppress the macro key definition and use the real Alt-Y.

     SUSPEND
     KEYS NOLOOK, Alt-Y, "1116 West 77th Street", F8

LOOKOFF. The definitions of all macro keys after LOOKOFF, but before LOOKON, will be suppressed. If neither of these terms is used, LOOKOFF represents the default mode of execution.

LOOKON. The definitions of all macro keys after LOOKON, but before LOOKOFF, will be used. If LOOKON is used, it will be active until the keylist is complete or a LOOKOFF is encountered.

In the following example, macros defined for the keys Shift-F3 and Ctrl-F1 will be used, because they fall between LOOKON and LOOKOFF. The keys Alt-F7 and F8 fall after LOOKOFF, so their original definitions will be used. Any macros that were defined for these keys will be ignored.

     SUSPEND
     KEYS LOOKON, sF3, ^F1, LOOKOFF, Alt-F7, F8

NOKEY. Placing NOKEY in a keylist protects the rest of the list from being lost if an error message is encountered as the keylist is being output. There may be a rare occasion when you want your keylist to generate an error message. If NOKEY is not used in these situations, the remainder of your keylist may be lost. NOKEY prevents loss of keys and allows a key to clear the message. The rest of the keylist can then be output.

     KEYS <key(s) that generate error>, NOKEY, Esc, <remaining keylist>

If you anticipate that an error message will be generated by a keylist, NOKEY must be inserted after the error generating key. NOKEY must then immediately be followed by a key, such as Escape, which will clear the error message and allow the remainder of the keylist to be output.

Careful consideration must be given to the use of NOKEY. It is important to be aware of why an error is generated, whether it will be generated every time the project is run, and where the program stands when the error is cleared.

PAUSE. This keyword pauses output of the keylist and waits for a single keystroke from the keyboard. The keystroke only resumes execution of the keylist;, it is not output as part of the keylist.

For example, a daily message document is displayed in the SmartWare Word Processor. Several days' messages are in the document, with the most current one displayed at the bottom. PAUSE enables the operator to read the message and press a key when finished.

     File Load "daily"
     SUSPEND
     KEYS ^End, PAUSE, F8

REPEAT, #?, term. This keyword repeats a term the number of times specified by the number entered after #. That number can be 1-65535. When it follows a REPEAT, #? is not considered a character term. Generally, character terms or activity control terms are repeated. However, there are times when it might be useful to repeat a KEY macro control term. A common use of REPEAT is to repeat the arrow keys. For example, you can use REPEAT to position the pointer at a particular item on the Word Processor Preferences menu.

     Tools Preferences Wordprocessor
     KEYS REPEAT, #25, Down, F3, "c:\mydir", Enter, F10

RESULT. This keyword produces the result of the last calculation performed with the Tools Calculator command.

     SUSPEND
     KEYS Alt-Y, "The result is ", RESULT, F8

SCREENOFF. SCREENOFF prohibits repainting of the screen as keys are output. The screen is frozen as it appeared immediately before the SCREENOFF keyword and remains frozen until a SCREENON keyword is encountered or until the keylist is complete.

SCREENON. SCREENON enables screen repainting. The screen will accurately reflect SmartWare's current state when SCREENON is in use. If neither SCREENON nor SCREENOFF is used, SCREENON represents the default mode of execution.
IMPORTANT: The placement of SCREENOFF and SCREENON is very important. See the following example for an explanation.

     SUSPEND
     KEYS SCREENOFF, Alt-Z, "tc", SCREENON, "12345", Enter

In this example, the screen is turned off, the Quick Key Alt-Z is executed to ensure that the module is in the Command Mode, and the Tools Calculator is accessed by "tc." It is important to note that the screen is turned back on immediately after the calculator is invoked. This allows the screen to repaint before the characters "12345" are typed and entered. If the keyword SCREENON is placed after Enter, the screen will not repaint. The calculator will not appear on the screen and keys may be mistakenly entered from the keyboard and can cause unanticipated actions.

UNTIL. This keyword pauses execution of the keylist and inputs all keystrokes from the keyboard until a specified key is pressed. The specified key, which is the key immediately following the UNTIL keyword, resumes keylist execution and is included as part of the keylist. The key must be a character term or an activity control term.

     SUSPEND
     KEYS Alt-Y, UNTIL, Enter, F8

WAITFORKEY. This keyword pauses execution of the keylist and ignores all keystrokes until a specified key is pressed. The specified key only resumes execution of the keylist; it is not included as part of the keylist. The key must be a character term or an activity control term.

     SUSPEND
     KEYS Alt-Y, WAITFOR, F5,F8

SUSPEND
SUSPENDONE


LABEL

Type: Statement
Scope: All
Format:

     LABEL label-name

The LABEL statement marks the destination of a JUMP statement in the current project file.

The LABEL may contain up to 31 characters. The rules for naming variables also apply to naming labels.
NOTE: All of the LABEL statements in a function must be unique. However, multiple JUMP statements may point to the same LABEL statement.

LABEL statements that do not have associated JUMP statements are ignored during project file execution. Refer to the explanation of the JUMP statement.

JUMP


LOAD

UNLOAD

Type: Commands
Scope: All

The LOAD command is the Project Processing equivalent of Remember Load From-File on the module menu. If the optional parameter IN-MEMORY is included, it is equivalent to Remember Load In-Memory.

Format:

     LOAD project
     LOAD project FROM-FILE
     LOAD project IN-MEMORY

The LOAD command activates a project file and executes any statements or commands in the main block. If LOAD is specified by itself or with the FROM-FILE option, execution takes place from the file. If the IN-MEMORY option is specified, the project is loaded in memory, and execution takes place from there. The project is a text expression that is the name of the project you want to activate. This expression may include a path, if necessary.
NOTE: Projects executed in memory run faster than those executed from a file. If there is not enough memory available, the project automatically runs from disk.

Loaded project files remain active until an UNLOAD project command or a Remember Unload module command is executed, or until you exit the current SmartWare module.

The UNLOAD command is the Project Processing equivalent of Remember Unload on the module menu. The project parameter is a text expression that is the name of a SmartWare project file that is currently loaded. This expression should not include path information.

Format:

     UNLOAD project

The UNLOAD command deactivates a project file and, if it is loaded in memory, clears it. This command will unload a project regardless of whether it was loaded from the command menu or in Project Processing. If another project is using functions in the loaded project, the loaded project will not be unloaded until the other project finishes executing.


LOCAL

Type: Statement
Scope: All
Format:

     LOCAL list

The LOCAL statement declares variables and arrays as local. Local variables are limited to use within a single main block or function block in which they were declared. When variables or arrays are declared, they are initialized with a value of zero. Memory is allocated for the variables and arrays when the function is called.

The LOCAL statement must be placed within the main block or within a function. If a LOCAL statement is found outside of the main block or a function, an error will occur and the project file will not compile.

The declaration list may contain variables or arrays. Names must adhere to the rules described in Project Processing and may be the same as global or public variables and arrays. Names in the list may be separated by a comma or a space.
NOTE: Local variables and arrays supersede other classes. A local variable or array will take precedence over a public or global variable or array with the same name in the function or main block in which it is declared.

Array list entries require more than a name; the array dimensions must also be included. The array dimensions must immediately follow the array name and be enclosed in brackets. Arrays can have up to three dimensions. If the array has multiple dimensions, they must be separated by commas. Examples of one-, two-, and three-dimensional arrays are names[20], sales[52,7], and appts[12,31,8].

Local variables and arrays are only known in the main or function block in which they were declared. When execution of the block is complete, the variable or array is automatically deallocated. Deallocation not only deletes the contents but frees the memory the variable or array was occupying. By managing memory in this manner, the amount of available memory is always maximized for the project currently executing.

If another project file is executed from within a section where local variables and arrays have been declared, the local variables and arrays will not be deallocated because the source project file section is not finished executing. Even though these variables will not be deallocated, they cannot be referenced in the destination project file due to their range restriction. In contrast, the TRANSFER command will cause the variables to be deallocated because the source project file will be abandoned.

FUNCTION
MAIN
TRANSFER


LOCATE

Type: Command
Scope: All
Format:

     LOCATE row col <shape>

This command displays a blinking cursor on the screen at a specified location. Three different cursor shapes are available plus the option of turning the cursor off.

The cursor is positioned according to the row and column numbers specified. The upper-left character position on the screen is described as row 1 column 1.

If no value for the shape is specified, the current cursor shape is used. A shape value of 0 specifies no cursor, 1 specifies an underscore, 2 a square, and 3 a rectangle. If you specify a number greater than 3, a runtime error will occur.


LOCK and UNLOCK

Type: Statements
Scope: All

The LOCK statement enables you to save public variables and arrays by overriding the automatic deallocation that occurs when a project file finishes executing.

Formats:

     LOCK MODULE list
     LOCK SYSTEM list
     LOCK BOTH list

LOCK MODULE saves, or locks, variables and arrays until the current module is exited. LOCK SYSTEM locks variables and arrays until SmartWare is exited. LOCK BOTH can be used to attach both types of locks to the variable.

The UNLOCK statement allows you to remove locks that were previously applied to public variables and arrays using the LOCK statement.

Formats:

     UNLOCK MODULE list
     UNLOCK SYSTEM list
     UNLOCK BOTH list

The list in both LOCK and UNLOCK format may contain variable names, array names, or special keywords. Items in the list may be separated by a comma or space. Variable names must be entered in the list just as they were declared. Array names should be entered into the list with trailing brackets to differentiate them from variable names. However, do not include array dimension information within the brackets. An example of an array entry would be stocks[].

There are four keywords that can be included as part of the list of variables to lock. These keywords allow you to lock groups of variables and arrays.

Keyword | Locks...
PUBLIC | all public variables declared in the current project file.
PUBLIC[] | all public arrays declared in the current project file.
EXTERNAL | all variables referenced externally from the current project file.
EXTERNAL[] | all arrays referenced externally from the current project file.

Normally, a public variable or array exists as long as there are project files either executing or loaded that reference it. If a module lock is placed on a variable or array, the variable or array will continue to exist even if all project files finish and are unloaded. The variable or array will be deallocated if the module is exited.

Variables can only be passed to other modules if they are SYSTEM locked. With a SYSTEM lock, a variable will exist until you exit SmartWare.
NOTE: There is a limited amount of memory to available to save locked variables between modules. If this amount is exceeded, an error message will be displayed and some of the variables will be lost.

EXTERNAL
PUBLIC


LOW BUFFER

Type: Command
Scope: All
OS: Different
Formats:

     LOW BUFFER variable SIZE number of bytes
     LOW BUFFER variable SIZEOF template

The LOW BUFFER command uses the same syntax and has the same effect as BUFFER, except that memory is allocated from low memory (under 1 MB). When LOW BUFFER is used, the formulas

     REALPTR(DOSPTR(buffer-variable))
or
     REALSEG(DOSSEG(buffer-variable))

can be used to translate the buffer address into a real mode address than can be passed to real mode or used with PEEK or POKE.

When used with Unix, this command works the same way as BUFFER.

PEEK and POKE
REALPTR and REALSEG


LOW MEMALLOC

Type: Command
Scope: All
OS: Different
Formats:

     LOW MEMALLOC variable SIZE number-of-bytes
     LOW MEMALLOC variable SIZEOF template

In DOS, LOW MEMALLOC uses the same syntax and has the same effect as MEMALLOC, however, memory is allocated from low memory.

The pointer returned by MEMALLOC is a virtual memory pointer but the REALPTR and REALSEG commands can be used to translate the address into a real mode address that can be passed to real mode or used with PEEK and POKE.

When used with Unix, this command is identical to MEMALLOC.

MEMALLOC
REALPTR and REALSEG


LPRINT

LPRINTRAW

Type: Command
Scope: All
Formats:

     LPRINT <expression>
     LPRINT NO-LINEFEED <expression>

LPRINT sends text to the printer through the current SmartWare printer driver. Either a string of text or a single numeric value can be sent to the printer, depending on whether the expression evaluates to text or a numeric value.

Formats:

     LPRINTRAW <expression>
     LPRINTRAW NO-LINEFEED <expression>

LPRINTRAW sends text or control codes directly to the printer, bypassing the current SmartWare printer driver. This allows you to directly control your printer.

Numeric expressions are allowed in LPRINT and LPRINTRAW commands but are not interpreted as text. They are evaluated to a single integer, and the ASCII character represented by that number is sent to the printer.

For example, if you include an expression that evaluates to 90, both of these commands send the letter Z (ASCII 90) to the printer. If a numeric expression is to be printed as a string, it should be converted to text using the STR function.

A linefeed is normally sent to the printer after the string. If no expression is included, a blank line will be printed. The NO-LINEFEED keyword suppresses this, allowing you to print multiple strings on a single line.

LPRINT and LPRINTRAW are very similar; however, LPRINT makes use of the printer driver you currently have selected, while LPRINTRAW sends the expression directly to your printer.
NOTE: The OPEN-PRINTER command must precede LPRINT or LPRINTRAW in a project file.

Example:

     LOCAL $age, $name
     $age = 33
     $name = "Jeff"
     OPEN-PRINTER
     LPRINT "My name is"|$name|"and I am "|STR($age)|"years old"
     LPRINT $age
     CLOSE-PRINTER

The example project produces the following output:

     My name is Jeff and I am 33 years old
     !

The exclamation point is printed because the value of the variable $age (33) was sent to the printer as a numeric value, not as a string. This value is interpreted as the ASCII value 33, which is represented by the character !.
NOTE: The only text that can be sent to a PostScript printer using LPRINTRAW is PostScript code. If the text is to be formatted, you must send it through SmartWare's PostScript driver using the LPRINT command.

OPEN PRINTER


MAIN

Type: Statement
Scope: All
Format:

     <MAIN>
     < commands>
     <END <MAIN>>

The MAIN statement structure represents the main body of a project file. Commands in the main block are immediately executed when you load or run a project file. It is from the main block that other project files or functions can be executed.
NOTE: The MAIN statement is optional in project files. You would not necessarily include a MAIN structure if you were creating a function library.

MAIN is located after any variable declarations. The main block is delimited by the statements MAIN and END MAIN. Using these statements is optional. If the MAIN statement is omitted, SmartWare assumes that the MAIN structure begins where all GLOBAL, PUBLIC, and EXTERNAL statements end. If the project file doesn't contain any variables, the first command in the MAIN structure is the first command in the project file. If the END MAIN statement is omitted, SmartWare ends the main block where the first function begins.

Virtually any command can be used within the main block. As mentioned above, declaration of global, public, and external variables and arrays signifies the beginning of the MAIN structure. However, these statements cannot be included in the MAIN structure. Only local variables may be declared within the MAIN structure.

In addition, the use of the RETURN statement has special meaning if used in the main block. Using the RETURN statement in the main block has the same effect as including an EXIT command, which immediately exits the current project. Because the RETURN statement is not "returning" but actually exiting, it cannot return a value. If you use the RETURN statement in the main block, do not include parentheses.
NOTE: Although GLOBAL, PUBLIC, and EXTERNAL statements can be placed between the MAIN structure and the first function, they cannot be used to signal the end of the MAIN structure. If you place these statements in this position, they must be preceded with END MAIN or an error will occur and the project file will not compile.

EXIT
EXTERNAL
GLOBAL
PUBLIC
RETURN


MEMALLOC

Type: Command
Scope: All
Formats:

     MEMALLOC variable SIZE number-of-bytes
     MEMALLOC variable SIZEOF template

The MEMALLOC command is used to allocate a memory record and store the pointer to the record in a variable. Memory records are used with a number of Project Processing commands. Refer to the section titled Memory Records in Project Processing.

There are two formats for using the MEMALLOC command. The number of bytes to be allocated is specified using the SIZE option and a numeric expression. The number of bytes represented by the numeric expression cannot be zero. MEMALLOC has a size restriction of 65520 bytes (subject to available memory).

The second format is used to allocate a buffer large enough to contain a structure defined by a template. All data items in the template must be explicit, that is, no S (string) or M (memory) types can be used that do not include a length parameter. Refer to the section titled Buffer/Memory Templates in the Project Processing Manual for more information about templates.

The address of (or pointer to) the allocated memory record is placed in the variable. This pointer is a numeric value. All future references to this record require the pointer; but because the address is a number, it can be stored in other variables or passed to functions. Memory records are deallocated using the MEMFREE command, and data is moved into and out of the records using the MEMPACK and MEMUNPACK commands. If not explicitly deallocated, all memory records are freed on exit from the current module, not on termination of the project file.

There is a fixed amount of overhead associated with memory records, amounting to 12 bytes per record; therefore, it is less efficient to allocate small records.
NOTE: In DOS, the MEMALLOC command will return the address of a native memory buffer. If a buffer is to communicate with a real mode program (e.g., a TSR), then the LOW MEMALLOC command must be used.

Buffer/Memory Templates
Memory Records
MEMFREE
MEMPACK/MEMUNPACK


MEMFREE

Type: Command
Scope: All
Formats:

     MEMFREE ALL
     MEMFREE pointer

The MEMFREE command is used to deallocate a memory record that was allocated with the MEMALLOC command. The MEMFREE ALL option will deallocate all currently allocated memory records. The MEMFREE pointer option will deallocate the record indicated by the pointer.

MEMALLOC
Memory Record


MEMPACK

MEMUNPACK

Type: Command
Scope: All
Formats:

     MEMPACK pointer   template   expressions
     MEMUNPACK pointer   template   variables

The MEMPACK and MEMUNPACK commands transfer data to and from a memory record allocated with the MEMALLOC command. The pointer is the pointer to the memory record returned by the MEMALLOC command. This must be the pointer to the beginning of the record.

The data to be transferred is controlled by the template, as discussed in the section titled Buffer/Memory Templates in Project Processing. For more information, refer to the section titled Memory Records, also in Project Processing, and to the discussion of the PACK and UNPACK commands.

Buffer/memory templates
Memory Record
MEMALLOC
PACK/UNPACK


MENU SUPPRESS, MENU ACTIVATE

Type: Command
Scope: All
OS: All
Formats:

     MENU SUPPRESS command
     MENU ACTIVATE command

These commands suppress and re-activate specified commands from the SmartWare menu. Item's are suppressed starting at the specified command and down through the menu hierarchy.

     MENU SUPPRESS "quit"
     MENU SUPPRESS "order change physical"

Note that SUPPRESS does not actually disable the command. Suppressed commands will compile and run within an SPL program and the Alt X key combination still works.


MESSAGE

Type: Command
Scope: All
Format:

     MESSAGE <message>

The MESSAGE command suspends project execution and displays an optional message on the first line of the Control Area. Pressing any key resumes execution.

The message can be a text or numeric expression. If the expression is numeric, it is converted to text as a convenience to the user (i.e., it is equivalent to using the STR function).

Example:

     MESSAGE "Press any key to continue"

The result Press any key to continue appears on the first line of the Control Area.

     MESSAGE "The current time is "|TIME

A text expression concatenated with the TIME function, which returns a text string, produces a message that might read The current time is 11:15:23. You can also concatenate with a variable, as shown here:

     user_name = "Steve"
     MESSAGE "Thanks, "|user_name

The resulting message would read

     Thanks, Steve

     SCREEN PRINT 2 2 7 0 "Hello!"
     MESSAGE

This combination allows you to place text anywhere on the screen and wait for the operator to press a key. With the text expression omitted, the MESSAGE command serves merely to halt processing.

     MESSAGE "The current time is"| &TIME

Compare this example to the one in the MESSAGE command using |. Notice that there is no need to add a space between "is" and the closing quotation mark when you use the ampersand.


MILLI-WAIT

Type: Command
Scope: All
OS: Different
Format:

     MILLI-WAIT milli-seconds

The MILLI-WAIT command is used to pause project execution for very short periods. MILLI-WAIT is followed by a numeric expression that is the number of milli-seconds (1/1000 second) that you wish to delay execution. This command is typically used to provide short delays when you want to show a figure moving on the screen or between SOUND commands.

Example:

     MILLI-WAIT 1000

The first example results in a 1-second delay.

     MILLI-WAIT 50

The second example results in a .05-second delay.

NOTE: On some Unix platforms, the MILLI-WAIT command will round down to the nearest second with a minimum of one second.

Unlike the WAIT command, which uses the CPU timer to determine how long to pause, MILLI-WAIT cycles through a portion of code a calculated number of times to pause for the desired time. The accuracy of this method is dependent upon other activities being carried on within the computer. Generally, the longer the pause, the less accurate it is to use MILLI-WAIT. The maximum delay executed by a MILLI-WAIT command is 10 seconds (MILLI-WAIT 10000). For longer pauses, combine the WAIT command with the MILLI-WAIT command to pause the desired time.

MILLI-WAIT does not allow messages to be displayed, unlike WAIT, which allows a second parameter that displays a text string during the wait. Also, MILLI-WAIT will not abandon the waiting period if a key is pressed.

SOUND
WAIT


NATIVE PEEK

NATIVE POKE

Type: Command
Scope: All
Formats:

     NATIVE PEEK segment  offset  template  variables
     NATIVE POKE segment  offset  template  expressions

These commands are exactly the same as the PEEK and POKE commands. They are used to retain compatibility with previous versions.

REALPTR and REALSEG
PEEK and POKE


ON-ERROR

Type: Command
Scope: All
Formats:

     ON-ERROR FUNCTION function
     ON-ERROR OFF

ON-ERROR calls a user-defined public function when any error occurs.

The function is a text expression that evaluates to the name of the public function to be called. The function must have no arguments but can contain a pair of empty parentheses. A null string for the function name, i.e., the formula

     ON-ERROR FUNCTION " "

is equivalent to ON-ERROR OFF.

When an error occurs, CERROR is set. If error messages are enabled, the message is displayed while the project waits for a key to be pressed and then calls the function declared in the last ON-ERROR function command. If error messages are not enabled, the project calls the function immediately.

During execution of the ON-ERROR function, ON-ERROR itself is temporarily disabled. Following execution of the function, ON-ERROR is re-enabled. This prevents an error in the ON-ERROR function from causing an infinite loop.

CERROR is restored after execution of the function to the value it had prior to the ON-ERROR function call. This means that CERROR can be tested after a command failure, even when an ON-ERROR function is in effect.

LERROR, on the other hand, is not restored after execution of the function. It reports the number of the last error, even if it occurred in the ON-ERROR function. This allows CLEARERROR commands to be placed inside the ON-ERROR function. If no CLEARERROR or error message is used in the ON-ERROR function, and no error occurs, then LERROR will be equivalent to CERROR.

ON-ERROR function commands remain in effect until project execution is complete or until an ON-ERROR OFF command is executed.


Using ON-ERROR with $_onerror

The current ON--ERROR setting can also be read with the SMARTPOKE $_onerror command, which returns the current on-error function name. You can use the syntax ON--ERROR FUNCTION " " as an alternative to ON--ERROR OFF when you are using the SMARTPEEK/SMARTPOKE option $_onerror. If no error is in effect, $on_error returns an empty string (" "). ON--ERROR FUNCTION " " allows you to preserve the current on-error status. You can also restore the previous on-error status by using ON--ERROR FUNCTION with the result.

     Example:

     LOCAL saveerror

     SMARTPEEK $_onerror saveerror    ' Save current state on
' on-error
     ON--ERROR FUNCTION "newname"     ' Set new on-error function
.
.
.
     ON--ERROR FUNCTION saveerror    ' Restore previous on-error
' state, which may have been OFF

See the discussion of the SMARTPEEK and SMARTPOKE commands.


Chained Projects

Chained projects (i.e., projects called with the EXECUTE command) are treated by ON-ERROR commands as one large project, so one ON-ERROR command affects all projects.

Example:

     PUBLIC custom_error_routine ()
     (etc.)
     ON-ERROR FUNCTION "custom_error_routine ()"
     (etc.)
     File Load Custom-View region 1
     File Load Custom-View region 2
     (etc.)
     FUNCTION custom_error_routine ()
     SCREEN CLEAR BOX 5 15 7 65 15 4
     SCREEN PRINT 6 21 15 4 "An error has occurred"
     MESSAGE "Press any key to continue"
     END FUNCTION

Here, custom_error_routine is declared a public function. Later in the project, ON-ERROR is executed, instructing the project to call custom_error_routine any time an error occurs. In this case, the ON-ERROR function clears a box on the screen, prints a message in the box, and suspends processing until a key is pressed.

CLEARERROR
FUNCTION
PUBLIC


OPEN-PRINTER

Type: Command
Scope: All
Format:

     OPEN-PRINTER
     OPEN-PRINTER RAW

This command must precede any LPRINT or LPRINTRAW commands to signal the beginning of a print job.

OPEN-PRINTER sets up the printer port, initializes the printer driver selected on the Hardware Preferences menu, and sets certain internal variables used in printing. It does not check whether the printer is attached or ready to print.

OPEN-PRINTER can be used anywhere in a project file but must precede the first LPRINT or LPRINTRAW command. A CLOSE-PRINTER command should follow the last LPRINT or LPRINTRAW command to signal the end of the print session.

OPEN-PRINTER RAW initializes the printer for LPRINTRAW printing only. Normally, when OPEN--PRINTER is used, initialization information that will affect subsequent LPRINTRAW commands will be sent to the printer. Also, a CLOSE-PRINTER command following an OPEN-PRINTER command will cause a page to be ejected.

OPEN-PRINTER RAW does not send any initialization information to the printer, nor does it eject a page when followed by a CLOSE-PRINTER command. You should use OPEN-PRINTER RAW for absolute control over information sent to the printer.

When OPEN-PRINTER RAW is used, LPRINT commands are not valid and will generate an error. LPRINTRAW commands may still be used when OPEN-PRINTER is used, but the effects will be difficult to predict.
IMPORTANT: OPEN-PRINTER and CLOSE-PRINTER define print jobs comprised solely of LPRINT and LPRINTRAW commands. Other commands resulting in printed output will give highly unpredictable results when used inside the OPEN-PRINTER/CLOSE-PRINTER loop. Mixing LPRINT and LPRINTRAW commands in the same print job may also give unpredictable results.

CLOSE-PRINTER
LPRINT/LPRINTRAW


OSEXIT

Type: Command
Scope: All
Formats:

     OSEXIT ON
     OSEXIT OFF

The OSEXIT command controls access to the operating system during periods when Project Processing is suspended.

There are two ways to access the operating system from within SmartWare: one is with the Tools Os command on each module menu; the other is with the Ctrl-O Quick Key. Both are normally available in Project Processing during project suspension.

OSEXIT OFF blocks access to the operating system and can be executed prior to suspension to prevent users from issuing undesirable operating system commands before processing resumes. OSEXIT OFF remains in effect until OSEXIT ON is executed or until project execution is complete.


OUTPORT

Type: Command
Scope: All
OS: DOS Only
Format:

     OUTPORT port-number  expression

The OUTPORT command sends a numeric value to the processor I/O port named in the port-number parameter.

In the context of the OUTPORT command, the term "port" refers to one of the 65,536 eight-bit I/O ports through which the CPU can exchange information with other components in the computer (e.g., video controller, sound generator, math coprocessor, etc.).
IMPORTANT: This command can be dangerous if used incorrectly. Only developers familiar with I/O ports and their uses should use this command.
NOTE: A run-time error message will be produced under Unix.


PACK

UNPACK

Type: Commands
Scope: All

The PACK command is used to store data in a variable previously declared with the BUFFER command. The data is stored as specified in the template. UNPACK is used to transfer data from a buffer and store it in variables that can be used to process the information in a project file or in an buffer variable.

The PACK command is used to store information in a buffer as a set of binary records. This is useful when you use the FWRITE BINARY command and the INTERRUPT command.

Format:

     PACK buffer-variable   template   expressions

Normally, SmartWare processes two types of data, numbers and text. The PACK command provides a way of transferring SmartWare data into fields within a buffer in a structured manner.

To begin this process, use the BUFFER command to create an empty buffer. The buffer provides a block of zeroed bytes of a specified length, which is referenced by a variable name. Internally, this is stored identically to a text string. In fact, a normal SmartWare variable containing a text string can be used as a buffer; however, because a buffer filled with the PACK command can contain binary zero bytes, it usually cannot be used as a string.

Information is transferred to this buffer using a template that defines what the format of the data in the buffer will be and where in the buffer the data will be placed. The buffer variable must be at least as large as the total number of bytes defined in the template. If the variable is not large enough to hold all of the expressions, SmartWare stores the expressions until all the space in the buffer variable is used and then generates a runtime error.

Within the template, a code is used to indicate the type of data to be placed in each field, as well as the size of the field. For each code that indicates data is to be transferred, there must be a corresponding expression following the template. The template may be very simple or very complex. Refer to the sections titled Buffer Variables and Buffer/Memory Templates in the Project Processing for more specific information about buffer variables and template options.

At the start of the pack operation, an internal pointer is set to the beginning of the buffer. The first code in the template is processed, and data is stored at the pointer location. The pointer is then moved ahead the length of the data, and the next code is processed. This continues until all codes are processed. Any portions of the buffer not reached by the template are left unchanged.

The expression can be any valid text or numeric expression, but there must be a sufficient number of expressions to satisfy all of the format options.

Examples. In the first example, an array of numbers must be passed to another module. The LOCK SYSTEM command can also be used for arrays.
NOTE: You can pass only about 6,000 bytes of total data from one module to another.

     'Array to be passed
     PUBLIC sarray[20]
     'Data to be packed in this variable
     PUBLIC holdarrray

     'ptr will be offset into PACK variable
     'Counter will be offset into array
     LOCAL ptr, counter

     'Need to fit 20 8-byte doubles
     BUFFER holdarray SIZEOF "20d"
     'Start at beginning of PACK buffer
     ptr = 1

     FOR counter = 1 TO 20
     'Pack each array element
     PACK holdarray[ptr] "d" sarray[counter]
     'Move to next PACK position
     ptr = ptr + 8
     END FOR

     LOCK SYSTEM holdarray

String arrays can also be handled in this manner; however, you may not know how far to move the pointer. If the array is small, you can let the PACK command move the pointer. For example, suppose you have defined a four-element array, as follows:

     PACK holdarray "4(s)" sarray[1] sarray[2] sarray[3] sarray[4]

The four strings are represented by "4(s)". (It is important to include the parentheses; "4s" would have meant one string of length 4.) If the string has many more elements, though, you may wish to use the following structure:

     ptr = 1

     FOR counter = 1 to 20
     PACK holdarray[ptr] "s" sarray[counter]
     ptr = ptr + LEN(sarray[counter]) + 1
     END FOR
NOTE: It is necessary to add "+1" to account for the zero byte that terminates the string.

The UNPACK command reads data that was stored in a buffer variable with the PACK command and stores it in variables that can be used to process the information in a project file or in another buffer variable.

Format:

     UNPACK buffer-variable  template  destination-variables

The information retrieved is stored in the destination variable according to the template specified. There must be one destination variable for each template option specified.
IMPORTANT: In order to read the information correctly, the template used in the UNPACK command must be equivalent to the template used in the corresponding PACK command.

To unpack the data shown in the first PACK example, simply reverse the process:

     ptr = 1

     FOR counter = 1 TO 20
     'Unpack each array element
     UNPACK holdarray[ptr] "d" sarray[counter]
     'Move to next PACK position
     ptr = ptr + 8
     END FOR
NOTE: It is possible to pack or unpack a buffer in more than one step, using successive PACK or UNPACK commands, respectively. If a character offset is used on the variable, the unpack operation will begin at that offset into the buffer.

FWRITE
INTERRUPT


PEEK and POKE

Type: Commands
Scope: All
Formats:

     PEEK segment  offset  template  variables
     POKE segment  offset  template  expressions

The PEEK and POKE commands, which are generally used in the DOS environment, transfer data to and from a specified memory area in the 80x8x memory space. PEEK moves data from a memory area to a set of variables, while POKE moves data from a set of expressions to a memory area.

NOTE: PEEK and POKE are intended for use in the DOS environment but can be used to inspect or change the values of buffer variables and allocated memory in place of the PACK, UNPACK, MEMPACK, and MEMUNPACK commands.

The memory area to operate on is defined by the segment and offset parameters. Because PEEK and POKE access real mode memory, segment and offset parameters must be real mode addresses. The data to transfer is controlled by the template, which is the same format as is used in the PACK and UNPACK commands. See the section titled Buffer/Memory Templates in the Project Procesing Manual for more information about templates.

No checking is performed on data that is stored or retrieved. Therefore, you should use extreme caution when you execute these commands because it is possible to overwrite any portion of the CPU address space, including SmartWare, DOS, and the interrupt vector table. Interrupts are not disabled during transfer of data, so do not use these commands to set interrupt vectors or to modify data that might be used if an interrupt occurred during the data transfer. Also, be aware that an offset and template combination that would cause data to be stored across a segment boundary will generally cause that data to be stored at the beginning of the segment (i.e., overflow of the offset does not affect the segment).

Example:

The first example returns the number of diskette drives installed in the system. The information regarding the currently installed equipment is stored in bytes 0x410 and 0x411 at segment 0. Bits 6 and 7 in byte 0x411 hold the number of diskette drives, where 0 means 1 drive and 1 means 2 drives.

     LOCAL drives
     'Get the data
     PEEK 0 0x411 "C" equipment
     'Mask off bytes 6 and 7
     drives = equipment/(2^6+2^7)
     'Print the numeric result using the STR function
     MESSAGE "The number of drives installed is "STR((INT(drives)+1))

In the second example, the POKE command is used to write three ASCII character values to the display memory located at segment 0xB000 and offset 0x800. This will make the characters A, B, and C (ASCII 65, 66, and 67) appear in the upper-left corner of the screen.

     POKE 0xB000 0x8000 "C" 65
     POKE 0xB000 0x8000+2 "C" 66
     POKE 0xB000 0x8000+4 "C" 67
IMPORTANT: This example assumes you are using an 80x25, CGA, text-mode driver. It is dangerous to write values to memory if you are not very familiar with the memory locations you are altering.


PULLDOWN

Type: Command
Scope: All
Formats:

     PULLDOWN INIT <menu id> usermode language
     PULLDOWN FINISHED BLANK
     PULLDOWN FINISHED DESTROY

Pulldown menus are controlled by SPL programs. SPL source code is provided. It is quite easy to extend or modify the pulldown menus.

The source code is bundled with the sample application and can be viewed by selecting PROGRAMMING EXAMPLES then SOURCE CODE from the main menu.

When adding new functionality, it is recommended that you do not modify the provided SPL source. This will minimize your work when new versions become available. Your own SPL libraries can be integrated into the pulldown menu system by using the MNU_LIBRARY field in the header of the menu file. For example, add the following line to the [ROOTMENU] section of the menu file:

     $MNU_LIBRARY = <your project file>

The library specified must have a public function named 'do_lib_act'. It must have two parameters in which the action and object specified in the menu file will be passed. Returning 1 from do_lib_act signifies that the action was handled. Returning 0 indicates that the passed action is not one that the program is concerned with. The following is a simple example:

     PUBLIC do_lib_act()

     FUNCTION do_lib_act( $act, $obj )
         IF $act = "myact"
            ' commands
            RETURN 1
        END IF
     END FUNCTION

You will need to add an entry to the pulldown menu file. For example:

     [ITEM]
     {
         $MNU_DESC = DEFAULT My Command
         $MNU_ACT = myact
         $MNU_CH_KEY = 62032
     }

If you want to remove items, edit the menu file and leave the SPL code in place.

Calling the Pulldowns From a Project

Due to the tight integration between SmartWare itself and the pulldown menu programs, you may not access the pulldowns from a project with the TOOLS PREFERNCES PULLDOWNS command. Instead, you must TRANSFER to the pd.rf0 program located in the OASYS directory. For example:

     TRANSFER PATH(syspath)|"pd.rf0" IN-MEMORY

As experienced SPL programmers will point out, the TRANSFER command effectively terminates the currently running program. The only way regain control of the project file is to send a 'message' to the pulldown menus which is acted upon when the user terminates the pulldowns. The way to communicate this message is to set a public variable named ##resume_md to the project file name to execute upon pulldown termination.

MNU_OPEN
TOOLBAR
STATUSBAR


PUBLIC

Type: Statement
Scope: All
Format:

     PUBLIC list

The PUBLIC statement declares variables, arrays, and functions as public. Public variables can be referenced in more than one project file. When variables or arrays are declared, they are initialized with a value of zero. Memory is allocated for public variables and arrays when a project starts, unless the variables already exist.

The public variable, array, and function declarations must be placed outside of a block and are usually placed before the main block. However, it is acceptable to place public declarations after the main block as long as they are not within a function. If a PUBLIC statement is found within a block, an error will occur, and the project file will not compile.

The list may contain variables, arrays, or functions. Names must adhere to the rules described in Project Processing Manual and may be the same as local variables and arrays. A public variable or array cannot have the same name as a global variable, array, or function. Names in the list may be separated by a comma or a space.
NOTE: Public and external variables declared within the same project must have unique names. If a public variable is referenced within a function that has a local variable declared with the same name, the local variable will take precedence.

Array list entries require more than a name; the array dimensions must also be included. Array dimensions must immediately follow the array name and be enclosed in brackets. Arrays can have up to three dimensions. If the array has multiple dimensions, they must be separated by commas. Examples of one-, two-, and three-dimensional arrays are names[20], sales[52,7], and appts[12,31,8]. For more information about array dimensions, refer to the Project Processing Manual.

Function names should be entered into the list with trailing parentheses to differentiate them from variable names. Optionally, you may enter a number within the parentheses that represents the number of arguments required by the function. Examples of function entries include boxtext(1) and create_file(2). Including the number of arguments gives SmartWare additional error-checking capability.

Public variables and arrays can be referenced throughout the currently executing project file as well as in other project files in the same module. When execution of all project files referencing the variable or array is complete, or the project files are unloaded, the variable or array is automatically deallocated. Deallocation not only deletes the contents but frees the memory that the variable or array was occupying.

Public functions can also be referenced throughout the current module. They remain available as long as the project file they are contained in is executing or loaded.
NOTE: The PUBLIC statement allows other project files to use variables, arrays, and functions from the current project file. To use them, other project files must include the EXTERNAL statement before referencing public variables, arrays, or functions.

By using the LOCK statement, you can save public variables for use even after the project that declared them is unloaded.

EXTERNAL
LOCK and UNLOCK


QUIET

Type: Command
Scope: All
Formats:

     QUIET ON
     QUIET OFF

The QUIET commands turn the display of command lines on or off during project file execution.

The QUIET OFF command can be used to display commands on the Status Line as they are being executed and is useful for debugging a project file. If an error occurs at runtime, the error message and the current command are displayed. The QUIET ON command can be used to suppress the display of the commands as they are being executed.

In order for QUIET OFF to display command lines, the text versions of the commands must be available. As long as you do not use the DEBUG OFF statement in your project file, the text statements will be available when either of the following conditions is met:
*** The project file is compiled by pressing F10 after loading it into the Project Editor.
** The project file is compiled with the Remember Tools Compile Debug command.

If you use the DEBUG OFF command, text statements will not be available if they fall between DEBUG OFF and DEBUG ON or the end of the project file, regardless of how the project is compiled. They will also not appear if you use the Remember Tools Compile No-Debug command.

When you select QUIET OFF, the command and the line number appear on the Status Line. For example, 56: QUIET OFF would appear on the Status Line if the QUIET OFF command were on line 56 of the project file. The QUIET OFF command is helpful when you are debugging a project file because the command display allows you to see the command that was being executed when an error occurred.

It is not necessary for you to enter QUIET commands in every project file. You need to enter them only when you want to change the current or default setting. The default setting is specified on the Global Preferences definition menu. The default setting is the current setting, until it is changed in a project file. For example, if the default setting is QUIET ON, and you want the commands to display during execution, you would enter QUIET OFF in the project file. The QUIET OFF command becomes the current setting; until it is changed, all project commands are displayed.
NOTE: The QUIET OFF setting cannot be changed by removing the command and recompiling; you must include a QUIET ON command.

The QUIET command setting, whether set on the Global Preferences definition menu or within a project file, affects all project files in the current session of SmartWare. If you execute a project file that contains a QUIET OFF command, then execute a second project file that does not have a QUIET command, the QUIET OFF setting will be used during its execution.

You are not limited to using only one QUIET command in a project file. You may turn the QUIET commands on and off wherever you want. For example, you may use QUIET OFF to display commands in one section of a project file, then use QUIET ON to suppress the display of commands in the rest of the file.

DEBUG


REAL FARCALL

Type: Command
Scope: All
OS: DOS Only
Format:

     REAL FARCALL address

REAL FARCALL is similar to the FARCALL command, except that the pointer must be a real mode pointer, no STACK option is available, and data may be passed in registers. Note that any addresses passed in registers should generally be real mode addresses.

When using REAL FARCALL, the CPU is switched to real mode and the call is made. Because of this, virtual addresses will have no meaning while the call is being made. Any addresses passed back by the called function are probably real mode addresses and will need to be translated to virtual addresses using the VIRSEG command before data can be accessed. The exception to this is if the address is already pointing to a LOW BUFFER or LOW MEMALLOC record for which you have virtual addresses.

REAL FARCALL operates the same as FARCALL except the STACK option is not allowed and data may be passed in registers.

REAL FARCALL does not use the FLAGS register setting. The FLAGS value returned by GETREG(FLAGS) after the REAL FARCALL does not reflect the flags on return from the function. Refer to the GETREG function in Formula Reference Manual for more information on the FLAGS register setting.

NOTE: A run-time error message will be produced under Unix.

FARCALL


REAL INTERRUPT

Type: Command
Scope: All
OS: DOS Only
Format:

     REAL INTERRUPT interrupt-number

This command switches the CPU to real mode before an interrupt is signaled. It operates the same as INTERRUPT with the following exceptions:
*** no STACK option is available
** any addresses placed in registers should be real mode addresses

REAL INTERRUPT ensures that a project will invoke a real mode interrupt vector for any interrupt.

A run-time error message will be produced under Unix.

INTERRUPT


REALPTR

REALSEG

Type: Command
Scope: All
OS: DOS Only
Format:

     REALPTR INTO var FROM virtual pointer
     REALSEG INTO var FROM virtual-segment

REALPTR and REALSEG each take a virtual pointer or segment and place an equivalent real memory pointer or segment into the variable, provided that the memory addressed by the virtual address is under 1 MB. If the memory is above 1 MB, then a 0 will be returned and an error issued.

These commands are most commonly used in conjunction with LOW BUFFER or LOW MEMALLOC to pass addresses of those buffers to real mode code. For example, if you need to pass the address of a buffer in AX (segment) and BX (offset) to a REAL FARCALL function, you could use either LOW MEMALLOC or LOW BUFFER as seen in the following options:

Example 1 (LOW MEMALLOC):

     LOCAL virtualp, realp

     LOW MEMALLOC virtualp SIZE 100

     REALPTR INTO realp FROM virtualp
     SETREG(AX, SEGMENTOF(realp))
     SEGREG(BX, OFFSETOF(realp))

     REAL FARCALL . . .

Example 2 (LOW BUFFER):

     LOCAL realp, bufvar

     LOW BUFFER bufvar SIZE 100

     REALPTR INTO realp FROM DOSPTR(bufvar)
     SETREG(AX, SEGMENTOF(realp))
     SEGREG(BX, OFFSETOF(realp))

     REAL FARCALL . . .

NOTE: A run-time error will be produced under Unix.

LOW BUFFER
LOW MEMALLOC


REDIMENSION

Type: Command
Scope: All
Format:

     REDIMENSION array[#,#,#]

The REDIMENSION command is used to increase or decrease the size of an existing array to the sizes of the specified dimensions. The existing array must have been declared previously with the same number of dimensions as specified in the REDIMENSION command. The original dimension sizes are disregarded, and the new dimension sizes are used to recreate the array.
IMPORTANT: All existing data is lost when an array is redimensioned. You should determine whether to resize the array before loading any data into it.

The REDIMENSION command is useful for adapting arrays to the current situation. If you want an array to hold varying amounts of data, you probably will not be able to predict how large to make the array. Making the array large enough to handle the largest possible case wastes memory by creating elements that are not used. REDIMENSION lets you resize the array at runtime after determining the amount of data you need to store in the array.

Example. The following example illustrates how to redimension the array student_exams [1,1].

     GLOBAL student_exams [1,1]
     'Assume you are prompted for the number of students
     'and exam scores, and that those values are stored in 2
     'global variables:  "kids" and "tests".
     'Redimension the array to the proper size
     REDIMENSION student_exams [kids,tests]


REF

Type: Statement
Scope: All
Format:

     FUNCTION name(REF arg1, REF arg2, ... )
     commands
     END <FUNCTION>

Each argument can be declared as passed by value or by reference. An argument passed by value gets a copy of the value passed in the function call. An argument declared to be passed by reference gets a reference to the variable passed in the function call. Use the REF keyword to pass an argument by reference.

Example:
     GLOBAL change_me()
     MAIN
        local i
        i = 3
        change_me(i)
        message str(i) 'i now equals 5 because it was passed as reference
     END MAIN

     FUNCTION change_me(REF arg)
        arg = 5
     END FUNCTION

FUNCTION


REPAINT

Type: Command
Scope: All
Formats:

     REPAINT
     REPAINT ON
     REPAINT OFF

The REPAINT commands control the screen display during project file execution. Normally, during project file execution, SmartWare' screen display reflects the actions brought about as each command is executed.

The REPAINT command clears the screen and displays the current SmartWare screen. REPAINT OFF prevents any SmartWare command except project commands and errors to show on the screen, although the commands are still executed. REPAINT OFF is helpful when you create and use custom menus in your project because it allows the menu to remain on the screen while the project commands are executed.

REPAINT ON allows SmartWare commands to be shown on-screen but does not refresh the screen. Use REPAINT to repaint the screen with the current module information.


REPLY

Type: Command
Scope: All
Formats:

     REPLY ON CHAR character TO prompt#
     REPLY ON ESCAPE TO prompt#
     REPLY ON NOTHING TO prompt#
     REPLY CHAR character TO prompt#
     REPLY ESCAPE TO prompt#
     REPLY NOTHING TO prompt#
     REPLY OFF TO prompt#
     REPLY OFF TO ALL
     REPLY ALWAYS NOTHING
     REPLY OFF TO ALL

Many module commands require a user to respond to a question before SmartWare can actually complete the execution of that command. For example, when you try to unload a document that has been edited but not saved, you are required to respond to the question Save modified document? (y/n). Otherwise, the File Unload command cannot be executed. These questions are called interactive prompts.

During project file execution, SmartWare provides default responses to most of the interactive prompts. This enables project execution to continue uninterrupted. The REPLY commands allow you to override the default response to any of these interactive prompts.

To override a default response, you must identify the prompt by number. A list of all the interactive prompts and their corresponding numbers can be found in Appendix B of Project Processing.

The REPLY ON CHAR and REPLY CHAR commands can each change the default response to a single interactive prompt. The character parameter refers to the response you want entered for the interactive prompt specified. This parameter is a text expression that could be "y" or "n," for example. The prompt# parameter refers to the number of the interactive prompt to which you want to respond.

The difference between REPLY ON CHAR and REPLY CHAR is that the REPLY ON CHAR command changes the default response for the duration of the current project and any projects run by the current project. The REPLY CHAR command changes the default only temporarily.

When the default response is temporarily changed, the response is only good for the command immediately following the REPLY command and is cleared regardless of whether it is used. It may, however, be used more than once within the command. When the default is changed permanently, the new response will be used each time the project generates that interactive prompt. The original default responses are restored upon completion of project execution.

Although all interactive prompts have character responses, some prompts may be cleared by pressing Escape. The REPLY ON ESCAPE and REPLY ESCAPE commands supply responses equivalent to pressing Escape to the specified prompt. The difference between these two commands is that REPLY ON ESCAPE changes the default response and the REPLY ESCAPE command changes the response temporarily.

The REPLY ON NOTHING and REPLY NOTHING commands suppress the default response to the prompt specified and force the prompt to be displayed as if it were encountered interactively. The operator must then supply a response to the prompt before project execution can continue, despite any default Project Processing would normally use.

For those responses that were changed permanently, you can change them back to the original default response by using either REPLY OFF command. The REPLY OFF TO prompt# command changes the response back to the original default for a single interactive prompt. The REPLY OFF TO ALL command changes every prompt referenced by a REPLY ON command back to its original default response.

The REPLY ALWAYS NOTHING and REPLY OFF TO ALL commands will turn on, and off, prompting for all prompts when under SPL program control.

The following items are important to keep in mind while using the REPLY commands:
*** If multiple REPLY commands set a combination of temporary and permanent responses to the same prompt, the last temporary response will take precedence. All temporary responses are cleared once the command following the REPLY command is executed. The permanent responses remain.
** If multiple REPLY commands set permanent responses to the same prompt, the responses are stacked. The last response is the active one. If REPLY OFF is used to clear the response to a prompt, only the last response is cleared and the second to last response becomes active.
** The project may include more than 20 REPLY commands, but only 20 can be active at any one time. If the total of permanent and temporary REPLY commands that are in effect at any one time equals 20, any additional REPLY commands will be ignored.


RETURN

Type: Statement
Scope: All
Format:

     RETURN <expression>

Used within a function, the RETURN statement enables you to pass a result from the function to the calling statement.

The optional expression may be either a text expression or a numeric expression. If you omit the expression, zero is returned to the calling statement.
NOTE: In addition to using RETURN in a function, it can be used within a main block. RETURN has the same effect as EXIT MAIN when it is used in a MAIN statement, i.e., the project is exited. Because the RETURN statement is not actually "returning" but is instead exiting, it cannot return a value. If you use RETURN in a main block, you should not include parentheses.

Example. This example demonstrates how the RETURN statement can be used in functions and in the main block. The function comp_num() returns the largest of three numbers passed to it as arguments. The RETURN statement in the main block accomplishes the same action as an EXIT statement.

     GLOBAL comp_num(3)

     MAIN
     LOCAL max_num

     max_num = comp_num(1,2,3)
     MESSAGE "The largest number was "|STR(max_num)

     RETURN
     END MAIN

     FUNCTION comp_num(num1, num2, num3)
     IF num1 > num2
     IF num1 > num3
     RETURN (num1)
     ELSE
     RETURN (num3)
     END IF
     ELSEIF num2 > num3
     RETURN (num2)
     ELSE
     RETURN (num3)
     END IF
     END FUNCTION

For more information, refer to the discussions on the FUNCTION and MAIN statements in the Project Processing Manual.


SCREEN

Type: Command
Scope: All

The SCREEN commands control display areas and colors. Five common parameters appear in most SCREEN command formats. They are row, col, fg, bg, and target.

The row and col parameters specify positioning on the screen. The row parameter is a number between 1 and the maximum number of lines displayable on your screen. The col parameter is a number between 1 and the maximum number of displayable horizontal positions on your screen. Row and column numbers are always specified as pairs, each pair representing a single character position on the screen. If one row and column pair is required, the specified position represents an upper-left corner. The command affects the screen area to the right and below this position. If two row and column pairs are required, the specified positions represent an upper-left and a lower-right corner, respectively. The command affects the screen area between these two positions.
NOTE: The maximum number of displayable horizontal and vertical positions can be determined by using the SCRWIDTH and SCRHEIGHT functions. See Formula Reference Manual for more information.

The fg and bg parameters specify foreground and background colors of information displayed on the screen by use of SCREEN commands. Foreground and background colors are entered as numbers between 0 and 15. The colors that these numbers produce depend on the display adapter and monitor currently installed. If you are using an EGA adapter, the colors you have available correspond to those shown in the following table:

0 - Black | 8 - Dark Grey
1 - Blue | 9 - Light Blue
2 - Green | 10 - Light Green
3 - Cyan | 11 - Light Cyan
4 - Red | 12 - Light Red
5 - Magenta | 13 - Light Magenta
6 - Brown | 14 - Yellow
7 - White | 15 - Intense White

The target parameter specifies a destination for a piece of data. In commands where the operator is prompted to enter data, a place for data storage is necessary. A target specified in a command format can be a variable, a field reference, if the project file is executing in SmartWare Database, or a cell reference, if the project file is executing in SmartWare Spreadsheet.
IMPORTANT: Specifying screen locations that are outside the boundaries of your screen can potentially overwrite memory other than screen memory and could even result in system failure. Wysiwyg screen drivers are particularly susceptible to this problem.


SCREEN CLEAR

Format:

     SCREEN CLEAR fg  bg
     SCREEN CLEAR fg  bg NO--BORDER

SCREEN CLEAR clears the data area of the screen from the upper-left corner to the lower-right corner above the menu line and repaints the data area with the specified foreground and background colors. The foreground color is used for the border, and the background color is used for the area behind and within the border. If the optional NO--BORDER keyword is entered, the entire area is cleared to the background color.


SCREEN CLEAR BOX

Formats:

     SCREEN CLEAR BOX row  col  row  col  fg  bg
     SCREEN CLEAR BOX row  col  row  col  fg  bg <NO--BORDER>

SCREEN CLEAR BOX clears an area identified by upper-left corner and lower-right corner character positions. The foreground color is used for the border foreground color, and the background color is used for the background of the border and the remainder of the area. If the optional NO--BORDER keyword is entered, the entire area is cleared to the background color.


SCREEN DRAW BOX

Format:

     SCREEN DRAW BOX row  col  row  col  fg  bg

SCREEN DRAW BOX displays a double-line perimeter of a box on the screen. Existing screen information within the box is not cleared. The upper-left and lower-right corners define the area of the box. The foreground color is used for the border foreground, and the background color is used for the border background.


SCREEN EDITOR

Formats:

     SCREEN EDITOR row col row col fg bg title  FILE file buext
     SCREEN EDITOR row col row col fg bg title  VARIABLE var def
     SCREEN EDITOR row col row col fg bg title  FILE file buext MAX rows cols START row col OPTIONS f6str stat_row menu border mode
     SCREEN EDITOR row col row col fg bg title  VARIABLE var def MAX rows cols START row col OPTIONS f6str stat_row menu border mode

The SCREEN EDITOR command is used to create a multi-line input area that affects either a text file or variable. Optionally, you can alter characteristics such as scrolling, starting position, display information, and whether the window is used for user input or display only.

The title of the edit window can be any text expression. If a title is not required, use NULL or blank.

If the FILE option on the command line is used, you must specify the path and file name to edit followed by the backup file extension. The backup expression must be preceded with an equal sign (e.g., "=btx").

The target of the SCREEN EDITOR command can also be a project processing variable. In this case, you must specify the variable name and a default value. The length of the input field must be limited to 1000 characters. Note that end of lines are indicated by the tilde (~) character.

The FILE and VARIABLE command variations both have extended versions which allow for greater control over the editor's characteristics. The additional command line items are the same for both the FILE and VARIABLE versions. Note that if any editor characteristics are varied, then all of the options must be specified.

After the MAX key word you must specify the maximum number of rows and columns. This will determine the extent that the operator may scroll. If the extended command version is not used, the operator will not be able to scroll.

The values entered after the START key word determine the starting position of the cursor within the edit window.

Following the OPTIONS key word, you must specify the characteristics listed in the table below:

Item | Explanation
F6 string | Use a text expression which will be shown on the function key menu where the explanation for the F6 key is normally shown.
Status row | Specify the row number that the status line (i.e., file name, current row/col, etc.) will be printed on. To omit the status line display, enter a 0 value.
Fkeys | If any number other than 0 is used here, the function key list will be displayed on the bottom of the screen.
Border | If this option is set to 0, a border will not be displayed around the input window. If this option is set to a value other than 0, a border will be displayed. If options are not specified, the border will be turned on.
Mode | Enter rw_mode (10), ro_mode (11), ro_share (12), or rw_share (13) . When editing a file, this determines the mode in which the file is opened (see FOPEN for details on open file modes). When editing a variable, this determines whether the operator may change the text or only read it.

Note that if you use the ro_share mode to display a file, the operator will be warned that the file cannot be saved. To suppress this message, use ERROR OFF before invoking the editor (see the ERROR command for more information).


SCREEN INPUT

Format:

     SCREEN INPUT row  col  fg  bg  length  target <default-expression>

SCREEN INPUT commands produce an entry area and then pause the project until the project operator enters data. After the operator enters data and presses Enter, the data is stored in a target as text, and the project continues. The target can be a variable, Spreadsheet cell, or Database field.
NOTE: You cannot display a prompt with SCREEN INPUT as part of the command format. Use SCREEN PRINT to display an accompanying prompt.

The screen position of the input is indicated by row and column numbers. The entry area extends from the starting position to the right according to a specified length. The target specifies where the entered data will be stored.

A default entry may be entered for use if the operator presses Enter at the prompt. The default entry must be an expression that evaluates to text. If the default entry is longer than the specified length, it is truncated and placed in the target.


SCREEN INPUT MASK

Format:

     SCREEN INPUT row  col  fg  bg  length  target  MASK mask <default-expression>

You can restrict the format or content of operator input by adding the MASK keyword and a mask string to the SCREEN INPUT command. For example, you can specify a mask string that allows the operator to enter only letters, prohibiting further data entry if a character other than a letter is entered. The mask string must be a text expression that immediately follows the keyword MASK in the command format.

Following is a list of input mask characters:

A | Alphabetic Character
# | Numeric Character
N | Alphanumeric Character
X | Any Character
\n | Literal Character (replace n)
L | Force to Lower Case
U | Force to Upper Case
! | Used in List to Signify "Not"
[] | Specifies a list
- | Used in List to Create a Range
{} | Specifies an option
* | Designates a Repeat Count (i.e., *5A equals AAAAA)

A list is a bracketed ([ ]) group of allowable characters for a single designated input position. A range of characters can also be specified inside a list (i.e., [a-m]). For example, an entry of A[3-6] for the input mask means that the first character must be alphabetic and the second character must be any number from 3 through 6.

An option contains a group of input characters specifying that if any character in the option is filled, all characters must be filled. Options can be nested, as in the following example:

     {###{##}###}
     123 45 678

If input position 1, 2, 3, 6, 7, or 8 is filled, all other positions except 4 and 5 must also be filled. Positions 4 and 5 remain optional. If 4 or 5 is filled, all eight positions must be filled.

Consider the following example. An operator is asked to enter a four-character account code. The first character is a state code, C for California or K for Kansas. The remaining characters are the account number. Given this information, SCREEN INPUT MASK could be used to restrict the input with no additional checking required.

     SCREEN INPUT 10 30 14 1 4 $acct_code MASK "[CK]U###"

But if the number had to be in the 100s for California accounts and in the 200s for Kansas accounts, this mask would not be sufficient. Additional checking would be required:

     LOCAL $acct_code
     LABEL retry
     SCREEN PRINT 9 30 14 1 "Enter account number"
     SCREEN INPUT 10 30 14 1 4 $acct_code MASK "[CK]U###"

     IF NOT((LEFT($acct_code,2) = "C1") OR (LEFT($acct_code,2) = "K2"))
     ...JUMP retry
     END IF

If the operator is to proceed past the SCREEN INPUT command, $acct_code must receive four characters, and C or K must be the first character, followed by three numbers. SCREEN INPUT MASK ensures this. The IF structure uses the LEFT function to examine $acct_code. If the first two characters are C1 or K2 the project continues after END IF. If the first two characters are some other combination, the project jumps to the retry label and prompts the operator again.


SCREEN MENU

Format:

     SCREEN MENU row  col  row  col  fg  bg  hfg  hbg  default choices  target <title-expression>

SCREEN MENU creates a bar menu that looks just like a SmartWare module menu. The command generates a highlighter for selecting an item on the menu.

The location of the bar menu on the screen is specified by upper-left corner and lower-right corner coordinates. The menu area is cleared using the background color, and the menu choices and title are displayed in the foreground color. The current choice is highlighted using the highlighter foreground and background colors (hfg and hbg). The target may be a variable, Spreadsheet cell, or Database field.

The default is specified by a number that represents its position in the choice expression, the first position being 1. To emulate SmartWare module menus, you could use the same variable for the default and the target and initialize the variable to 1 on a command line before that containing the SCREEN MENU command. In this way, after the initial appearance of the menu with the first choice highlighted, subsequent displays of the menu will highlight the choice last made from the menu.

List menu choices after the default as an expression that evaluates to text. Include in the expression all possible choices, each separated by a space. The choices are placed on the menu in the order in which they are listed, from left to right. When the defined horizontal limit is reached, a new row of choices is started. This continues until the defined vertical limit is reached. The choices are displayed in proper format (first letter capitalized). Highlighter control keys are identical to those used on SmartWare module menus.
NOTE: Menus created with SCREEN MENU do not scroll. All choices are visible at all times. Therefore, the defined area must be large enough to accommodate all entries. If it is not large enough, an error occurs during project execution.

The target is a variable in which the position of the selected menu choice is placed.

The optional menu title must evaluate to a text expression and is displayed at the upper-left corner of the menu area. If menu choices wrap, they are indented to appear beneath the first choice and do not appear under the title.

When the SCREEN MENU command is executed, the menu appears with the highlighter positioned on the default choice. To make a selection, the operator highlights a choice and presses Enter, or just enters the first letter of the choice. If multiple choices have the same first letter, the one appearing earliest in the list is selected.

Instead of the choice itself, a number is placed in the target. The number corresponds to the position of the selection in the choice expression, the first position being 1.
NOTE: If the project operator presses Escape, the target variable is initialized with a value of 0.

To convert the numeric result to its text equivalent, use the GROUP function. The GROUP function must be supplied with a choice expression consisting of selections separated by spaces and a number. GROUP returns the choice corresponding to the specified number. For example, given the choice text expression "John Bill Joe Jim Mike" in the variable $choices, the function GROUP($choices,2) would return "Bill," the second item.

Consider the following example illustrating an operator creating letters by piecing together standard paragraphs. The project file prompts the operator with a menu of available paragraphs:

     LOCAL $choices $pgraph
     $choices = "Intro1 Intro2 Body1 Body2 Close1 Close2"
     SCREEN MENU 6 10 6 70 15 0 15 4 1 $choices $pgraph "Paragraphs"
     $pgraph = GROUP($choices,$pgraph)

For this example, $choices is initialized with a constant. SCREEN MENU uses $choices as the choice expression. After the operator selects a menu item and $pgraph is assigned numeric value, the GROUP function converts the numeric selection to its text equivalent.


SCREEN PRINT

Format:

     SCREEN PRINT row  col  fg  bg  expression

SCREEN PRINT prints information on the screen. The result of an expression you enter appears on the screen beginning at the specified position and in the foreground and background colors. Only expressions that evaluate to text can be printed. Numeric expressions are automatically converted to text before printing.
NOTE: Numeric expressions in the form -# will not print properly unless enclosed in parentheses (-#).


SCREEN PRINT FORMAT

Format:

     SCREEN PRINT row  col  fg  bg FORMAT format-expression expression

The FORMAT keyword and format-expression allow you to automatically format an expression. For example, you can specify a format-expression to automatically print a numeric variable with commas and a dollar sign without having to convert the variable to text and then format it before printing. Because only text expressions can be printed, numeric expressions that are entered are automatically converted to text before printing.

The format expression immediately follows the keyword FORMAT and must evaluate to a text expression. This expression consists of one or more codes that specify the data format. Use of each code is optional, depending on the data being formatted and the result you want to obtain. Those that are used must be placed in quotation marks the following order:

     <precision><alignment><width><options><data-type>
NOTE: The entire format expression must be a single sequence of text characters with no intervening spaces.

Precision. A precision code is a number from 0 to 15 that indicates a fixed number of decimal places for numeric data. If no precision code and no data-type are specified, numeric data is returned in the "general" format (decimal precision matches the precision of the numeric value).

Alignment. The alignment code specifies the alignment of the data within a specified width. You can use the following alignment codes.

Code | Meaning
L | Left alignment
R | Right alignment
M | Center (middle) alignment

Left alignment is the default alignment. Unless a width is specified, alignment codes have no effect.

Width. A width code is a number from 1 to 255 that specifies the length (number of characters) of the returned text expression. Space characters (or asterisks if the F option code is specified) are used to "pad" to the desired width that portion of the resulting text not occupied by the formatted data. If the data exceeds the specified width, a string of asterisks filling that width is returned. If no width is specified, FORMAT returns exactly the number of characters required to produce the desired format.

Options. Option codes provide special formatting capabilities. You can use the following option codes:

Code | Meaning
F | Fill with asterisks (*)
Z | Blank if 0
P | Parentheses around negative numbers
B | "cr" following negative numbers;"db" following positive numbers
C | "cr" following negative numbers

The F option code causes the text returned to be padded to the specified width with asterisks. This option is useful for check amount protection. The F code has no effect if a width is not specified or if the width is less than or equal to the number of characters occupied by the data in the specified format.

The Z code returns a single space character if the data item is a numeric 0.

The P, B, and C codes provide various options for the treatment of negative numbers. These codes are valid only if you also specify a precision code or an appropriate data-type (i.e., $, %, or E).

Data-type. A data-type code specifies one of several data formats available in SmartWare. You can use the following data-type codes:

Code | Meaning
, | Comma separated
$ | Currency
% | Percent
E | Exponential notation
H | Histogram
D1 | Date1 format
D2 | Date2 format
D3 | Date3 format
T1 | 12-hour time format
T2 | 24-hour time format

You may also create your own date format by specifying a data-type code consisting of the capital letter D followed by a custom date mask including one or a combination of the following characters:
NOTE: These codes must be lowercase.

Code | Meaning
d | Numeric day (omits leading 0 on single digit)
dd | Numeric day (includes leading 0)
day | Text day name
m | Numeric month (omits leading 0 on single digit)
mm | Numeric month (includes leading 0)
mon | Text month (3-character abbreviation)
month | Text month name
yy | Numeric year (2-digit)
yyyy | Numeric year (4-digit)

You can include other characters, such as hyphens (-) and slashes (/), within a custom date mask. Such characters are placed literally in the text expression returned, producing the familiar punctuation in date formats. If you want to include a term that serves as a code (e.g., the word "Month"), or the numbers 1, 2, or 3, as literal characters in a custom date mask, you must precede them with the backslash (\) character.
NOTE: If you inadvertently enter more than one data-type code, Format uses the last one in the format expression.

Consider the following examples illustrating two ways to center messages on the screen. Without format capabilities, you have to calculate the print positions of both messages and enter them into the SCREEN PRINT command:

     SCREEN CLEAR 0 0
     SCREEN PRINT 5 26 14 0 "Sorting Procedure In Progress"
     SCREEN PRINT 6 33 14 0 "Please Stand By"
     MESSAGE "Press Enter"

With a format expression, calculation of start positions is not necessary:

     SCREEN CLEAR 0 0
     SCREEN PRINT 5 1 14 0 FORMAT "M80" "Sorting Procedure In Progress"
     SCREEN PRINT 6 1 14 0 FORMAT "M80" "Please Stand By"
     MESSAGE "Press Enter"

Using "M80" as the format expression, the project centers the message within an 80-character field starting at column 1.

Though numbers are not stored with thousands separators or monetary symbols, you can display numbers with these symbols using format expressions. In the following example, the format expression specification prints $1,532,543 on the screen:

     LOCAL #number
     #number = 1532543
     SCREEN CLEAR 0 0
     SCREEN PRINT 1 1 12 1 FORMAT "M20$," #number
     MESSAGE "Press Enter"


SCREEN PROMPT

Format:

     SCREEN PROMPT row  col  row  col  fg  bg  choices  target <title-expression>

SCREEN PROMPT generates the same style prompter that SmartWare uses and displays a pointer for selecting an item on the prompter. The prompter is placed on the screen according to the specified upper-left corner and lower-right corner coordinates. The defined area is cleared using the background color. The prompter choices, title, pointer, and border are displayed in the foreground color. The target can be a variable, Spreadsheet cell, or Database field.
NOTE: SCREEN PROMPT always displays a border around the defined area. Therefore, you must define an area containing a minimum of three lines to accommodate the top and bottom of the border and at least one row of choices.

List prompter choices after the color numbers as an expression that evaluates to text. Possible choices included in the expression are each separated by a space and are placed on the prompter in the order they are listed, from left to right. When the defined horizontal limit is reached, a new row of choices is started. This continues until the defined vertical limit is reached. The choices are displayed exactly as entered (not necessarily in proper format, as in SCREEN MENU). Initially, only choices that fit in the defined area are displayed. Choices that are specified but cannot fit in the defined area can be viewed by scrolling the prompter. Pointer control and scrolling keys are identical to those used on SmartWare file prompters.

The optional prompter title is displayed at the upper-left corner of the prompter area, overwriting part of the border.

When the SCREEN PROMPT command is executed, the prompter appears with a pointer positioned at the first choice. The operator points to a choice and presses Enter to make a selection. Instead of the choice, a number is placed in the target. The number corresponds to the position of the selection in the choice expression, the first position being 1. As in SmartWare, the prompter is cleared immediately after a selection is made. Refer to the example under SCREEN MENU for more information.
NOTE: If the project operator presses Escape, the target variable is initialized with a value of 0.

SCREEN MENU


SCREEN RESTORE

Format:

     SCREEN RESTORE row  col source-variable

SCREEN RESTORE restores a portion of a previously saved screen to the current screen at a specified position. The variable must have been used in a previous SCREEN SAVE command. The row and column parameters specify the position of the upper left corner of the portion to be restored.

If the restored portion exceeds the length or width of the screen at the specified position, all information falling below the bottom line of the screen is lost. Any of the remaining restored portion cut off at the right edge of the screen wraps to the left side of the screen.
NOTE: You can quickly restore a previously saved screen portion using the SCREEN SHORTRESTORE command, which restores the screen to the area from which it was saved. You do not have to specify screen coordinates.


SCREEN SAVE

Format:

     SCREEN SAVE row  col  row  col  variable

SCREEN SAVE allows a portion of the screen to be saved and redisplayed later at the same or a different location using the SCREEN RESTORE command. The rectangular area to be saved is defined by an upper-left position and a lower-right position. The specified area is saved into the variable.

SCREEN SAVE has no visible effect. The saved area is not cleared after the command is executed. In order to clear and reuse the saved area, use SCREEN CLEAR BOX and SCREEN PRINT.

SCREEN CLEAR
SCREEN PRINT


SCREEN SCROLL

The SCREEN SCROLL commands scroll a designated area of the screen down, left, right, or up.

Two pairs of row and column numbers define the upper-left and lower-right corners of the area to be scrolled. The amount of scroll is determined by the last number in the command format. Scrolling up or down is measured in rows, while scrolling left or right is measured in columns.

When an area of the screen is scrolled, everything in that area moves in the direction specified. Screen data scrolled beyond the limits of the area is erased. This data cannot be redisplayed by scrolling in the opposite direction.

The blank area created by the scrolling action is painted with the background color specified in the SCREEN SCROLL command.
NOTE: Entering a value of 0 for the amount to scroll erases the entire scroll area.


SCREEN SCROLL DOWN

Format:

     SCREEN SCROLL DOWN row  col  row  col  fg  bg  #rows

SCREEN SCROLL DOWN scrolls a designated area of the screen down a specified number of rows.


SCREEN SCROLL LEFT

Format:

     SCREEN SCROLL LEFT row  col  row  col  fg  bg  #columns

SCREEN SCROLL LEFT scrolls a designated area of the screen left a specified number of columns.


SCREEN SCROLL RIGHT

Format:

     SCREEN SCROLL RIGHT row  col  row  col  fg  bg  #columns

SCREEN SCROLL RIGHT scrolls a designated area of the screen right a specified number of columns.


SCREEN SCROLL UP

Format:

     SCREEN SCROLL UP  row  col  row  col  fg  bg  #rows

SCREEN SCROLL UP scrolls a designated area of the screen up a specified number of rows.

Consider the following example using SCREEN SCROLL to print a string and scroll it around the screen:

     LOCAL ctr, scroll_msg

     scroll_msg = "Scroll Item"
     SCREEN CLEAR BOX 1 1 25 40 7 1 NO--BORDER

     FOR ctr = 11 TO 1 STEP -1
     SCREEN PRINT  25 1 15 1 CHR(scroll_msg[ctr])
     SCREEN SCROLL RIGHT 1 1 25 40 7 1 1
     WAIT .07
     END FOR

     FOR ctr = 1 TO 24
     SCREEN SCROLL UP 1 1 25 40 7 1 1
     WAIT .03
     END FOR

     FOR ctr = 1 TO 28
     SCREEN SCROLL RIGHT 1 1 25 40 7 1 1
     WAIT .03
     END FOR

     FOR ctr = 1 TO 24
     SCREEN SCROLL DOWN 1 1 25 40 7 1 1
     WAIT .03
     END FOR

     FOR ctr = 1 TO 28+13
     SCREEN SCROLL LEFT 1 1 25 40 7 1 1
     WAIT .03
     END FOR

     MESSAGE "That's All"

This example prints a message on the screen at the lower-left corner of a box created with SCREEN CLEAR BOX. Then the message is scrolled up to the upper-left corner, right to the upper-right corner, down to the lower-right corner, and left off of the left border.


SCREEN SHORTINPUT

Formats:

     SCREEN SHORTINPUT target <prompt>

SCREEN SHORTINPUT pauses a project until the operator enters information and presses Enter. You can specify an optional prompting message that appears on the first line in the Control Area, where most SmartWare prompts appear. The entry is stored in a variable, Spreadsheet cell, or Database field. SCREEN SHORTINPUT offers no control over the position, prompt colors, or accuracy of the entry.
NOTE: If the project operator presses Enter, the target is initialized with a NULL value.

Example:

     SCREEN SHORTINPUT $password "Enter the password"

Although SCREEN SHORTINPUT is limited, it does provide an easy method of obtaining data. You can use SCREEN PRINT commands to display instructions and SCREEN SHORTINPUT to provide a consistent location for operator input:

     LOCAL $password $date
     SCREEN CLEAR 0 0
     SCREEN CLEAR BOX 6 30 9 50 11 4
     SCREEN PRINT 7 31 14 4 FORMAT "M19" "Enter Password"
     SCREEN SHORTINPUT $password
     SCREEN CLEAR BOX 6 30 9 50 11 4
     SCREEN PRINT 7 31 14 4 FORMAT "M19" "Enter Date"
     SCREEN SHORTINPUT $date


SCREEN SHORTMENU

Format:

     SCREEN SHORTMENU default choices  target <title-expression>

SCREEN SHORTMENU creates a bar menu in the Control Area of the screen in standard SmartWare colors and generates a highlighter for item selection. The menu is positioned just like a SmartWare module menu. The menu background is black with white choices. The highlighted choice is white on a blue background. The default choice is specified by a number that represents its position in the choice expression, the first position being 1.

This is equivalent to the SCREEN MENU command, except that the position and colors are not variable but are instead those used on standard SmartWare menus. Refer to the SCREEN MENU command for details on the operation of this command.


SCREEN SHORTRESTORE

Format:

     SCREEN SHORTRESTORE variable

SCREEN SHORTRESTORE restores a portion of a previously saved screen to the area from which it was saved. The variable must have been used in a previous SCREEN SAVE command.

In the following example, an operator must choose a selection from a menu. During processing, the menu is cleared and the status screen is displayed. When the process is complete, the menu is restored.

     LOCAL $menu_scn $process
     SCREEN CLEAR 0 0 NO--BORDER
     SCREEN CLEAR BOX 5 20 10 60 14 4 NO--BORDER

     SCREEN PRINT 5 35 11 4 "Menu Title"
     SCREEN PRINT 7 34 11 4 "a) Process a"
     SCREEN PRINT 8 34 11 4 "b) Process b"
     SCREEN PRINT 10 34 11 4 "Select"

     SCREEN SAVE 5 20 10 60 $menu_scn
     SCREEN INPUT 10 41 11 4 1 $process Mask "[a-b]"
     SCREEN CLEAR 0 0 NO--BORDER

     IF $process = "a"
     ...SCREEN PRINT 6 23 14 0 "Process a complete - press [Enter]"
     ...MESSAGE
     ELSE
     ...SCREEN PRINT 6 23 14 0 "Process b complete - press [Enter]"
     ...MESSAGE
     ENDIF

     SCREEN SHORTRESTORE $menu_scn
     MESSAGE "Press any key to exit"

The first six SCREEN commands display the menu. Then the menu is saved into the screen buffer by SCREEN SAVE. Next, an input prompt is displayed. The SCREEN INPUT command uses a mask to restrict operator input to a or b. A message concerning the selected process is displayed. The MESSAGE command is used to pause the project and wait for a keystroke. Finally, the original menu is redisplayed using SCREEN SHORTRESTORE.


SINGLE-STEP

Type: Command
Scope: All
Formats:

     SINGLE-STEP ON
     SINGLE-STEP OFF

The SINGLE-STEP command controls the display of a prompt before each command during project execution. The prompt gives you the option of executing the command or proceeding to the next command, which can be valuable in debugging your projects.
NOTE: Only project commands are displayed; statements, such as FOR, WHILE, or IF, are not displayed.

Like the QUIET OFF command, SINGLE-STEP displays the current command on the Status Line along with its line number. The prompt Execute the following command (y/n) is also displayed. The operator must then choose whether to execute the displayed command by pressing y or n.

If you want to be prompted only when certain sections are executing, you can place multiple SINGLE-STEP commands throughout the project file.

SINGLE-STEP ON causes all of the following command lines to be displayed and the prompt to appear. SINGLE-STEP OFF disables the display of command lines and prompting.
NOTE: SINGLE-STEP commands are not be affected by QUIET ON or QUIET OFF.

The success of SINGLE-STEP ON is contingent upon how the project file is compiled. For SINGLE-STEP ON to display the command lines and prompt, the text versions of command lines must be available in the runtime version of the project. As long as the DEBUG OFF project command is not used in your project file, the runtime version will contain text versions of every command if:
*** The project file is compiled by pressing F10 after loading it into the Project Editor.
** The project file is compiled with the Remember Tools Compile Debug command.

A default SINGLE-STEP setting may be specified with the Tools Preferences Global command. This setting controls all project files unless SINGLE-STEP commands are embedded within the project file.
NOTE: A SINGLE-STEP setting, whether set in Global Preferences or with the SINGLE-STEP command, affects all project files. If you execute a project file that contains a SINGLE-STEP ON command and then execute a second project file without a SINGLE-STEP command, command lines and the prompt will be displayed during execution of the second project file. SINGLE-STEP ON cannot be stopped by removing the command and recompiling; you must include a SINGLE-STEP OFF command.

DEBUG
QUIET


SMARTPEEK

SMARTPOKE

Type: Commands
Scope: All
Formats:

     SMARTPEEK option variable
     SMARTPOKE option expression

The SMARTPEEK and SMARTPOKE commands are used to examine and change the status of SmartWare system settings. These commands allow a project to determine such things as whether Autohelp or automatic file backup is enabled; the name of the currently selected printer or plotter driver; or the current date or time format.

SMARTPEEK returns information about the status of the system setting. SMARTPOKE actually changes the status of the system setting. Both commands use option parameters to specify which system settings to examine or change. While all options can be examined, not all can be changed. For example, you cannot change the current module by using SMARTPOKE to change the value of $_modl.
IMPORTANT: It is important that you know which options can be used with SMARTPOKE before using them. If you attempt to change an option that cannot be changed, a runtime error will occur.

NOTE: Some SMARTPEEK and SMARTPOKE constants work differently under the Unix operating system. If a program uses any constants that are specific to an operating system, it will still compile but the values returned will be meaningless.

The following table lists alphabetically the option names that can be used with these commands. Included in the table is a one-letter code indicating the type of information being referenced and a brief description of the system setting being controlled. All option names start with $_. The one-letter codes are defined as follows:

N | Numeric information.
B | Boolean information, i.e., numeric, where zero = false and non-zero = true. When using SMARTPOKE with Boolean information, always use 1 for true.
T | Text information.
W | Option can be changed or written using SMARTPOKE.
D | DOS option
U | Unix option

Options | Descriptions
$_auto B,D,U | Autohelp on (1) or off (0). Change using the AUTOHELP command.
$_beep B,D,U | Beep on (1) or off (0). Change using the BEEP command.
$_bkfp N,W,D,U | Backup and file prompting. Bits indicate whether automatic file backup and file prompting are on:
 | BITAND(value, 0x8000) will be true (1) if file backup is on.
 | BITAND(value, 0x4000) will be true (1) if file prompting is on.
 | To change one of the options, SMARTPEEK the old value, modify the correct bit, and use SMARTPOKE to change the current setting.
$_cbmodl B,D,U | Combined module used (1) or not used (0).
$_cct T,D,U | Returns the name of the currently selected character comparison table.If the American/UK is being used, default.cct will be returned
$_clbg N,W,D,U | Colors, background (used on the command line). This affects the FGBACKGROUND and BGBACKGROUND functions.
$_cldp N,W,D,U | Colors (dim pleasing) used for unavailable options in paper profile.
$_cled N,W,D,U | Colors, editing (used in the text editor). This affects the FGEDITING and BGEDITING functions.
$_cler N,W,D,U | Colors, error (used for error messages). This affects the FGERROR and BGERROR functions.
$_clhp N,W,D,U | Colors (highlighted pleasing) used for available options in paper profile.
$_clip N,W,D,U | Colors (inverse pleasing) used for selected options. This affects the FGINVPLEASING and BGINVPLEASING functions.
$_clis N,W,D,U | Colors (inverse standard) used for selected keywords. This affects the FGINVSTANDARD and BGINVSTANDARD functions.
$_clpl N,W,D,U | Colors (pleasing) used in options editing. This affects the FGPLEASING and BGPLEASING functions.
$_clst N,W,D,U | Colors (standard) used in menus, prompt editing. This affects the FGSTANDARD and BGSTANDARD functions.
 | The color options control most of the system and default colors. Foreground and background colors are stored together, as follows:
 | Foreground = MOD(value, 16); Background = INT(value / 16)
 | To change a color, use the format SMARTPOKE $_clxx (bg * 16) + fg, where xx represents the two-character code of the color setting you want to change.
$_co B,D,U | Ctrl-O on or off. On allows the project to be suspended and exit to the operating system. You can change this by using the OSEXIT command.
$_cpl N,D,U | Characters per line for current printer. Based on paper profile setting on the Tools Preferences Hardware menu.
$_cpos N,D,U | Current cursor position, obtained as follows:
 | column = MOD(value, 256); line = INT(value/256)
 | NOTE: You will have to experiment to determine whether this option is suitable for your particular needs.
$_cpu N,D,U | CPU information. The first 5 bits (0-4) describe the DOS CPU type or Unix machine. Bit 5 is unused. If bit 6 is set, word alignment is significant. If bit 7 is set, byte order is low/high.
 | Bits 0-4 CPU/Unix
 | 00000 ----- 286
 | 00001 ----- 386
 | 00010 ----- 486
 | 00011 ----- Pentium
 | 00100 ----- Reserved
 | 00101 ----- Reserved
 | 00110 ----- Reserved
 | 00111 ----- Reserved
 | 01000 ----- SCO
 | 01001 ----- Hewlett Packard
 | 01010 ----- Sparc
 | 01011 ----- Data General
 | 01100 ----- Motorola
 | 01101 ----- Altos
 | 01110 ----- MX300
 | For example: On a DOS 486 (byte order is high/low and word alignment is not significant) the value is 00000010 while on a Hewlett Packard (byte order is low/high and word alignment is significant) the value is 11001001.
$_ctyp N,D,U | Current cursor type, displayed as follows:
 | 0 - No cursor, 1 - Underline, 2 - Small block, 3 - Large block
$_cz B,D,U | Ctrl-Z on or off. On allows a project to be interrupted. Change this using the CZBREAK command.
$_d1 T,W,D,U | Date1 format string.
$_d2 T,W,D,U | Date2 format string.
$_d3 T,W,D,U | Date3 format string.
 | Date formats are set using the Tools Preferences Global module command. Formats can be a maximum length of 20 characters.
$_dead N,W,D,U | File header deadsize. SmartWare documents, spreadsheets, and database files provide for a user-defined area in the file header. This area follows the first 32 bytes of the file and is normally set to zero length. Setting this option to a value other than zero reserves space in new files that can be overwritten by the user without affecting the file's contents. Whether a file has a dead space can be tested by examining bytes 6 and 7 of the file (starting at zero); the contents of these bytes is the deadsize, beginning with the low byte first (offset 6). The maximum number the deadsize can be is 64.
$_decp N,W,D,U | Decimal separator. This option determines which character to use as the decimal point in decimal numbers. To change this option, set to {X}, where X is the character you choose.
$_dfmt N,W,D,U | Date format. Date styles are set using the Tools Preferences Global module command. The following formats are available:
 | 1 = mmddyy 2 = ddmmyy 3 = yymmdd
$_divz B,W,D,U | Division by zero. This option controls whether division by zero is an error (1) or a result of zero (0). Change this setting using the Tools Preferences Global command.
$_dlma N,W,D,U | Delay, maximum lock time.
$_dlmi N,W,D,U | Delay, minimum lock time. See the retry lock times below under $_r?lk.
$_ds N,D | Data segment. Obtains the 80x8x data segment (DS) register value used by SmartWare.
$_encr B,W,D,U | Alternate encryption driver. Controls whether an alternate (1) or standard (0) encryption driver is used.
$_enter B,D,U | Enter mode. Determines whether the current module is in Enter Mode (1) or Command Mode (0).
$_eof B,W,D,U | EOF on text files. Controls whether an ASCII EOF (Ctrl-Z) is written on the end of text files. (1 = true; 0 = false).
$_errmes T,W,D,U | Text of last error message as it was displayed. Note that some errors contain formatting codes (e.g., %d, %s) that are replaced with text. ERRORTEXT displays these internal codes, while $_errmes displays the replacement text.
$_error B,D,U | Error on (1) or off (0). Controls whether error messages are displayed during project execution. Change this using the ERROR command.
$_filedlg B,W,D,U | switches between the SmartWare File Prompter and the Windows Open File dialog box. When set to 1, any location that uses the File Prompter will use Open File instead. This has no influence under any operating system but Windows. The following lines of code toggle between these modes.
$_gdv T,D | Graphics screen driver name. An empty string indicates that no driver is loaded.
$_graphopt N,W,D,U | Controls a variety of graphics output and conversion options.
 | Bit 0 (the "TRUEGRAY" flag) controls conversion from colors to gray scales.
 | 0 optimizes the differences among colors to avoid mapping to the same shade of gray.
 | 1 maps colors to their true gray value equivalents.
 | Bits 3, 2, 1 (the "ditherstyle" field) are explained as follows.

Ditherstyle | Bit Values
0 ordered dither (smoothest edges; poor reproduction) | 0 0 0
1 halftone dither (good for photocopying) | 0 0 1
2 linear dither (decorative) | 0 1 0
3 circular dither (decorative) | 0 1 1
4 reserved, not used | 1 0 0
5 reserved, not used | 1 0 1
6 reserved, not used | 1 1 0
7 granite texture (decorative) | 1 1 1

 | Bit 4 (the "PAGE EXPAND" flag).
 | 0 fits graphs in a box with a 4x3 aspect ratio when printing from the spreadsheet.
 | 1 uses the full printable page if the aspect ratio matches that of the page. (The aspect ratio of the graph is maintained in any case. Since SmartWare-generated graphs currently use a 4x3 aspect ratio, this flag is only of use when printing metafiles from sources other than SmartWare.
 | Bit 5 (the METAFILE COLOR STORAGE flag).
 | 0 uses indexed colors. SmartWare's 16 colors are specified by an index into this color table.
 | 1 uses the direct RGB colors. Every time a color is specified it is specified as a triplet of red, green, and blue values. Direct color results in a larger output file, but allows more than 16 colors per output file.
 | Bit 6 (the SCREEN BACKGROUND flag). This flag specifies the background color before a graph is drawn. A graph can have its own background, which gets painted on top of this background, but if the graph does not fill the screen, or does not have a background color, this is the color that will "show through".
 | 0 sets a white background
 | 1 sets a black background (the default).
 | Bit 7 (the TEXT EDGE ATTRIBUTE flag).
 | 0 sets this flag to plain. No edges drawn around the outline of the character.
 | 1 sets this flag to outline. An outline will be drawn around text which can be helpful when color text is output to a black and white device. The interior of the character is filled in regardless of the edge attribute.
 | Bit 8 (the TEXT FILL ATTRIBUTE flag).
 | 0 sets this flag to Fill. Text characters are filled. Whether or the text is outlined is controlled by the setting of bit 7.
 | 1 sets this flag to Outline Only. Only the outline of text characters is drawn. The characters are not filled. Setting this bit to 1 overrides the setting of bit 7.
 | Bit 9 (Plotter Polygon Fill Disable flag).
 | 0 sets this flag to Fill. The interior fill of all solid-fill-patterned polygons will be filled when sent to a plotter
 | 1 sets this flag to No Fill. The interior fill of all solid-fill-patterned polygons is turned off on output to plotters. This can speed up plotting, and is also useful for plotters which can accept cutting styli in place of plotter pens.
 | This bit has no effect on devices other than plotters.
$_graphszx N,W,D,U | See the $_graphszy option.
$_graphszy N,W,D,U | This option combined with $_graphzx allow graphs to be created in shapes other than the standard aspect ratio of 4 by 3. The values for these options are in units of 1/20th of a point. If you specify 12 point text in a graph, the text will be 12x20 = 240 units high in any metafiles produced by ANGOSS. The default values for the width and height are 15264 and 11448, respectively, corresponding to a "page" of 10.6 by 7.95 inches. Values should be kept between 1000 and 32000 or you may produce unpredictable results. ANGOSS displays and prints graphs as large as they will fit on the output device without distorting their shape. Doubling or halving both the width and the height at the same time will not change the size of the graph on screen, just the text size relative to graph size.
$_gvseg N,D | Virtual segment for graphics screen video RAM.
$_help B,D,U | Help on or off. Controls whether on-line help (F1) is enabled (1) or disabled (0). Change this using the F1HELP command.
$_hidx N,W,D,U | Help index number. The help index number is the internal number used to determine which help topic will be displayed when F1 is pressed. Incorrect values could produce a Help Corrupted message. Use this option with caution.
$_hbc N,W,D,U | Help bold format. This and the following help options control the display format for various portions of on-line help. The help format includes both color and font information. The color can be obtained by masking the lower byte of the help format, as follows:
 | SMARTPEEK $_hbc helpvar
 | color = bitand(helpvar, 0xFF)
 | Color formats are the same as described under the system colors ($_clxx) options.
 | The following fields in the upper byte of the help format control the font for the corresponding help text:
 | SMARTPEEK $_hbc helpvar
 | bitand(helpvar, 0x8000). This is always set and requires color to be used for fonts if a graphics text screen is not used.
 | bitand(helpvar, 0x4000). If set, the text is to be underscored.
 | bitand(helpvar, 0x2000). If set, the text is to be boldfaced.
 | bitand(helpvar, 0x1000). Unused.
 | bitand(helpvar, 0x0F00). This masks a 4-bit font number. The font is equivalent to the original 16 SmartWare fonts (0 = normal, 1 = italics, etc.)
 | To set a new font format, specify the color as described under the system color option ($_clxx) and add 0x8000. Add 0x4000 for underscore or 0x2000 for boldfacing. To use a different font, add the font number (0 - 15) * 256. SMARTPOKE the resulting format.
 | Other format options include the following:
$_hhc N,W,D,U | Help header format.
$_hic N,W,D,U | Help italics format.
$_hpc N,W,D,U | Help prompt format.
$_htc N,W,D,U | Help text format.
$_hwnd N,D,U | Returns the window handle of the main SmartWare window.
$_ins B,W,D,U | Insert mode on (1) or off (0). Changes made to the insert mode using this option may not be properly displayed on the Status Line.
$_irev T,D,U | Internal revision number.
$_iswince N,D,U | Returns 1 if the current operating system is Windows CE (PocketPC), otherwise is 0.
$_key N,W,D,U | Next key to be used. Returns the next key used, i.e., it will look as if that key were typed in. No macro lookup or other checks, such as Ctrl-Z to abort checking, will be done. Use this option with caution; indiscriminate poking may interfere with the operation of SmartWare Quick Keys or KEYS statements.
$_kflt N,W,D,U | Keyboard filter bits. This is a 32-bit value that controls whether the lower 32 ASCII key values are translated to their respective SmartWare key values. The most significant bit (0x80000000) is ASCII value 0; the least significant bit (1) is ASCII value 31. Bits are set if translation is to be done, as is normal. For example, clearing bit 0x40000000 will prevent Ctrl-A from being translated, effectively removing Ctrl-A from use in the SmartWare system. The true ASCII value of Ctrl-A will be sent in when the key is pressed. Use this option with extreme caution.
$_l1 N,D,U | Line 1 (menu/prompts). Screen line numbers for the lowest four lines of the screen: menu area, Status Line, and Autohelp Line.
$_l2 N,D,U | Line 2 (menu, command line).
$_l3 N,D,U | Line 3 (Status Line).
$_l4 N,D,U | Line 4 (Autohelp).
$_lastkey N,W,D,U | Last key used by SmartWare for any action, except when NEXTKEY has been executed.
$_lpp N,D,U | Lines per page for current printer. Lines per page is based on the paper profile setting on the Tools Preferences Hardware menu.
$_modl N,D,U | Module number of current module:
 | 0 - Main menu
 | 1 - Spreadsheet
 | 2 - Wordprocessor
 | 3 - Database
 | 4 - Communications
$_net B,D | Networking. Determines whether the network driver is in use (1) or not (0). This is always true in Unix.
$_newevents B,W,D | Determines whether new events fire. New events include MouseMovedNoButton, AppActivate, AppDeactivate, WinFocus, and WinLostFocus.
$_nodos B,W,D,U | No operating system access. Setting this option to 1 (true) disables access to DOS.
$_noexp B,D | No expanded memory in use. If this option returns true (non-zero), expanded memory is not in use.
$_norslt B,W,D,U | No result key Ctrl-C. If this option is set to 1 (true), Ctrl-C will not invoke the RESULT macro (the last calculation from the calculator, text editor, Word Processor, etc.).
$_onerror T,D,U | Current ON-ERROR FUNCTION name. This option will return a null string (" ") if no error is in effect.
 | NOTE: When you are using $_onerror, you can use the ON-ERROR FUNCTION " " command as an alternative to ON-ERROR OFF. ON-ERROR FUNCTION " " allows you to preserve the current on-error status. You can also restore the previous on-error status by using ON-ERROR FUNCTION with the result. Refer to the discussion of ON-ERROR in the Project Processing Manual for an example.

$_os N,D,U | Operating system ID.
 | 1 = DOS 16 bit mode (286 or higher)
 | 2 = DOS 32 bit mode (386 or higher)
 | 3 = UNIX character terminals
 | 4 = UNIX graphical (X11)
 | 5 = Windows
$_paint B,D,U | Repaint on or off. Controls whether repainting is on (1) or off (0). Change this setting using the REPAINT command.
$_pdis B,D,U | Port disabled. If this option is true (non-zero), an error, such as a timeout, has disabled the current port being used for printing or plotting. See also $_prdis.
$_pdv T,D,U | Printer driver name. Returns the name of the currently selected printer.
$_pfcp N,W,D,U | Default project file compiler mode. Controls whether projects are compiled by default with DEBUG OFF (0) or DEBUG ON (1).
$_pfec N,D,U | Project file compiler error character offset.
$_pfel N,D,U | Project file compiler error line number. If an error occurs when a project file is compiled, these options contain the line and column number showing where the error occurred.
$_pfex B,W,D,U | Project file default execution type. This controls whether the default type of project files (Entry, Menu Keywords, etc.) are run in-memory (1) or from-file (0).
$_pfim B,D,U | Project file in-memory. This option is set to 1 (true) if the current project file is loaded in-memory and 0 (false) if it is run from-file. If you run a project in-memory, this option can be used to test whether insufficient memory caused the system to switch to running from-file.
$_pflc N,W,D,U | Project file last cursor column. This value is returned by the SCRLINE and SCRCOLUMN functions.
$_pfll N,W,D,U | Project file last cursor line. This value is returned by the SCRLINE and SCRCOLUMN functions.
$_pfst N,D,U | Project file status. The three project file status bits are as follows:
 | BITAND(value, 1) = Breakpoint set.
 | BITAND(value, 2) = ON-ERROR in use.
 | BITAND(value, 4) = REPLY in use.
$_pldv T,D,U | Plotter driver name. Returns the currently selected plotter.
$_plport N,W,D,U | Plotter port number. If changed to a serial port, the plotter port parameters defined on the Tools Preferences Hardware menu are used. Port numbers are as follows:
 | For DOS:
 | 1, 2, 3 = LPT1, 2, 3
 | 4, 5 = COM1, 2
 | 6 = PRN
 | 7 = AUX
 | 8 = NETWORK
 | 9 = FILE
 | For Unix:
 | 1 = SPOOLER
 | 2 = DIRECT
 | 3 = CUSTOM
 | 4 = FILE
$_plto N,W,D,U | Plotter timeout value. Returns the time (in 1/100 seconds) before a plotter timeout occurs.
$_popn B,D,U | Printer open in project file. Determines whether the printer has been opened in a project file using the OPEN--PRINTER command (0 = no, 1 = yes using OPEN--PRINTER, 2 = yes using OPEN--PRINTER RAW).
$_prdis B,D,U | Printer disabled. If this option returns true (non-zero), an error has disabled the printer driver. Test both this and $_pdis to see if information being printed is currently being discarded. This option can also be set by a user aborting a print job (by pressing Esc).
$_prport N,W,D,U | Printer port number. If changed to a serial port, the printer port parameters defined on the Tools Preferences Hardware menu are used. Port numbers are as follows:
 | For DOS:
 | 1, 2, 3 = LPT1, 2, 3
 | 4, 5 = COM1, 2
 | 6 = PRN
 | 7 = AUX
 | 8 = NETWORK
 | 9 = FILE
 | For Unix:
 | 1 = SPOOLER
 | 2 = DIRECT
 | 3 = CUSTOM
 | 4 = FILE
$_pto N,W,D,U | Printer timeout value. Returns the time (in 1/100 seconds) before a printer timeout occurs.
$_ques N,D,U | Last question number. This option contains the number of the last question asked. This information can be used in conjunction with the REPLY command.
$_quiet B,D,U | Quiet mode on (1) or off (0). Change this using the QUIET command.
$_rem B,D,U | Remembering. Determines whether a project file is being remembered (yes = 1; no = 0).
$_rev T,D,U | SmartWare revision. Returns the version of SmartWare being used.
$_rflk N,W,D,U | Retry file lock time limit.
$_rrlk N,W,D,U | Retry record lock time limit.
$_rtlk N,W,D,U | Retry transaction lock time limit. Primarily used in the Database, the retry values control how long SmartWare tries to place a lock on a record, file, or transaction before timing out. These values are in 1/100 seconds (100 = 1 second). Related to these are the $_dlmi and $_dlma values, which control how often within the retry period to attempt to lock. $_dlmi is the minimum time, and $_dlma is the maximum time. A random time between the minimum and maximum is picked each cycle to prevent deadlock conditions. In all cases, the retry times must be fairly long to prevent failures from premature timeouts in heavy network traffic. Also, the minimum must be less than the maximum, and both delays must be less than the retry times. Delays should not be too short, or an overload of the network could result. These options should be used with caution and only when you think the default values are not right for your network.
$_sdv T,D,U | Screen driver name. In DOS, this returns the currently selected text screen name. In Unix, this returns the terminal type (TERM).
$_seed N,W,D,U | Random number seed. This is the current seed value used to generate the next random number in the SmartWare random functions. If you wish to synchronize the random number generator to a known point, set this option to a non-zero positive number between 1 and 2,147,483,646 (2^31 - 2). Setting the number outside this range will destroy the randomness of further numbers generated by the random number functions.
$_s1cmd B,W,D,U | Suspend one command mode. In a project, if set to 1, One Command Mode will be in effect when the project is suspended. This option always reverts to 0 at the start of the first project. See $_1cmd for more information.
$_sn T,D,U | SmartWare serial number. Returns the serial number of the SmartWare package being used.
$_step B,D,U | Single-step mode on (1) or off (0). Change this using the SINGLE-STEP command.
$_spnded B,D,U | Suspend status. (1 = suspended; 0 = not suspended)
$_spndmes B,W,D,U | Suspended message visible flag. (1 = visible; 0= not visible)
$_tfmt N,W,D,U | Time format. The time format (12/24 hr) is selected using the Tools Preferences Global command:
 | 1 - AM/PM
 | 2 - 24 Hour
$_thou N,W,D,U | Thousands separator (comma). Determines the character to use as the thousands separator in numbers. To change, set to {X}, where X is the character.
$_trace B,D,U | Trace on (1) or off (0). Determines whether breakpoints are enabled or disabled. Change this using the TRACE command.
$_tvseg N,D | Virtual segment for text screen video RAM.
$_unixerr N,U | Unix error number. This returns the error number generated by a Unix project processing command.
$_1cmd B,W,D,U | One Command Mode. If set to 1, all applications will revert to Enter Mode after one command is executed from the command line. This does not affect Project Processing.
$_$ T,W,D,U | Currency ($) symbol string. Determines the text character(s) to use to represent the currency symbol (usually $). Can be up to five characters long.
$_$pos B,W,D,U | Currency ($) symbol position. Determines where the currency symbol appears. Returns 1 (true) if the symbol is before the number and false (0) if it is after.


SOUND

Type: Command
Scope: All
OS: Different
Format:

     SOUND frequency <duration>. . .

The SOUND command causes audible tones of variable frequency and length to be produced.

In DOS, various frequencies can be produced by entering a number or an expression that evaluates to a number between 0 and 20000. However, the human ear generally can detect sound only in the range of 19-15000. The duration is an optional number or expression that evaluates to the number of seconds the sound will be produced. Sound durations from approximately .001 to 10 seconds can be produced. If no duration is specified, 1/10th of a second is the default.

In Unix, the SOUND function will simply produce a beep. The parameters will have no affect.

Multiple pairs of frequency and duration numbers can be used in a single SOUND command. Each number must be separated by a space. For example, SOUND 45 1 123 .5 98 2 212 would produce four sounds. The last sound would be audible for the default duration of .1 second since a duration is not specified.
NOTE: This command will produce a sound regardless of whether BEEP is on or off.

Unlike the BEEP command, SOUND can produce a variety of different tones for varying lengths of time. With this capability, project files can be enhanced in several ways.
*** Instead of using long messages, distinctive sounds may be used to trigger operator response. For example, every time the operator must enter a filename, the same sound could be produced. The operator may be able to react more quickly to the sound than to a printed message.
** The SOUND command can be used to signal the completion of a lengthy process, such as printing several reports or sorting a large number of records.
** Groups of tones can be programmed to accent instructional projects or presentations. Sound cannot be generated simultaneously while other processing is occurring, but with special care to timing, tones can appear to accompany other processes.


SOUNDBLOCK

Type: Command
Scope: All
OS: Different
Format:

     SOUNDBLOCK buffer-variable

SOUNDBLOCK takes a buffer variable in which successive pairs of words (two-byte integers) represent sound frequencies and durations and plays it through the computer speaker.

SOUNDBLOCK is a specialized variant of the SOUND command and is designed to allow playing long sequences of sound without experiencing the "clicks" associated with the speaker being turned on and off. Before using this command, you must define the entire set of sounds in a buffer variable using the PACK command. Each sound is represented by a pair of words (two-byte integers). The first word is the frequency in hertz, and the second is the duration in number of milli-seconds (1/1000 seconds). The sequence of word pairs must be terminated by a word with value 65,535 (0xFFFF).

NOTE: In Unix, the SOUNDBLOCK function will simply produce a beep. The parameters will have no affect.

NOTE: The duration is not a fractional number. One-tenth second is 100, not .1.

Because each word can hold a value of 0 to 65,535, the frequency limits are 0 - 65,534 hertz (65,535 is the terminator), and the duration limits are 0 - 65.535 seconds. If the 0xFFFF terminator word is left off, the SOUNDBLOCK command will play random frequencies and durations until it encounters 0xFFFF. Ctrl-Z may be used to abort a SOUNDBLOCK sequence; however, a check for Ctrl-Z occurs only between successive notes, so there could be up to a 65-second delay before the sequence is aborted.

Example. The following program illustrates one method for packing the sounds into a variable, using randomly generated frequencies and durations.

LOCAL song | 'Buffer variable.
LOCAL freq | 'Frequency
LOCAL duration | 'Duration
LOCAL count | 'Number of sounds to generate
LOCAL x | 'Counter
LOCAL buffloc | 'Place in the variable to pack next
count = 20 | 'Produce 20 sounds
buffloc = 1 | 'Start packing at variable offset 1

     COMMENT  Each frequency/duration pair takes\
     4 bytes (2 per word). Terminator\
     takes the extra 2 bytes.

BUFFER song SIZE ((count * 4) + 2) | 'Allocate buffer
FOR x = 1 TO count |
freq = rand * 5000 | 'Random frequency, '0 - 5000 hertz
duration = (rand * 450) + 50 | 'Random duration, '.05 - .5 secs

     COMMENT   Pack two words at the current location\
     in the variable. Buffloc, in this\
     instance, is an offset into the buffer,\
     not an array offset.

PACK song[buffloc] "WW" freq duration buffloc = buffloc + 4 | 'Move to next pair
END FOR |
PACK song[buffloc] "W" 0xFFFF | 'Put on terminator
SOUNDBLOCK song | 'Play the "song"

You can also use the SOUNDBLOCK command to build up a library of sounds or music. Because the sound sequence is stored in a BUFFER form variable, it can be written to and read from a disk file using the FWRITE and FREAD BINARY commands.

FREAD
FWRITE


STATUSBAR

Type: Command
Scope: All
OS: Graphical
Formats:

     STATUSBAR INIT fg bg border_color
     STATUSBAR FINISHED
     STATUSBAR MESSAGE text

The STATUSBAR INIT command creates a status bar window at the bottom of the application window. Text is drawn on the status bar through the STATUSBAR MESSAGE command.

Usually, a status bar is initialized at the start of an application and messages are written to it multiple times. Finishing the status bar would then only be required when a user turns it off. If that happens, writing to the status bar is simply ignored.

PULLDOWN
TOOLBAR


STOP

Type: Command
Scope: All
Format:

     STOP

The STOP command stops execution of all project files. If the current project file was called from another project file with the EXECUTE command, execution does not resume in the original project file. Control immediately returns to the current module.

Project files that were previously loaded with the Remember Load command will stop executing when the STOP command is executed but are not otherwise affected. They must be unloaded with the Remember Unload command.

EXECUTE


SUSPEND

Type: Command
Scope: All
Formats:

     SUSPEND
     SUSPEND COMMAND
     SUSPEND ENTER

The SUSPEND command causes project file execution to pause and return program control to the project operator. This allows interactive execution of module commands, or input of keys from the keyboard. Pressing F8 resumes file execution.

SUSPEND, used by itself, accesses the Command Mode or Enter Mode of a module, depending on the mode that was current when the project file was executed. The keywords COMMAND or ENTER allow you to dictate which mode the module will be in when the SUSPEND command is executed.

SUSPEND is helpful if you need to perform an interactive task that cannot be done within a project file. However, if you wish to limit a project operator's access to SmartWare, it is best to use SUSPEND in combination with a KEYS statement or with the SUSPENDONE command. This prevents an operator from performing actions other than those intended during project execution. For more information, refer to the discussions of the SUSPENDONE command and the KEYS statement in Project Processing Manual.
NOTE: If you use the KEYS statement in combination with the SUSPEND command, be sure to include F8 as the last term in the key list. Without F8, the project file will remain suspended when the key list is complete.

KEYS


SUSPENDONE

Type: Command
Scope: All
Formats:

     SUSPENDONE
     SUSPENDONE COMMAND
     SUSPENDONE ENTER

The SUSPENDONE command causes project file execution to pause and return program control to the project operator for the execution of a single module command. When the command is complete, project file execution is resumed automatically. SUSPENDONE, like the SUSPEND command, can be beneficial but must be used carefully.

SUSPENDONE, used by itself, accesses the Command Mode or Enter Mode of a module, depending on the mode that was current when the project file was executed. The keywords COMMAND or ENTER dictate which mode the module will be in when the SUSPENDONE command is executed.

Although SUSPENDONE allows only one module command to be executed, that one command could be enough to cause problems when the project file resumes execution. Additional control over operator input can be achieved by using SUSPENDONE with the KEYS command. For more information, see the discussion on the KEYS command in the Project Procesing Manual.

KEYS


TOOLBAR

Type: Command
Scope: All
OS: Graphical
Formats:

     TOOLBAR INIT mnu_handle usermode language
     TOOLBAR FINISHED BLANK
     TOOLBAR FINISHED DESTROY

The TOOLBAR INIT command creates a toolbar in conjunction with a menu - refer to the section on Menu Functions. The command requires a menu handle (the menu must be bound to a bitmap library), a usermode, and a language.

The FINISHED BLANK and FINISHED DESTROY commands both close the toolbar but BLANK leaves the toolbar space while DESTROY completely removes it.

GRAPHICS BMPLIB
PULLDOWN
STATUSBAR


TRACE

Type: Command
Scope: All
Formats:

     TRACE
     TRACE ON
     TRACE OFF

The TRACE command provides a means of calling the Remember Tools Trace utility from within a project and enabling or disabling breakpoints from within a project.

Using TRACE with no following keyword invokes the Remember Tools Trace utility to allow you to examine variables and set or clear breakpoints. Within a project, you must use this command instead of Remember Tools Trace or a runtime error will occur.

TRACE OFF is used within a project to temporarily ignore any breakpoints that may have been set up. Once this command is executed, the project file will not stop on any breakpoints until TRACE ON is executed. TRACE can still be used to directly invoke the Trace utility.

When a project is first executed from a SmartWare menu, breakpoint checking is automatically enabled.


TRANSFER

Type: Command
Scope: All
Formats:

     TRANSFER "project"
     TRANSFER "project" IN--MEMORY
     TRANSFER "project" FROM--FILE

When the TRANSFER command is executed, the current project is abandoned, and a new project file is executed. Unlike the EXECUTE command, control does not return to the current project after the new project is finished.

The name of the new project file to which control will be transferred follows the keyword TRANSFER and may include path information.
NOTE: When the first project file is abandoned, any public or external variables or arrays that are referenced in the second project file will not be deallocated. In some cases, the need to keep both project files open to make these public variables available can require a great deal of memory. If memory shortage is a problem in your system, you may not be able to transfer to some project files.

In a complex project file, parts of other project files may be called or executed. In these situations, it is important to understand the flow of control during a transfer. It may be helpful to remember that a transfer is always made from the file in which the last MAIN statement was executed before the transfer.

For example, assume a project file calls a function in a second project file. This function in the second project file contains a TRANSFER command. When the transfer is made to a new (third) project file, the original project file will be abandoned.

However, now suppose the first project file uses the EXECUTE command to execute the second project file containing the TRANSFER command. The transfer is made to the new (third) project. Once the third project file has completed execution, control returns to the original project file. In this example, it is the second project file, rather than the first, that is abandoned by the TRANSFER command.

By adding the keywords IN--MEMORY and FROM--FILE, you have the option of executing the new file in memory or from disk. If you do not include this option, the file will be executed from disk by default. When executed FROM--FILE, portions of the file are loaded into memory when needed. If you use the IN--MEMORY option, the entire project is loaded into memory before it is executed. While this option can provide faster execution, no function in the project file can be greater than 64K, and enough memory must be available to load the entire project file.

EXECUTE


UNIX

Type: Command
Scope: All
OS: Unix Only

This series of Unix project processing commands allows programmers to utilize the Unix IPC (inter process communications) messaging system. You may also create child processes. Among other things, these features allow you to integrate your own C code into Unix ANGOSS applications and allows you to create applications where users can send messages to each other.

The UNIX CHILD command uses the fork() execvp() functions to run the specified command. Both ANGOSS process and the new process will run simultaneously. The UNIX SIGNAL command allows you to send various signals to a specified process. This can be used in conjunction with the UNIX CHILD command.

The UNIX ID command provides information, such as process id, group id, user id, etc., about the currently running process.

The UNIX MSG-OPEN, MSG-SEND, MSG-RECEIVE, MSG-REMOVE, MSG-STATUS and MSG-CONTROL commands allow programmers to access the powerful IPC provided by the UNIX operating system.


UNIX CHILD

Format:

     UNIX CHILD "command" CHILD-PID variable "arguments" ...

The UNIX CHILD command performs a fork() and execvp().

This allows you to run a Unix command in the background. Use the UNIX MSG or UNIX SIGNAL commands to "talk" to the new process.

The command parameter is the filename of the command to run. It may contain the full path if necessary.

The variable parameter must be a project processing variable in which the child process id will be stored.

This variable is used to pass the id to other UNIX commands (i.e. UNIX SIGNAL) that require a process identification.

At the end of the UNIX CHILD command, list any arguments that should be passed to the command as separate text strings.

Example:

local #id
unix child "lp" child-pid #id "bigfile" "-ob"

The above example sends the file "bigfile" to the printer with the no banner flag ("-ob") in the background.


UNIX SIGNAL

Format:

     UNIX SIGNAL process-id named-constant

The UNIX SIGNAL command sends a signal to another process. The first parameter is the process id and the second parameter is a named constant indicating the signal to send.

The process id is typically determined by the UNIX CHILD command. The following named constants are available to indicate which signal to send:

SIGHUP - Hangup signal
SIGINT - Interrupt signal
SIGKILL - Kill signal
SIGTERM - Software termination signal
SIGUSR1 - User-defined signal 1
SIGUSR2 - User-defined signal 2

The UNIX SIGNAL command will call the C function kill(S). The error code, if any, can be retrieved by using the SMARTPOKE $_unixerr. Refer to the Unix Programmers Reference Manual for your version of Unix for more details.

Example:

UNIX SIGNAL #child_id SIGKILL


UNIX ID

Format:

     UNIX ID named-constant variable

The UNIX ID command allows you to find information about the current process and user.

The variable parameter must be a project processing variable in which the results of the command will be stored.

The following named constants are available:

UNIX_PID - Process ID number.
UNIX_PPID - Parent process ID number.
UNIX_PGRP - Process group ID number.
UNIX_UID - User ID number.
UNIX_EUID - Effective user ID number.
UNIX_GID - Group ID number.
UNIX_EGID - Effective group ID number.
UNIX_UNAME - User login name.

The following table shows the C functions which relate to available named constants. Refer to the Unix Programmers Reference Manual for your version of Unix for more details.

UNIX_PID - getpid(S)
UNIX_PPID - getppid(S)
UNIX_PGRP - getpgrp(S)
UNIX_UID - getuid(S)
UNIX_EUID - geteuid(S)
UNIX_GID - getgid(S)
UNIX_EGID - getegid(S)
UNIX_UNAME - getlogin(S)

Example:

UNIX ID UNIX_PID #pid message "The current process ID is "|str(#pid)


UNIX MSG-OPEN

Format:

     UNIX MSG-OPEN EXISTING key ID id-variable
     UNIX MSG-OPEN EXISTING key ID id-variable PERMISSIONS perm
     UNIX MSG-OPEN NEW key ID id-variable
     UNIX MSG-OPEN NEW key ID id-variable PERMISSIONS perm
     UNIX MSG-OPEN OLD-OR-NEW key ID id-variable
     UNIX MSG-OPEN OLD-OR-NEW key ID id-variable PERMISSIONS perm
     UNIX MSG-OPEN UNIQUE-KEY key-variable ID id-variable
     UNIX MSG-OPEN UNIQUE-KEY key-variable ID id-variable PERMISSIONS perm
     UNIX MSG-OPEN PRIVATE ID id-variable

The UNIX MSG-OPEN command creates a message queue which can then be used to send or receive messages to another process. For more information on IPC messages refer to the C functions msgget(S), msgop(S) and msgctl(S).

One use possible use is to pass information to your own C programs. You can do this by opening the message queue(s) and then forking a process (UNIX CHILD) passing the queue ID(s) to the new process as arguments.

The UNIX MSG commands can also be used to pass information between users.

The following named constants are accepted as permission indicators. If permissions are not specified, all permissions are assumed.

MPERM_RU - Allow reading by user.
MPERM_WU - Allow writing by user.
MPERM_RG - Allow reading by group.
MPERM_WG - Allow writing by group.
MPERM_RO - Allow reading by others.
MPERM_WO - Allow writing by others.
MPERM_ALL - Allow reading and writing by all (default).

The message queue identifier will be placed into the id-variable which must be a project processing variable. This variable must be used to identify a message queue in the UNIX MSG-SEND, UNIX MSG-RECEIVE and UNIX MSG-REMOVE commands.

The key parameter is an IPC key which specifies the entity being accessed.

The SMARTPEEK $_unixerr command can be used to check the error status after executing of any of the MSG commands. Note that you should clear the variable with SMARTPOKE before running the command if you are going to check the error status.

UNIX MSG-OPEN EXISTING

The EXISTING option is used when you want to open a message to an IPC message entity that has already been set up. The existing IPC entity is specified by the key parameter. The message queue ID is placed into the id-variable parameter.

UNIX MSG-OPEN NEW

The NEW option is used when you want to establish a new IPC message entity. If the message entity already exists, the command fails. The message queue ID is placed into the id-variable parameter.

UNIX MSG-OPEN OLD-OR-NEW

The OLD-OR-NEW option is used when you want to establish a new IPC entity. If the message entity already exists, the command proceeds normally. The message queue ID is placed into the id-variable parameter.

UNIX MSG-OPEN UNIQUE-KEY

The UNIQUE-KEY is used when want to establish a new IPC entity. ANGOSS will ensure that the key created is unique. The newly created IPC entity ID will be placed into the key-variable parameter. The message queue ID is placed into the id-variable parameter.

UNIX MSG-PRIVATE

The MSG-PRIVATE command is used to create a unique IPC identity that no other processes can access without knowing the message queue identifier. This is placed into the id-variable.


UNIX MSG-SEND

Format:

     UNIX MSG-SEND id FROM variable LENGTH bytes TYPE type WAIT
     UNIX MSG-SEND id FROM variable LENGTH bytes TYPE type NO-WAIT

The UNIX MSG-SEND command is used to place messages in an IPC message queue.

The id parameter must contain the message queue identifier, typically obtained by UNIX MSG command.

The variable parameter must be a project processing variable which contains the message to send.

The bytes parameter must indicate the length of the message in bytes.

The type parameter must be a positive integer which can affect the way a message is received (see the UNIX MSG-RECEIVE command below).

If the WAIT option is used, the current process will be suspended until the message can be sent. This occurs if certain system maximums are exceeded. Otherwise, if NO-WAIT is used, the message would not be sent. Note that the maximums can be adjusted by kernel tuning.

The SMARTPEEK $_unixerr command can be used to check the error status after executing of any of the MSG commands. Note that you should clear the variable with SMARTPOKE before running the command if you are going to check the error status.

This command calls the C function msgsnd(S).


UNIX MSG-RECEIVE

Format:

     UNIX MSG-RECEIVE id INTO variable TYPE type WAIT <type-variable>
     UNIX MSG-RECEIVE id INTO variable TYPE type NO-WAIT <type-var>

The UNIX MSG-RECEIVE command is used to read a message from the IPC message queue.

The id parameter is the message queue identifier which is typically obtained by the UNIX MSG-OPEN command.

The variable parameter must contain a project processing variable into which the message will be placed. The type-variable parameter must also be a project processing variable. If used, the message type will be placed into it. It is an optional parameter.

The type parameter determines which message will be received. If the type is 0 then the first message is received. If the type is larger than 0, then the first message of that type is received. If type is less than 0, the first message of the lowest type that is less than or equal to the absolute value of the type is received.

As with the other UNIX MSG commands, the $_unixerr SMARTPEEK variable will be set if an error occurs.

This command calls the C function msgrcv(S).


UNIX MSG-REMOVE

Format:

     UNIX MSG-REMOVE id

The id parameter must be the message queue identifier that you want to close. As with the other UNIX MSG commands, the $_unixerr SMARTPEEK variable will be set if an error occurs.

This command calls the C function msgctl(S) with the IPC_RMID cmd parameter.

Note that this command can only be executed if you have the appropriate permissions.


UNIX MSG-STATUS

Format:

     UNIX MSG-STATUS id INTO array

The UNIX MSG-STATUS command will read all obtainable information into a project processing array.

The id parameter must be the message queue identifier that you want to check. The array parameter must be a single dimension project processing array with the size of 12 or more. The element specified will contain the first returned value.

The following name constants can be used as offsets to the starting position:

0 MSTAT_CUID - Creator user PID.
1 MSTAT_CGID - Creator group PID.
2 MSTAT_UID - User PID for access permissions.
3 MSTAT_GID - Group PID for access permissions.
4 MSTAT_PERM - Permission flags.
5 MSTAT_QNUM - Number of messages on queue.
6 MSTAT_QBYTES - Max number of bytes allowed on queue.
7 MSTAT_LSPID - PID of last process to do a SEND operation.
8 MSTAT_LRPID - PID of last process to do a RECEIVE operation.
9 MSTAT_STIME - Time of last SEND.
10 MSTAT_RTIME - Time of last RECEIVE.
11 MSTAT_CTIME - Time of last CHANGE.

This command uses the Unix C function msgctl(S) with the cmd parameter of IPC_STAT. As with the other UNIX MSG commands, the $_unixerr SMARTPEEK variable will be set if an error occurs.


UNIX MSG-CONTROL

Format:

     UNIX MSG-CONTROL id uid gid mode qbytes

The UNIX MSG-CONTROL command allows you to change the permissions of an existing IPC message queue.

The id parameter is the message queue identifier. The uid parameter and the gid parameter are the user id and group id respectively.

The mode parameter is the lower nine bits of the access mode. The qbytes parameter sets the maximum number of bytes of all messages in the queue.

This command uses the Unix C function msgctl(S) with the cmd parameter of IPC_SET. As with the other UNIX MSG commands, the $_unixerr SMARTPEEK variable will be set if an error occurs.

Note that this command can only be executed if you have the appropriate permissions.


UNLOAD

See LOAD/UNLOAD.

LOAD and UNLOAD


UNLOCK

See LOCK/UNLOCK.

LOCK and UNLOCK


UNPACK

See PACK/UNPACK.

PACK and UNPACK


VIRSEG

Type: Command
Scope: All
OS: DOS Only
Formats:

     VIRSEG INTO var FROM real-segment <LENGTH length> <NO--REMOVE>

     VIRSEG REMOVE virtual segment

     VIRSEG CODE variable FROM segment
     VIRSEG CODE variable FROM segment NO--REMOVE

VIRSEG INTO maps a real segment value to a virtual segment that is valid in protected mode and then places the virtual segment into the variable. If a virtual segment can't be created, this command returns a zero (0) and issues an error.

The optional length is the maximum number of bytes in the segment that can be addressed. By default, the value is the entire offset range, or 65536 bytes. A length that is 0 or greater than 65536 will result in an error.

By default, the previous virtual segment mapping is removed when another VIRSEG command is executed, i.e., a VIRSEG CODE command also removes a previous VIRSEG INTO, and vice versa. You can prevent a previous virtual segment mapping from being removed by using the NO--REMOVE option with this command. When NO--REMOVE is used, you must remember to remove the old mappings using the VIRSEG REMOVE command.

The VIRSEG REMOVE command removes the mapping between the specified virtual segment and its real segment. This invalidates the segment. If no virtual segment is given, the last segment mapped with VIRSEG is removed.

A run-time error message will be produced under UNIX.

Example:

     GLOBAL videoseg, biosseg
     LOCAL equipment
     VIRSEG INTO videoseg FROM 0xB800
     'Get virtual segment to address screen memory

     VIRSEG INTO biosseg FROM 0X40 NO--REMOVE
     'Get virtual segment to address BIOS RAM area,
     'but don't remove video mapping

     .
     .
     .

     NATIVE PEEK biosseg 0x11 "C" equipment
     'Get number of diskette drives (bits 6+> in character)

     MESSAGE "Number of diskette drives is" & STR(INT(equipment/0x40) + 1)

     NATIVE POKE videoseg 0 "C" 65     'Put "ABC" into video memory
     NATIVE POKE videoseg 2 "C" 66
     NATIVE POKE videoseg 4 "C" 67

     .
     .
     .

     VIRSEG REMOVE       'Remove last mapping (the biosseg mapping)
     VIRSEG REMOVE videoseg     'Remove videoseg mapping
IMPORTANT: Removal of a segment not mapped with VIRSEG could remove a segment in use by SmartWare, causing the program to fail.

Memory that contains code must be designated as executable. This can be accomplished with the VIRSEG CODE command. VIRSEG CODE takes a virtual data memory segment and places another segment number that is valid for code execution into a variable. This must then be combined with the address offset for calling. The previous segment mapping is removed unless the NO--REMOVE keyword is used.

Example:

     LOCAL data_adr, code_adr, code_seg

     MEMALLOC data_adr SIZE number-of-bytes
     'Allocate memory
     MEMPACK  data_adr template-expression
     'Pack code to be executed.
     VIRSEG   code_seg FROM SEGMENTOF(data_adr)
     'Combine executable segment and data offset.
     code_adr = POINTEROF(code_seg, offsetof(data_adr))
     FARCALL  code_adr
     'Call the executable address.


VOICE COMMAND

Type: Command
Scope: All
OS: DOS Only
Format:

     VOICE COMMAND command

VOICE COMMAND sends the specified string to the voice recognition software where it is interpreted as a DCOM command.

All DCOM commands, except DCOMs that only work at the DOS prompt can be sent.

Note that if there is a more specific project processing command, such as VOICE STATE CALL, that meets your needs, it is preferable to use it. This will make your applications more portable to future versions and provides compile time syntax checking.

For details on the DCOM command syntax, refer to the DragonDictate User's Guide.


VOICE STATE

Type: Command
Scope: All
OS: DOS Only
Formats:

     VOICE STATE CALL NEW state
     VOICE STATE CALL EXISTING state
     VOICE STATE SWITCH NEW state
     VOICE STATE SWITCH EXISTING state
     VOICE STATE RETURN
     VOICE STATE DELETE state
     VOICE STATE ON-EXIT keystrokes
     VOICE STATE ON-ENTRANCE keystrokes

The VOICE STATE series of commands provides the ability to create, call, delete and modify state vocabularies. A state vocabulary is a series of verbal commands and related keystroke and punctuation information. For details on state vocabularies, refer to the ANGOSS Voice Suite manual or the DragonDictate User's Guide.

The state parameter must be a text string indicating the state name to call. Upper and lower case letters are significant. The dcom command parameter is also a text string.

VOICE STATE CALL initiates a new state. The current state is preserved on a stack and is restored when the VOICE STATE RETURN command is issued. This makes it easy to modularize programs. The VOICE STATE SWITCH command switches the current state without affecting the stack.

If the EXISTING option is used with the VOICE STATE CALL or VOICE STATE SWITCH, the state must exist or an error will occur. The NEW option will create a new state if one does not exist. No error is generated if the state already exists.

The VOICE STATE DELETE command will remove a state from the current user's vocabulary files.

The VOICE STATE ON-EXIT and VOICE STATE ON-ENTRANCE commands allow you to specify keystrokes to execute when a state is started or terminated. Note that, when you return to a state using the VOICE STATE RETURN command, the initiating keystrokes are run again.

Dcom commands may be embedded by surrounding them with {dcom} strings. For example "{dcom}console{dcom}s" starts the voice console and issues a save. For details on DCOM command syntax, refer to the DragonDictate User's Guide.


VOICE ADD-WORD

Type: Command
Scope: All
OS: DOS Only
Formats:

     VOICE ADD-WORD CURRENT-STATE NO-TRAIN desc keys punct
     VOICE ADD-WORD CURRENT-STATE TRAIN desc keys punct
     VOICE ADD-WORD GLOBAL NO-TRAIN desc keys punct
     VOICE ADD-WORD GLOBAL TRAIN desc keys punct
     VOICE ADD-WORD DICTATION NO-TRAIN desc punct
     VOICE ADD-WORD DICTATION TRAIN desc punct

The VOICE ADD-WORD commands add new macros and dictation words to the currently loaded vocabulary files.

If the CURRENT-STATE option is used, the new macro is added to the current state vocabulary. The current state vocabulary can be changed with the VOICE STATE CALL or VOICE STATE SWITCH commands. If the GLOBAL option is used, the new macro will always be available.

The VOICE ADD-WORD DICTATION command creates a new dictation word. The <keys> parameter is not required because the description is used.

The TRAIN option will invoke the DragonDictate training program for macros whose pronunciation cannot be derived. If the pronunciation can be derived or the NO-TRAIN option is used, training will not occur.

The pronunciation is derived based on words within the description. Brackets are ignored. Spaces, hyphens and underscores are interpreted as word separators. If all of the words within the description have a known pronunciation, the sounds of each word are concatenated to build an acoustic signature for the new macro. This approach only provides a rough estimate of the pronunciation as the sounds of continuous speech are different than that of individual words. If, however, derived macros are used in conjunction with limited vocabulary, 100% accuracy can often be achieved. When limited vocabulary is off, derived words will still often be interpreted correctly and will certainly come up much sooner in the choice list.

Note that the phrase building capability is only used in the project processing form of ADD-WORD. The DCOM ADD-WORD command will not derive pronunciation. Also note that the phrase building capability is only available in DragonDictate version 3.0 and up.

The description parameter generally reflects the pronunciation of the macro. Usually, non dictation words are surrounded by brackets.

The keys parameter determine what keystrokes are produced when the macro is spoken. If you want to use non text keystrokes such as page down, etc., surround the keystroke name with braces. For example, {enter}. Note that the keystroke names are different than the names used by the rest of SmartWare. Refer to the DragonDictate User's Guide for a complete list of key names.

The punctuation parameter effects the spacing and capitalization of the macro. It must be a text string with one or more of the following characters.

Char/Function | Description
c capitalize next word | Capitalizes the first letter of the next word you say. DragonDictate includes this attribute in characters that end sentences such as . (period) and ? (question mark)
l clings left | Removes the space between the current word and the last word you said. DragonDictate includes this attribute in characters such as ) (close parentheses) and . (period).
r clings right | Removes the space between the current word and the next word you say. DragonDictate includes this attribute in punctuation marks such as " (open quote).
s string | Removes spaces between consecutive words. If you dictate to consecutive words to which you have assigned the string attribute. This attribute is generally used for alpha-bravo words and numbers.
i invisible | Tells DragonDictate to pass punctuation associated with the last word said to the next word you say. Generally, this is used for command macros and should only be used when you are sure that you don't want it to be effected by the punctuation of the previously spoken word or commands.
d default | Replaces punctuation for the current word with the default punctuation. DragonDictate assigns punctuation to a word based on its keystrokes.


VOICE-TRAIN

Type: Command
Scope: All
OS: DOS Only
Format:

     VOICE-TRAIN s

The VOICE TRAIN command calls the DragonDictate training command. The user will be asked to repeat the specified word the number of times indicated by the DragonDictate defaults.


WAIT

Type: Command
Scope: All
Formats:

     WAIT
     WAIT duration
     WAIT duration text

The WAIT command is used to pause project file execution for a specified amount of time. You can optionally display a message during the pause.

There are three formats for using the WAIT command. Used by itself, WAIT pauses for one second. WAIT followed by a numeric expression representing duration pauses the specified number of seconds. The duration should be .05 second or greater. Because of internal timing constraints, anything less than .05 second has the same effect as waiting zero seconds.

The duration may be followed by an expression that displays in the Control Area during the pause. This expression generally includes text, but if a numeric expression is included, it is automatically converted to text.

You may abort the wait and resume execution immediately by pressing any key. The key is used only to abort the wait and is not processed further.


WHILE

Type: Statement
Scope: All
Format:

     WHILE logical expression
     commands
     END <WHILE>

The WHILE statement creates a loop in which at least one command is executed while a condition is true.

Use a WHILE loop when you do not know in advance how many times to execute a series of commands but do know that execution should stop when a certain condition is met.

When the WHILE statement is executed, the logical expression is evaluated. If the expression is true (any value except zero), the commands following the WHILE statement are executed. The loop may contain any number of commands. When the END WHILE statement is encountered, the logical expression is reevaluated. If the expression is still true, the commands are executed again.

The commands within the WHILE loop continue to be executed until the logical expression evaluates to false (0). When the logical expression is false, project file execution continues with the command following the END WHILE statement.

Two additional commands are available for use with the WHILE loop, CONTINUE WHILE and EXIT WHILE. CONTINUE WHILE abandons the current iteration of the loop and returns to the WHILE statement, where the logical expression is reevaluated. EXIT WHILE causes the program to abandon the WHILE loop, regardless of the result of the logical expression, and continue execution with the command following the END WHILE statement.

The WHILE loop is terminated by the END WHILE statement. Including WHILE after END is optional; however, adding it makes it clear that it is the WHILE statement that is complete, since END is also used in other statements in the SmartWare Programming Language.

For more information about WHILE loops, refer to the Project Processing Manual.

CONTINUE
EXIT


WINHELP

Type: Command
Scope: All (Windows)
Formats:
     WINHELP CONTENTS
     WINHELP CONTEXT number
     WINHELP FILE string
     WINHELP FORCE
     WINHELP HELP
     WINHELP INDEX
     WINHELP POPUP number
     WINHELP QUIT
     WINHELP SEARCH string
     WINHELP SET CONTENTS number
     WINHELP SET INDEX number
     WINHELP TOPIC string

The WINHELP series of commands provides access to the Windows help program. The SPL interface closely follows the C interface to WinHelp (refer to the MSW 3.1 and WIN32S API help files for information). Note that instructions on creating a Windows help file is beyond the scope of this manual. It requires an editor that outputs Rich Text Format (RTF) and a help compiler (comes with most Windows SoftWare Development Kits).

In SPL, you announce the existance of "help" by first executing:

     WINHELP FILE "filename"

This file name can be changed at any time. The help system itself is started by executing one of the following commands:

     WINHELP CONTENTS

Displays the table of contents for the help file

     WINHELP HELP

Displays help-on-help

     WINHELP INDEX

Shows the index for the help file

     WINHELP CONTEXT #context_number

Shows the help associated with the "context number" supplied. these numbers are built into both the help file and the application.

     WINHELP POPUP #context_number

Similar to the above, except help appears as a popup item.

     WINHELP TOPIC "topic string"

Shows help on the given topic (exact match).

     WINHELP SEARCH "search string"

Searches for the topic - the select window appears if the string is ambiguous. In particular: winhelp search "" allows the user to search for a topic in the help file.

When you are finished with the Windows Help system, the quit command will close the help window if it has not already been closed.

     WINHELP QUIT


Appointment Manager

Each time you access Help in the Appointment Manager, this file is displayed. Scroll through the file to find the information you need. Error messages are addressed first, immediately following this paragraph. The remainder of this file discusses how to create and use files and directories and each Appointment Manager command.


Error Messages

Unable to write to file. File has been changed.
Another user has opened the file. Wait and retry again.

No meeting or task is marked to edit.
You must have a meeting or task marked before choosing edit.

Unable to edit a private meeting or task.
Must load the file with private access.

Initialization failed - unable to execute Appointment Manager.
The project files necessary to run the Appointment Manager were not found in the SmartWare directory, or there is insufficient memory to run the Appointment Manager.

No meeting or task is marked to use as a template.
You must mark a meeting or task before attempting to use a template.

The period specified is greater than the maximum allowed.
Enter a shorter period.

File does not have a valid Appointment Manager format. Reached EOF prematurely.
File not found or invalid filename entered.

Unable to load.
Someone else may be using this file. Wait and retry again.

Verification failed.
The password just entered does not match the initial password entered.

Password incorrect.
The password entered is not the password for this file.

Wrong password entered. - only general access allowed.
The maximum number of unsuccessful password entries has been reached.

No meeting or task is marked to remove.
You must mark a meeting or task before attempting to remove one.

Filename is invalid. Filename = "(none)". Enter a filename.
An error occurred while writing the file.

Fopen error - someone else may have file.
Someone else may be using the file.

Item not found.
The specified item was not found.

Unable to use a private meeting or task as a template.
Select a non-private meeting or task for a template.


Files and Directories

The first step in creating a file is to insert an appointment on the calendar. After scheduling at least one appointment, you can save the file. When you execute File Save, you are prompted to name the file. Enter a name of no more than eight characters.

You do not need to include an extension in the filename. The Appointment Manager automatically assigns an .stm extension. Only files with .stm extensions are listed in the prompter list when you load a file. Therefore, if you create a file with an extension other than .stm, you must type in the full name when you want to load it. You can use the Tools File Rename command to modify the filename to include an .stm extension.
NOTE: If you have used SmartWare 3.10, your appointment files might have a .dtm extension. The updated Appointment Manager reads these files and lists them in the prompter list.

If you do not include a path when you name and save the file, it is stored in the current directory. The current directory usually is determined by the Tools Preferences Appointment-Manager command. With this command you can set a default directory that becomes the current directory whenever you enter the Appointment Manager. If you have changed the directory using Tools Directory New-Directory, the file is stored in the new directory.


Command Reference

Appointment Manager commands are explained below in the same order as they are presented on the top menu.


Display

Display switches to the Week Screen or Month Screen associated with the current day. Display Week switches to the Week Screen that contains the current day. Display Month switches to the Month Screen that contains the current day.


Insert

The Insert command is used to place new meetings and tasks on the calendar. It is available only in the Day Screen and has three options: Meeting, Task, and Similar.


Insert Meeting

Insert Meeting places a new meeting on the calendar. When it is selected, you are prompted for the meeting's frequency and the period of time over which it is to be scheduled. If an inserted meeting conflicts with an existing one, a warning is displayed prior to insertion. (This message is optional; you can turn it off using the Tools Preferences Appointment-Manager command.)

Once you specify a time period, a definition screen is displayed listing appointment-specific settings. The settings address the date of the first occurrence, starting and ending time, private or general access (password option), and an optional short and long description.

Enter the date in whichever format you have specified in the Global Preferences menu. Starting time is also entered, displayed, and printed in the format selected on the Global Preferences menu. (This menu gives you access to global SmartWare parameters.) The system time, which is rounded upward to the nearest half hour, is entered as a default, but it can be replaced with any time. The optional duration display can be shown as hours:minutes or as ending time. You can opt not to display a duration time.

The access parameter specifies whether the file is to be password-protected. If you choose to make the file a general access file, it can be loaded by anyone, but any private information is replaced by asterisks. However, if you attach a password, the file must be loaded with the password in order to have private meeting descriptions displayed.

The short description, containing up to 25 characters, is the message that appears next to the time. The long description, containing up to three 75-character lines, can be used to explain the purpose of the meeting. The lines do not wrap, so you must press Enter at the end of each one. The long description is displayed in the Description Area when the meeting is highlighted.


Insert Task

Insert Task places a new task on the calendar. It works exactly the same as Insert Meeting, but instead of entering a time, you enter a priority number.

Priority numbers represent a task's relative importance and can range from 1 to 99. If you assign two tasks on the same day with the same priority number, a warning message is displayed prior to insertion. (You can turn this message on or off using the Tools Preferences Appointment Manager command.)


Insert Similar

Insert Similar places a new meeting or task on the Day Screen using an existing one as a template. After selecting the appointment to be used as a template and filling in its frequency and time period, a definition screen appears. It contains information copied from the meeting or task you specified. Edit the information as necessary, then press the F10 key to record the new entry.


Edit

Edit is used to modify existing entries on the current Day Screen. To edit an entry, select Edit, move the highlighter to the meeting or task you want to change, and press Enter. The definition screen for the selected meeting or task then appears. Change the information as necessary, then press F10 to record them.

If you use the Quick Key to edit an appointment, a definition screen is brought up for whichever meeting or task is highlighted. Be sure to highlight the meeting or task before using the Edit Quick Key.


Heading

The Heading command allows you to place a heading under the current day and date on the Day Screen to signify events or holidays. Select Heading from the top-level menu and type in the heading. The heading can be no longer than 25 characters and can consist of numbers, letters, underscores, and symbols. Headings can be searched for with the Search command.


File

The File menu contains the commands for loading, saving, and unloading appointment files as well as specifying the type of file access and attaching a password.


File Load

When you first enter the Appointment Manager, no appointment file is loaded unless you specified one using the Tools Preferences Appointment Manager in an earlier session.

To load an appointment file, select File Load, enter a filename, and press Enter. You can enter the filename either by selecting it from the prompter or by selecting <other> and typing in the filename. As long as the file is not password protected, the file is then loaded.

If the file is password protected, another option menu is displayed listing General and Private. If you select Private, you are prompted to enter the password. If you select Private and the file is not password-protected, you are prompted to attach a password. If you select General, the file is loaded and any private appointment information is replaced with asterisks.

If a file is already loaded and has been altered, you must choose whether to save the changes before the new file is loaded. If the file does not contain any unsaved changes, it is unloaded automatically and replaced with the new file. If the file is not found, you must choose whether to create it. If you indicate no, the Load command is abandoned.


File Save

File Save stores on disk a copy of the current file. When you select File Save, a prompt to enter the filename appears in the Control Area. If the file does not have a name yet, type in one after the prompt. If it has a name, pressing the Enter key saves the file under its current name. To save the file under a new name, type in a new name and press Enter. This writes a copy of the newly named file in the same directory.

To place the file in a different directory, type in the path and press the Enter key. To verify that the file was placed in the new directory, use the Tools Directory Display command and enter the path and filename. The file should be displayed in the directory listing.


File Unload

File Unload removes any currently loaded appointment file from memory. If the file has been modified, you must choose whether to save the changes before it is unloaded.


File Access

You can use File Access to change the access of a file once it is loaded or while you are creating it. If you are working in an unprotected file, you need to attach a password if you want to insert private information. This password must be entered every time you load the file with private access. If you forget the password, there is no way to retrieve the private information.

If, on the other hand, it is a protected file and you want to make it general access, all the private information is replaced with asterisks. You could also edit all of your private appointments so they are general.


File Password

File Password allows you to attach or remove a password.


Password Attach

Use File Password Attach when you are working in a general access file and you want to add private appointments. Execute the command and type in the password; you are then prompted to re-enter the password for verification. This password must be entered every time you load the file with private access.


Password Remove

If you want to remove the password from a protected file that has been loaded with private access, execute File Password Remove and the password is removed. If the protected file has been loaded with general access, however, the password must be entered before it is removed. The password can be removed only while loaded, which requires that you know the password. This prevents unauthorized persons from accessing private information.


Goto

The Goto command allows you to jump directly to another day on the calendar. It has six options: First, Last, Previous, Next, Relative-Date, and Specific-Date. The Goto command is available only from the Day Screen.

Goto First and Goto Last jump to the first and last days, respectively, on which meetings or tasks are scheduled.

Goto Previous jumps backward on the calendar to the most recent day with a meeting or task scheduled. Goto Next works in a similar manner, jumping forward to the next day with a scheduled meeting or task.

Goto Relative-Date jumps a specific number of days forward or backward on the current calendar. When selected, it prompts you to enter a number of days. Entering a positive number causes the system to jump forward that number of days. Entering a negative number (one preceded by a minus sign) causes the system to jump backward.

Goto Specific-Date prompts you for a date and jumps to that day when you press {Enter}. The date format is determined by the setting the Global Preferences menu.


Remove

The Remove command deletes the highlighted meeting or task from the Day Screen. To remove an entry, select Remove, move the highlighter to the unwanted meeting or task, and press Enter.

If you use the Quick Key to remove a meeting or task, the appointment is removed directly. Be sure to have the correct appointment highlighted before using the Quick Key to remove an appointment.
IMPORTANT: The Remove command permanently deletes information from the calendar. Be certain you have highlighted the correct meeting or task before using it.


Clear

The Clear command removes all appointments from a section of the current calendar. Three options are available: Day, Week, and Month. Clear Day removes all meetings and tasks from the current Day Screen. Clear Week and Clear Month remove the week and month associated with the current Day Screen.
IMPORTANT: The Clear command permanently deletes information from the calendar. Be certain you have selected the correct Day Screen before using it.


Print

The Print command generates printed lists of meetings and tasks. (Days that contain no appointments but do contain a heading are also printed.) Meetings are printed at the top of the page, in chronological order. Tasks are printed below the meetings in order of priority. The Print command has three options: Day, Week, and Month.

Print Day produces a list of the meetings and tasks for the highlighted day.

Print Week produces up to seven daily lists, one for each day in the week that contains an appointment.

Print Month works in much the same way, producing up to 31 daily lists. Lists are not printed for days on which no meeting or task is scheduled.

When you have selected either Day, Week, or Month, you must specify whether to print a short list or a long list. Selecting Short prints only the short descriptions. Selecting Long prints the long description for each meeting or task that has one.


Search

You can search for just meetings, tasks, or headings, or you can search all items. You can also search for specific times, priority numbers, and text.

The day on which you execute the Search command is the point at which the Appointment Manager begins looking for matches. That is, the Search command only moves forward through the calendar.

Select Search from the menu. A definition screen appears containing fields in which to specify search criteria. The first search field is Type, listing All, Meeting, Task, and Heading. Other search fields appear depending on which of these options you select.

If you are searching for a meeting, the screen contains Starting time and Search text. If you are searching for a task, the screen contains Priority number and Text. If you are searching for a heading, the screen contains only Text. If you are searching for all types of appointments and headings, the screen contains all of these fields.

Type in the search criteria and press {F10} to begin the search. As each match is found, it is displayed and highlighted on the screen. A message is also displayed in the Control Area prompting you to either continue or end the search. When no matching items are found, the message Item not found is displayed in the Control Area.


Tools

Use Tools commands to access directories, manage files, and set parameters for the Appointment Manager, all SmartWare modules, and hardware.


Tools Directory

Tools Directory allows you to display, create, change, and remove directories without exiting the Appointment Manager.


Directory Display

Directory Display permits you to view files in any directory without exiting the Appointment Manager. After executing the command, a prompt to enter a file specification is displayed. If you want to see all the files in the current directory, just press Enter. To view files in another directory, enter a full pathname. Other file information displayed in the listing includes the date and time that the file was last modified and its size. Press Esc or F10 to return to the Appointment Manager.


Directory Make

Directory Make allows you to create a directory without exiting the Appointment Manager. Type in the name at the prompt and press Enter.

If you enter a directory name that already exists or is somehow invalid, the message Unable to create the directory appears in the Control Area.


Directory New-Directory

Directory New-Directory allows you to change your current directory without exiting the Appointment Manager, giving you quick access to files in other directories. Upon selecting New-Directory, you are prompted to enter a new directory name. Type in a name and press Enter.

Remember that this change is only temporary; the default path is restored after exiting and reentering the Appointment Manager. If the pathname you enter does not exist or is invalid, an error message is displayed.


Directory Remove

Directory Remove allows you to eliminate a directory without exiting the Appointment Manager. When you execute the command, you are prompted to enter the directory name. It is deleted when you press Enter. If any files or subdirectories are located in the directory, it is not deleted. A message is displayed in the Control Area indicating this. Remove all files and subdirectories before trying again.


Tools File

With Tools File commands you can copy files from one directory to another, erase them altogether, print them, or rename them without exiting the Appointment Manager. All of these functions are intended to act on files that are not currently loaded.


File Copy

You can use File Copy to make a copy of one or more files. You can copy a file to another directory, to the same directory, or to another disk. Executing the command yields a prompter list and a message to select a source file. Use the arrow keys to select the filename. If the file you wish to copy is not listed, select <other> and type in the filename. After pressing Enter, a second prompt to enter the destination path or filename is displayed. Enter the directory and/or subdirectory that you want the file copied into.

If you want two separate but identical files within the same directory, give the file a new name only. You can then edit the second file without altering the original.


File Erase

File Erase permanently removes a file from a directory. Selecting File Erase displays a prompter list of appointment files. If the file you wish to erase is not listed, select <other> and type in the filename. Press Enter and the file is deleted.
IMPORTANT: There is no message that verifies your selection, so be sure to enter the correct file.


File Print

File Print is used to print text files. Any files that you print to a disk file can then be printed using this command. When you execute the command, you are prompted to enter a filename, then press Enter.


File Rename

File Rename allows you to change the name, extension, or path of a file. Executing the command displays a prompter list of appointment files. If the file you wish to rename is not listed, select <other> and type in the filename. Pressing Enter yields a second prompt to enter the new filename. Press Enter to complete the renaming action. If you choose a name that is already used, an error message is displayed.


Tools Preferences

Tools Preferences commands give you access to definition menus for setting Appointment Manager, global, and hardware parameters.


Preferences Appointment-Manager

This command gives you access to a definition screen for setting five Appointment Manager parameters.

Automatic load of appointment file. This allows you to specify a file to be loaded automatically upon entering the Appointment Manager. The file is not loaded automatically until you exit and reenter the Appointment Manager.

Data path. This allows you to specify a default data path. This data path becomes the current directory each time you enter the Appointment Manager until you specify a new directory or change the default data path. Your appointment files are saved in the default directory unless otherwise specified.

Issue conflict warnings for meetings/tasks. These allow you to specify whether you want warning messages for conflicting meetings and tasks. If you specify yes, a message is displayed when you schedule a task with the same priority as another task or a meeting at the same time as another meeting. The appointment is still placed on the calendar; it is intended only to forewarn you of the conflict.

Duration Display. This specifies the format for the duration display of scheduled meetings. You have the option of not displaying the duration of a meeting on the calendar by selecting None, or an Hours:Minutes display format, or displaying an Ending-Time. Remember that None affects only what is displayed on the calendar; the definition screen still contains a field for duration.


Preferences Global

Tools Preferences Global allows you to specify default settings for the SmartWare system. When you execute the command, a definition screen is displayed. Each setting is discussed in Software System Manual.


Preferences Hardware

Use this command when you want to change the default hardware settings you specified during the Install program. When you select the command, a definition screen is displayed. Each option is discussed in Software System Manual.


Tools Text-Editor

Tools Text-Editor gives you access to a text-editor where you can create or edit text files. A prompter list containing the filenames of all text files in the current directory is displayed when you execute the command.


Quit

The Quit command exits the Appointment Manager and returns to SmartWare's Main menu. If the currently loaded appointment file has been changed, you must specify whether the file is to be saved before exiting.


DataLink

When you press F1 to access Help in SmartWare DataLink, the DataLink Help file is displayed. Use Up-Arrow and Down-Arrow, and PgUp and PgDn to scroll through the text.

Table of Contents. Pressing F4 from DataLink Help provides access to the Help Table of Contents. Position the pointer next to "SmartWare DataLink On-Line Help" and press F4 again. Pressing F4 several more times reveals additional levels of topics. Position the pointer next to the desired topic and press Enter.

Index Entries. Pressing F3 from DataLink Help provides access to the Help Index. Press F3 again to see second level index entries. Position the pointer next to the desired topic and press Enter.

Related Topics. To select a related topic, press the Plus key (+) to move the pointer down to the desired topic and press Enter. Press the Minus key (-) to move the pointer upwards.

Getting Started
Exiting DataLink temporarily
Quitting DataLink
Terminating the remsql session
The Info command
The Query command
The Updates command
The Database command
The SQLEntry command
The Exit command


Introduction to DataLink

Welcome to SmartWare DataLink, an innovative SmartWare Programming Language application that allows you to interact with Informix SQL database products through the Spreadsheet module of SmartWare.

SmartWare DataLink harnesses the power of a database engine through the familiar environment of the SmartWare Spreadsheet window. Experience using a database management system is not needed. Simply specify settings in easy-to-use definition screens; DataLink translates your settings into statements the database management system can understand.

You communicate with the database on the host computer through INFORMIX-NET connectivity software.


Installing DataLink

DataLink must be installed correctly before you begin. It is likely that you will need the assistance of a network administrator or MIS representative, and a database administrator. Installation information and system requirements are provided in the DataLink Installation Guide.


Getting Started

Refer to "Chapter 2: Using DataLink" in the DataLink User's Guide for specific instructions on logging in to the host, and starting SmartWare and DataLink.

Briefly, the basic steps are as follows:
1. Load your TCP/IP driver, if it isn't already running.
2. Execute the INFORMIX-NET PC module, remsql, to log in to the host.
3. Start SmartWare by typing smartdl.
4. From the Spreadsheet module, invoke the DataLink menu.
5. Open a database


Info

The Info command invokes the Information screen, which provides information about the tables and columns in the current database.

The Tables list shows the tables in the current database. Press Down-Arrow and Up-Arrow to scroll through the list. Press Tab to move the highlighter to the Columns list.

The Columns list shows the columns of the table highlighted in the Tables list. To the right of the column name is the column's data type, and its length or precision. Press Down-Arrow and Up-Arrow to scroll through the list. Press Tab to return to the Tables list.

Pasting Column Names. Press F7 from the Information screen to copy the column names into the current worksheet and return to the DataLink menu.

Press Escape to dismiss the Information screen and return to the DataLink menu.


Query

The Query command invokes the Query Definition Box, where you define and execute queries. The Query Definition Box has two modes: Entry Mode and Command Mode.

Entry Mode allows you to enter and edit the query settings for individual table columns. Command Mode, as a rule, presents a menu of options that pertain to the overall query definition.

Press Escape to toggle between the two modes.


Using Entry Mode

The largest portion of the Query Definition Box consists of two rectangles divided into labeled columnar sections. Enter the query settings in this area of the screen.

The Query Definition Box has both a highlighter and a cursor.

Highlighter. The highlighter, which moves up and down, marks the table column for which a setting is to be defined. Use the vertical cursor movement keys to move the highlighter.

Cursor. The cursor, which moves horizontally within the highlighter, marks the query setting to be specified. Use the horizontal cursor movement keys to move the cursor. Tab and Shift-Tab can be used to move between the two rectangles.


Using Command Mode

Command Mode presents a menu of the following keywords:

     Autojoin  Computed  Options  File  Generate  Exit

To select one of the Command Mode keywords, position the menu highlighter on the keyword and press Enter. Alternatively, you can press the first letter of the keyword.

Clearing the Query Definition Box
Defining computed columns
Deleting a query definition
Executing a query
Exiting the Query Definition Box
Joining columns automatically
Joining columns manually
Loading a query definition
Marking the destination block
Relational operators list
Retrieving data from a table column
Saving a query definition
Sending output to SQLEntry
Sorting queried data
Specifying selection criteria


To

An entry under the To heading indicates that data from the highlighted table column is to be copied to the worksheet when the query is executed. The number entered represents a relative worksheet destination.

Every query must have at least one entry in the To area.

To specify the To setting:
1. Highlight the table column to be included in the query.
3. Position the cursor beneath the To heading and press Enter.

Press Enter again if you want to remove the entry.


Sort

An entry under the Sort heading indicates that the highlighted table column is to be part of a sort operation. The sort definition has two parts: a number (1-8) representing the column's priority in the sort, followed by a letter representing the type of sort (A for ascending or D for descending).

To define a sort operation:
1. Highlight the table column upon which the sort operation is to be based.
2. Position the cursor beneath the Sort heading.
3. Enter a sort priority (from 1 through 8). DataLink inserts an A to specify an ascending sort. To specify a descending sort, type D. Alternatively, you can press Enter to invoke the Sorting Options screen, which allows you to select the entries from menus.
4. Press F10 to complete the sort definition.

Press Delete if you want to remove the sort definition.


Join

A join operation allows you to query data from multiple tables by defining linking columns called "join columns." The set of columns to be defined as join columns must contain matchable data and must uniquely identify their table rows.

The members of a join are identified by a letter under the Join heading. All members of a join must be assigned the same letter.

To manually define a join operation:
1. Highlight the table column to be designated a join column.
2. Position the cursor beneath the Join heading and type a letter.
3. Repeat the first two steps for each member of the join.

Press Delete if you want to remove a join letter.


Criteria

An expression entered under a Criteria heading controls which rows of data are retrieved. Two Criteria headings are visible on the screen at one time. Eight more are available by scrolling horizontally.

Multiple selection conditions can be specified. The placement of the conditions under the Criteria headings determines how DataLink interprets the conditions.
*** Conditions entered under the same Criteria heading are connected by an implied AND operator.
** Conditions entered under different Criteria headings are connected by an implied OR operator.

To enter a selection condition expression:
1. Highlight the name of the column storing the data to be matched.
2. Position the cursor beneath the appropriate Criteria heading and press Enter.
3. Enter the condition, using the following format: OPERATOR EXPRESSION. The OPERATOR is a relational operator, such as =; the EXPRESSION can be a literal value, a formula, an SQL function, a database column name, or a computed column name. A conjunction (AND or OR) can be used to connect the first condition to an optional second OPERATOR EXPRESSION sequence.
4. Press F10 to complete the definition.

Use the cursor movement keys to position the cursor. Press F3 if you want to clear the Expression editor.

Pressing Escape abandons the definition.


Valid Operators and Keywords

The following table lists valid operators and keywords.

Operator or Keyword | Meaning
= | Equal to
< | Less than
> | Greater than
<> or != | Not equal to
<= | Less than or equal to
>= | Greater than or equal to
expr AND expr | Both expressions must be true
expr OR expr | Either expression may be true
LIKE string | Match the pattern in the string. A percent sign, %, matches zero or more characters. An underscore, _, matches any one character
IN (value-list) | Match a literal value or the value of the keyword TODAY in the value-list
BETWEEN expr AND expr | Match a value falling within the inclusive range of the two expressions.
NOT keyword | Negate the keyword
IS NULL | Has no data entered
MATCHES string | Match the pattern of characters in the string. An asterisk, *, matches zero or more characters; a question mark, ?, matches any one character. [...] matches any one of the characters inside the brackets.

Entering Values. Enclose character strings in quotation marks: "NY", "(913) 555-1234", "A774". Numeric values do not require quotation marks.

Referencing Columns. When you use a column name in an expression, use the format "table.column". Use the format "*column" to reference a computed column.

If you prefer, press F5 to see a list of the columns in the active tables. Position the highlighter over the name of the column to be referenced and press Enter. The column name is inserted at the current cursor position in the Expression editor.


Autojoin

The Autojoin option instructs DataLink to automatically join columns having the same name. The following conditions must be met:
*** Only tables represented by entries under the To heading are eligible for the Autojoin operation. Therefore, at least one column from each table to be joined must have an entry beneath the To heading; this column need not be one of the join columns.
** The columns to be joined must have the same name and data type.

To use the Autojoin feature:
1. Make the required entries in the To area.
2. Select Autojoin from the Query Definition menu.


Computed

The Computed option allows you to define and modify computed columns, which are virtual columns used for obtaining calculated values. A computed column is denoted by an asterisk next to its name in the Name list.
NOTE: You cannot use a computed column in a sort operation or a join.

To define a computed column, select Computed to invoke an empty Computed Column Definition screen.

To edit an existing computed column, position the highlighter (in Entry Mode) on the column to be edited. From Command Mode, select the Computed option. The Computed Column Definition screen, displaying the specified column's calculation definition, appears.


Computed Column Name

Enter or change the name of the computed column in this field. Pressing F3 deletes the current name.


Expression

Enter the expression defining the calculation to be performed in the Expression editor. Pressing F3 clears the editor.

Using Operators. Use the following operators to define the calculation:

Operator | Meaning
+ | Addition
- | Subtraction
* | Multiplication
/ | Division

Expressions are evaluated according to the operator they contain. In general, expressions containing * or / are evaluated before expressions containing + or -. Use parentheses to override this order of evaluation.

Entering Values. Enter numeric values without quotation marks.

Referencing Columns. When you use a column name in a calculation expression, use the format "table.column".

Alternatively, press F5 to obtain a list of the columns in the active tables. Position the highlighter on the column to be referenced and press Enter. The column name is inserted at the current cursor position in the Expression editor.


Options

The Options keyword invokes the Query Options screen. Use the Down-Arrow or Tab to move from one item to the next. Use Up-Arrow or Shift-Tab to return to the previous item.

Output Order. This list shows the table columns that have entries under the To heading. The columns are listed according to the To entry.

To change the order:
1. Position the highlighter on the name of the column to move.
2. Press F6 to mark the column.
3. Move the highlighter to the intended location in the list and press Enter. The marked column is inserted at the current highlighter location.

Press Tab to exit the Output Order list and advance to the next setting.

Display Format. This bar menu controls the way column names are displayed on the Query Definition Box. Change the format by highlighting the setting to be used.

Select Rows. This bar menu allows you to retrieve either all rows containing appropriate data, or only rows that are not duplicates of already retrieved rows. The All setting provides detail information from your database. The Unique setting provides information on how many different values or combinations of values are stored in your database.

Get Column Names. Select Yes to instruct DataLink to include the column names in the data copied to the worksheet. Select No to omit the column names.

Output to SQLEntry. This bar menu controls where the SELECT statement generated from the query definition is sent upon execution.
*** If you want DataLink to send the SELECT statement to the database engine for execution, select No.
** If you want DataLink to send the SELECT statement to the SQLEntry screen, select Yes.

Update Capable. Select Yes if the query to be executed will retrieve rows that are to be modified or deleted. Otherwise, select No, which is the default setting.

Press F10 to accept the current settings and return to the Query Definition Box. Press Escape to abandon the current settings.


File

The File option invokes a submenu of additional options: Load, Save, and Delete.


Load

Select Load to open a saved query definition file and display it on the Query Definition Box.

Choose the file to be opened from the prompter menu, which lists files having the extension .dlq.


Save

Select Save to store the current query definition in a file. You are prompted to specify a filename.

DataLink appends the extension .dlq to the filename you enter.


Delete

Select Delete to remove query definition files. Choose the file to be deleted from the prompter menu of definition files in the current directory.


New

Select New to clear all of the settings on the Query Definition Box and delete computed columns.


Generate

Select Generate to exit the Query Definition Box, save and then execute the current query definition. If the Query Definition Box is in Entry Mode, you can press F10.


 When the retrieved data is obtained from the database engine, the following prompt is displayed:

     Enter block:

You can type the worksheet reference, or you can use blockmarking. The dimensions of the returning rowset are shown on the Autohelp line. Press Enter when the block is specified.

If the block you specified is too small, the Block Size Too Small screen is displayed. Press Enter to accept all of the retrieved data. Press F7 to truncate the data to fit the block. Press F6 to mark a new block. Press Escape to cancel.
NOTE: If the Output to SQLEntry setting is Yes, the SELECT statement is sent to the SQLEntry screen instead of to the engine for execution.


Exit

Select Exit to leave the Query Definition Box without executing the current query. If the definition has been changed, the following prompt appears:

     Save Query Definition? (y/n)

If you answer y, the definition is saved in a temporary file; the assigned filename matches the name of the database. If you answer n, the definition is not saved.
NOTE: To save the definition permanently, use the Save option on the File command on the Query Definition Box.


Updates

The options of the Updates command allow you to add, modify, or delete rows of data.

BLOB data cannot be added or modified through the DataLink interface. Refer to the DataLink Function Reference for information about writing custom applications to manipulate BLOBs.


Rules for Updates

Rows can be added to a table at any time during the period the database is open. Normally, rows are modified or deleted immediately after a query that retrieves them. To protect the integrity of the data, however, DataLink imposes some restrictions. You cannot update rows if any one of the following conditions exists:
** The query retrieved data from multiple tables.
** The query selected only unique rows.
** The rows have been sorted in the worksheet.
** Another database has been opened.
** The update attempts to change the value of a serial column.

In addition, the Update Capable setting on the Query Options screen must be set to Yes for modifying and deleting.


Add

The Add option on the Updates menu is used to insert new rows of data into the table of a database.

To add rows to a table:
1. Use a row of the worksheet to list the names of the table columns that are to receive new data. You can type the names, or you can use the Paste Column Names feature of the Info command to enter the names for you.
2. Immediately beneath the column names, enter one or more rows of data. Be sure that the data you enter is valid for the data types of the columns. These rows of data become new rows in the database table.
3. From the Updates menu, select the Add option. The prompt Enter block reference: appears. Specify the entire block containing the data; include the row of column names. You can type the reference or use blockmarking.

DataLink then adds the new rows to the table.


Modify

The Modify option on the Updates menu is used to change the data in your database. You cannot, however, change the values in a serial column.

To modify rows:
1. Select Query from the DataLink menu and define a query. Make entries beneath the To heading for the columns containing data to be modified. Specify criteria that will select the rows of data to be modified.
2. From the Query Definition Box in Command Mode, select the Options keyword. When the Query Options screen appears, be sure that the Select Rows item is set to All. Set the Update Capable option to Yes. Press F10 to return to the Query Definition Box.
3. Execute the query. The retrieved rows are copied into a worksheet.
4. Exit DataLink and use the Spreadsheet environment to modify the data in the worksheet.
5. Return to DataLink and select the Modify option of the Updates menu. The prompt Enter block reference: appears. Specify only the block containing the data; do NOT include column names. You can type the reference or use blockmarking.

If the data in the table has not changed since the rows were retrieved by query, DataLink replaces the existing rows of the database with the rows in the specified block. If the data in the table has changed since the query was performed, DataLink notifies you. You can then choose to complete the update procedure or to cancel the operation.


Delete

The Delete option is used to delete rows of data from your database.

To delete rows:
1. Select Query from the DataLink menu and define a query. Make at least one entry beneath the To heading. Specify criteria that will select the rows of data to be deleted.
2. From the Query Definition Box in Command Mode, select the Options keyword. When the Query Options screen appears, be sure that the Select Rows item is set to All. Set the Update Capable option to Yes. Press F10 to return to the Query Definition Box.
3. Execute the query. The retrieved rows are copied into a worksheet.
4. Review the returned data in the worksheet to be sure that the desired rows have been retrieved.
5. From DataLink, select the Delete option of the Updates menu. The prompt Enter block reference: appears. Specify only the block of rows to be deleted; do NOT include column names. You can type the reference or use blockmarking.

If the data in the table has not changed since the rows were retrieved by query, DataLink deletes the appropriate rows of the database. If the data in the table has changed since the query was performed, DataLink notifies you. You can then choose to complete the deletion procedure or to cancel the operation.


Database

The Database command is used to open a database, which involves two steps:
1. Selecting the database
2. Selecting the tables to be used

The Database command is executed when you select Database from the DataLink menu, or when you attempt to use one of the other commands without first opening a database.


Opening a Database

When you execute the Database command, the Databases prompter appears. The Databases prompter lists the databases found in the directories or sites specified in your DBPATH environment variable and in your home directory. (If you are using INFORMIX-TURBO, the prompter lists the databases known to the TURBO system.)
NOTE: The search for databases to list is conducted in the order in which the directories are listed in DBPATH.

To cancel the command without opening a database, press Escape.

To select a database to open, position the pointer next to the name of the database and press Enter. To open a database that is not listed on the Databases prompter, select the (other) entry. At the Database: prompt, type the name of the database, including path, and press Enter.

The database is then opened and you can select the tables to be used.


Selecting Tables

After you select a database, the Active Tables screen appears. The screen contains two lists: Available and Selected.

The Available list shows the names of all the tables in the current database. The Selected list shows the tables to be accessible from the Query Definition Box. Initially, the Selected list is empty. For subsequent sessions, the tables chosen the last time you opened the database are shown in the Selected list.

To use DataLink the first time, at least one table must be shown in the Selected list.
*** Press Tab to move the highlighter from one list to the other. The list containing the highlighter is the "current list."
** To copy a name from the current list to the other list, position the highlighter on the name to be copied and press Enter.
** To copy all of the names from the current list to the other, press F7.

DataLink maintains a local file containing structural information about the tables in the database. This file is also used to control the tables that are displayed on the Query Definition Box.

Pressing F10 instructs DataLink to update the local file and to use the tables currently shown in the Selected list on the Query Definition Box.

Pressing Escape instructs DataLink to bypass updating the local file and to use the tables selected from the previous session on the Query Definition Box.

If the database you have opened is large, obtaining structural information and updating the local file can take a considerable amount of time. Press F10 the first time you open the database; thereafter, you may wish to press F10 only when:
*** you want to use different tables on the Query Definition Box, or
** you need to update the local file to reflect changes made to the structure of the database.


SQLEntry

The SQLEntry command allows you to by-pass the DataLink interface and enter or run your own SQL statements. Selecting SQLEntry invokes a submenu of the following options:

     Option:  Edit       Run


Edit

The Edit option allows you to create or modify SQL statements. When you select Edit, a prompter list of text files having the extension .sql is displayed. These files reside in the datalink directory.

The first entry on the prompter is (default). This file represents the file to which a SELECT statement generated from the Query Definition Box is written.

After you select a file, the SmartWare Text Editor appears. If you selected the (default) entry, the SELECT statement from the Query Definition Box appears in the Text Editor.

Enter or modify SQL statements in the Text Editor. Function keys that can be used are shown in the Control Area; press F2 to display additional keys. Refer to an Informix SQL manual for information about SQL usage and syntax.

When you press F10, the file is saved under its current name in the datalink directory.
NOTE: If you have edited the (default) file and press F10, the following prompt appears:

     Save to file? (y/n)

If you answer n, the information is not saved.

If you answer y, you are prompted to enter a filename. DataLink saves the file, using the filename you specified and the extension .sql.


Run

The Run option allows you to select a file containing SQL statements and to send the statements to the database engine for execution.

When you select Run, a prompter menu of files having the .sql extension is displayed. The first entry on the prompter is (default), which represents the temporary file containing the SELECT statement sent from the Query Definition Box.

Select the name of the file to be executed and press Enter. The contents of the file are sent to the engine. When the engine returns a rowset of data, the following prompt appears:

     Enter block:

Specify the worksheet block that is to receive the returned data. A block can be a single cell. You can type the reference or use blockmarking. The dimensions of the rowset are shown on the Autohelp line.

If the returning data cannot fit into the specified block, the Block Size Too Small screen appears.
*** Press Enter to copy all of the returned data to the worksheet.
** Press F6 if you want to mark a new block.
** Press F7 to truncate the data to fit into the specified block.
** Press Escape to cancel.


Exit

To close the database, release system resources, and return to the Spreadsheet, select Exit from the DataLink menu.

If you do not execute the Exit command, DataLink closes the database when you quit SmartWare.


 Press Escape to exit DataLink temporarily and leave the current database open.


 After you exit SmartWare, terminate the remsql session by typing exit.


SmartWare System Error Messages

     0 No Error

The formula contains an error function, i.e., ERRORTEXT(), whose argument is zero. If you are using LERROR or CERROR as the argument, make sure that the correct data is being passed to your error function. LERROR returns the value of the last error that occurred, even when later commands were executed without error. CERROR returns the value of any error occurring during the previous command, or zero if no error occurred.

     1 Missing '('

The formula lacks a left parenthesis. For each left parenthesis in the formula you must supply a corresponding right parenthesis, and vice versa. Check your formula to make sure that the number of left parentheses matches the number of right parentheses.

     2 Missing ')'

The formula lacks a right parenthesis. For each left parenthesis in the formula you must supply a corresponding right parenthesis, and vice versa. Check your formula to make sure that the number of right parentheses matches the number of left parentheses.

     3 Incorrect number of arguments

A function has not received the correct number of arguments. Consult the Formula Reference Manual to determine the proper number of arguments for the functions you are using.

     4 Bad syntax

The formula is improperly written and cannot be calculated. The formula may have an improper operator for the type of expression used, an unrecognizable function or variable name, a function whose scope does not include the current module, or invalid characters. Make certain that function arguments are placed in parentheses, if necessary.

     5 Missing 'THEN'

The formula lacks a portion of an IF-THEN-ELSE statement. Every IF-THEN-ELSE formula requires a THEN clause to indicate what to do when the conditions tested for in the IF clause are met. You must supply the word "THEN" to identify the THEN clause. Consult the alphabetical listing of functions for help in writing logical formulas using this function.

     6 Missing 'ELSE'

The formula lacks a portion of an IF-THEN-ELSE statement. Every IF-THEN-ELSE formula requires an ELSE clause to determine what happens when the IF expression is false. You must supply the word "ELSE" to identify the ELSE clause. Consult the alphabetical listing of functions for help in writing logical formulas using this function.

     7 ERROR

The formula contains a reference to another formula which returns an error. Correcting the error in the referenced formula will eliminate this one.

     8 LOOKUP failed

The search item for an HLOOKUP, VLOOKUP, FILELOOKUP, or TABLELOOKUP formula is not found in the search block or field(s). These functions search for data matching the search item argument(s). Make sure you have specified the correct search block or field list and search item or items. If you are searching for worksheet data that falls within a particular numeric range, use @HLOOKUP/@VLOOKUP.

     9 Serious error

Calculation of a File SDb function has been interrupted because one or more data-file records cannot be accessed. This may indicate that hardware failure or damage to the file has occurred. Examine the file to evaluate its condition. It may be necessary to restore from backup.

     10 Insufficient data

Not enough information is provided in the item list to perform the calculation or some of the information is unavailable due to other errors. @VAR, @COUNT, and STD require at least values; SUM, MIN, MAX, AVERAGE, STDEV, SUMSQ, VAR, and COUNT require at least 1 value in the item list.

     11 Division by zero

Calculation of the formula entails dividing a number by zero. Mathematically, division by zero is undefined. SmartWare allows you the alternatives of returning either zero or Error 11 when this condition occurs. The Division by zero is: setting in the Tools Preferences Global menu controls this feature.

     12 Bad cell reference

The formula contains a term interpreted as a cell or block reference that cannot be resolved. The formula may reference a named cell or block that is no longer defined. The problem may lie with an external worksheet reference that consists of a valid worksheet name but an invalid or missing cell or block reference. Verify the correctness of the target of any assignment statements and/or the argument of any CELLTEXT functions in your formula.

     13 Function or assignment not valid in this context

A formula or statement uses a function in a manner for which it is not designed. For example, use of BLOCKMARK is restricted to project commands and statements where it permits interactive selection of a block during project execution. BLOCKMARK cannot be used directly in a formula cell or a user-defined function called by a worksheet or calculator formula. Likewise, assignment functions, such as LET and SSPUT, cannot be used directly in a cell.

     14 CASE failed

No match is found for the search item in a formula using the CASE function and no ELSE statement is included in the CASE formula. Make sure that you have specified the correct item to be matched, included all appropriate items to be compared in the case list, and included an ELSE statement if there is a possibility that no match will be found.

     15 SELECT failed

None of the logical expressions in the select list is true and no ELSE statement is included in the SELECT formula. Make sure that you have specified the correct terms in your select list, used the correct relational operators in the logical expressions, and included an ELSE statement if there is a possibility that none of the conditions is true.

     16 Function not available in current module

The formula contains a function whose scope does not include the SmartWare module in which you are currently working. Make sure that you have entered the function name correctly.

     17 Expression too complex

Calculation of the formula requires manipulation of expressions or terms that are too lengthy or too complex. Revise the formula to simplify the operations or calculations involved. Use data references where appropriate. Try performing the calculation in two or more steps.

     18 Bad argument

The formula contains an argument that is of the wrong expression type or is out of the range required for the function with which it is used. Make certain that all functions receive arguments of the appropriate type and value.

     19 Missing worksheet

The formula contains a term interpreted as a data reference to a worksheet that is not active. You must load or activate the referenced worksheet before recalculating this formula.

     20 Missing name

The formula contains a term interpreted as a reference to a named cell or block in an external worksheet. No such name is defined for that worksheet or the worksheet is unavailable. Load the referenced worksheet and use Sheet Name Edit to check the defined names. Then edit the formula to include the correct name.

     21 First argument must be date

When you use two arguments with this time function, the first argument must be a date expression.

     22 Bad date

A date expression is either improperly formatted or results in a date that is impossible (e.g., "02/31/87") or out of the range of dates supported by SmartWare.

     23 Bad time

A time expression is improperly formatted, results in a time that is impossible, or is out of the range of times supported by SmartWare (e.g., "25:00:00").

     24 CHOOSE failed

The value of the first argument of the CHOOSE function is less than 0 or greater than the number of items in the item list minus 1. Make sure that you have specified the correct terms in your formula and that the item list includes all the appropriate items.

     25 Missing ',' or ')'

Within a function, either a comma is missing, as in the example ATAN2(3 15), or a right parenthesis is missing, as in ATAN2(3,15.

     26 Date expression expected

A formula expects a date expression but another type of expression has been encountered. Make certain that all date expressions are properly formatted and that all functions and operators are used with expressions of the appropriate type.

     27 Inconsistent number of arguments

The formula employs a user-defined function that has not received the correct number of arguments. Make sure that you are using the correct function name and the number of arguments it requires.

     28 Out of string space

The formula requires manipulation of a text expression that is too long. Revise the formula or the text expressions involved in the calculation.

     29 Expected block

The formula contains a function that requires one argument to be a block reference. Correct the formula so that, where necessary, the function receives a reference to a block of cells or fields.

     30 No convergence

The data contained in the arguments for a recursive function (e.g., IRR, GOAL, INTEREST) do not converge to yield a specific result. For IRR, at least one number in the block must be negative. For GOAL, check and revise your initial estimate to make it more closely approximate the final result.

     31 Invalid field

The formula contains an item interpreted as a field reference (i.e., within brackets) that is not a valid field title or number in the current view. Make sure that you are working with the correct view and check all field references in the formula.

     32 Cell out of range

The offset argument for an HLOOKUP, VLOOKUP or INDEX function is negative or refers to a cell that is outside of the defined block.

     33 Can't execute project file function. Overlay conflict.

Using one of the text editors, you have attempted to recalculate using a function from a loaded function library. There is an overlay conflict between the function library and the text editor you are using.

     34 Variable not found

The formula contains an item interpreted as a public variable that has not been declared. Check the formula for errors or ambiguous expressions. Public variables must be declared with a Public statement.

     35 User error

You have calculated a formula using the ERROR function. This function allows you to generate a formula error based on conditions you specify.

     36 Invalid variable assignment

The formula contains a LET statement that attempts to assign a literal data reference (i.e., a cell, field, or variable address) to a target rather than the data denoted by the data reference. Verify the format of your formula and make sure that all functions receive the correct expression types as arguments.

     37 Not text variable or character offset outside text

The formula contains an item interpreted as a text variable subscript that cannot be resolved. Character subscripts can only be used with text variables. The subscript must be numeric and must not be greater than the length of the text expression referenced by the variable nor less than one.

     38 Bad index value to array

The formula contains an item interpreted as an array reference that cannot be resolved. The array must contain the correct number of subscripts, corresponding to the number of array dimensions. The subscripts must be numeric and must not have a value larger than the number of array elements nor less than one.

     39 Invalid LET or command target

The formula contains an expression interpreted as an assignment statement that attempts to place data in an invalid LET or command target. You can use LET to assign data to variables, fields, and cells (e.g., LET variable1 = 2). You cannot assign data to a formula, constant, or data reference (e.g., LET 2 = #variable1). You cannot use LET or SSPUT to assign data to a formula cell during worksheet recalculation.

     40 Missing equal sign in LET

Your formula contains a LET statement that lacks the equal (=) sign. The correct format is LET target = expression .

     42 Incomplete formula

The formula is improperly written and cannot be calculated. Check the syntax to make sure that all expressions and data references have the correct format and are complete.

     43 Calc stack bad

The source of a calculation has somehow been corrupted. Restore the file from backup.

     44 Calc token unknown

Some damage has occurred to the formulas in your data file or project file. Save the current file under a new name and exit the module, when possible. It may be necessary to recover your files from backup.

     45 Data is not available

The formula describes a calculation that cannot currently be performed. A variety of conditions may produce this error, including those mentioned in the following paragraph. If you receive this error, examine your formula carefully to determine whether or not it describes a meaningful or realistic calculation.

During view definition, you cannot calculate a formula containing a field reference to the view being defined. In Enter/Update mode, you cannot calculate a formula involving a file SDb function. Formulas using FETCHFIELD return this error when no record has previously been accessed since the file was loaded.

     48 No expression found

The formula contains an item interpreted as an expression or a data reference that cannot be located. Check the syntax to make sure that all expressions and data references have the correct format and are complete.

     49 No closing array bracket

The formula contains an array reference but lacks the closing (]) character for the array subscript. The correct format for a reference to an array element is A[S], where A is an array name and S is the subscript number or numbers.

     50 Missing or bad array index

The formula contains an item interpreted as an array reference that lacks or has an invalid subscript. The array must specify the correct number of subscripts, corresponding to the number of array dimensions. The subscripts must be numeric and must not have a value larger than the number of array elements nor less than one.

     51 Hex constant too large

The formula contains a hexadecimal value greater than the maximum supported by SmartWare: FFFF FFFF (32 bits).

     52 Project file function not loaded

The formula or statement calls for a user-defined function that is not available. You must load the project file that defines the function before attempting to calculate the formula or execute the statement. The project file that defines the function must contain a Public statement allowing the function to be called externally.

     53 Undefined variable or function

The formula or statement contains an unrecognized term. Check the syntax for errors and ambiguous expressions. All variables and arrays used in projects must be declared by means of a Local, Global, Public, or external statement. All functions must be declared by using a Global, Public, or external statement.

     54 Array already exists with variable name

SmartWare's Project Development Language requires that all variables, including arrays, have unique names. Project files currently in use contain variables and/or arrays identified by the same name. Edit your project files to change the name(s) as necessary.

     55 Too many functions deep - danger of stack overflow

A command or statement in a user-defined function calls for another user-defined function that calls for yet another. The number of such "nested" or recursive function calls is approaching the maximum (50). Edit your projects to reduce the number of successive function calls. Main counts as the first "level."

     56 Unknown compiler token - try recompiling

SmartWare is unable to continue executing the project or user-defined function, possibly due to corruption of the file or a memory fault. Try recompiling the project file(s) or restore from backup.

     57 Error in FOR loop

The expression used to specify the initial counter value, loop length, or step increment in a For statement is invalid. These entries must be numeric.

     58 Insufficient memory

Execution of the project or calculation requires more memory than is currently available in the system.

     59 Error reading project file

SmartWare is unable to continue executing the project or calculation, possibly due to corruption of the file or a disk error. It may be necessary to restore from backup.

     60 Invalid file number

An expression used to specify the file number in a project data file command (e.g., FOPEN, FREAD . . .) falls outside the allowable range, 1 through 20.

     63 Bad search field

The search field specified in a FILELOOKUP formula references a field that cannot be identified or is not a data-file field. All views used in the lookup must be active. Make sure that you have entered all field references correctly, including the view name where needed.

     64 Search field is not a key field

The search field specified in a FILELOOKUP formula references a field that is not a key field. Make sure that you have entered all field references correctly and that the search field is a key field.

     65 Bad return field

The return field specified in a FILELOOKUP formula references a field that cannot be identified or is not a data-file field. All views used in the lookup must be active. Make sure that you have entered all field references correctly, including the view name where needed.

     66 Search and return fields are not from the same view

The search and return fields specified in a FILELOOKUP formula must be located on the same view. Make sure that you have entered all field references correctly, including the view name where needed.

     67 Bad search data

One or more expressions used to specify the search data in a FILELOOKUP formula return data invalid for a search. Make sure that each search argument is a valid expression and does not return an error, NA, or BLANK.

     68 Cannot execute module commands recursively

A formula or project calls a user-defined function that contains a module command. Unlike project commands, module commands cannot be used in functions that are executed by formulas or other module commands.

     100 Error writing project file

Check the path you have specified to ensure you have access rights to the directory. If the directory and path you have specified are available to you, either insufficient disk space remains to write the file, or a disk error has occurred during the internal operation involved in writing the file.

     101 Invalid project filename

You have entered an invalid filename; a maximum of 78 characters are allowed when specifying a drive and path in conjunction with a filename. Try the command again, using a valid filename.

     102 Can't compile active project (loaded from disk or remembering)

You cannot compile a project which is currently loaded or being processed within Remember Mode. Unload the file or exit Remember Mode, and then compile the project.

     103 Already in remember mode

You tried to access Remember Mode while already in Remember Mode.

     104 Remember not allowed while project executing or suspended

You cannot access Remember Mode while a project is executing or is suspended.

     105 Not in remember mode

The command Remember Finish was executed when you were not in the Remember Mode. Remember Start must be used to begin Remember Mode.

     106 Can't open project file

Project file cannot be opened. Make sure project file exists and has the correct path. Access may have been denied because file is in use at another station.

     107 Error deleting file

An error was encountered in attempting to delete the file. The file may be in use at another station, or marked Read-Only.

     108 Invalid target

The destination specified for this input item is invalid. Generally, a destination must be a variable, field reference or a cell reference.

     109 Too much text

Too many characters were entered while defining a table in the Remember Input-Screen command. Either enter fewer characters, or define a larger table.

     110 Cannot remember keys while remembering a macro

You cannot execute the Remember Start Keys command while remembering with the Tools Macro Remember command.

     111 Page too small to print on

The page size specified in your Global Preferences is too small. You must allow for at least eight lines per page and seven characters per line for formatting.

     175 File(s) not found.

SmartWare is unable to find the file or files you have specified. Make sure you are entering the proper name. Include the proper path to the file if necessary.

     176 Can't rename temporary resource library.

A temporary file created when you modify with the resource library cannot be renamed. Make sure you have proper permissions to rename and delete files in this directory.

     177 Error reopening resource library.

The resource library cannot be re-opened. Make sure you have rights to access files in this directory and that the file is not in use at another station.

     178 Error building new resource library.

SmartWare is unable to repack the resources in your library. This would indicate that some resource or disk file was unreadable, or some other I/O error has occurred.

     179 Error writing to disk file.

Check the path you have specified to ensure you have access rights to the directory. If the directory and path you have specified are available to you, either insufficient disk space remains to write the file, or a disk error has occurred during the internal operation involved in writing the file.

     180 Error reading resource file.

The resource file cannot be read, possibly due to corruption of the file or a disk error. It may be necessary to restore from backup or reinstall SmartWare.

     181 Error opening disk file.

The file you specified cannot be opened. Make sure the file exists and has the correct path. Access may have been denied because file is in use at another station or because the file has been corrupted.

     182 Error opening resource file.

SmartWare is unable to open the resource file you specified. Make sure the file exists and has the correct path. Access may have been denied because file is in use at another station or the file may have been corrupted.

     183 Can't delete disk file.

SmartWare is unable to delete the file that you wish to replace. Make sure the file exists, and that you have permissions to delete files from the directory.

     184 Can't rename temporary file.

A temporary file created when you modify resource libraries could not be renamed. The new or old filename or path may have been nonexistent or invalid. You also may not have the proper permissions to rename files in this directory.

     185 Invalid file specification.

You have entered an invalid filename. Make sure that you have typed the name correctly, and that it conforms to DOS filenaming conventions.

     186 Invalid path.

You have entered an invalid path. Make sure that you have properly typed the path and that the path does exist. A maximum of 78 characters are allowed when specifying a drive and path in conjunction with a filename. Try the command again and specify a valid pathname.

     Error reading resource library.

SmartWare is unable to read the resource library possibly due to corruption of the file or a disk error. It may be necessary to restore from backup or reinstall SmartWare.

     200 Cannot rename an active file

The file is active. To rename it, you must first finish execution or unload it.

     201 Cannot print an active file

The file is active. To print it, you must first finish execution or unload it.

     202 Rename was not successful

The file was not renamed. The new or old filename or path may have been nonexistent or invalid. You also may not have the proper permissions to rename files in this directory.

     203 Can't copy a file to itself

A destination with a different name or path must be given for the file you wish to copy.

     204 Invalid directory name

When attempting to make or remove a directory, the indicated name was not a valid DOS filename. It may have been too long, or contained illegal characters.

     205 Unable to create the directory

The directory was not created. You may be out of disk space, have no write permission to this directory, or have used an invalid directory name.

     206 Unable to remove the directory

The directory was not removed. The directory may not exist, may be read-protected, or may not be empty, or you may have used a bad name.

     207 Disk is full -- continue (y/n)

The disk became full during a write operation. Press "y" if you want to continue. Press "n" if you do not.

     208 Cannot delete (filename) -- continue with other files (y/n)

One of the files you have designated to be erased can not be erased. You may have entered a bad name, or the file may be read-protected, or the file may not exist in this directory. You may choose "y" to continue deleting the other files designated, or "n" to abandon the command.

     209 File (filename) not found -- continue with other files (y/n)

One of the files you have designated to copy was not found. You may have entered the name incorrectly, or the file may not exist. You may choose "y" to continue copying the other files designated, or "n" to abandon the command.

     210 File (filename) is active -- continue with other files (y/n)

A number of the Tools File commands require the file to be inactive (not in use by a SmartWare module) before the command can be executed. One of the files you have selected for this command is active. You may choose "y" to continue with the other files designated, or "n" to abandon the command.

     214 Can't copy/move multiple files to single file

Be sure the location you have selected is a directory, not a single file. For example, enter c:\mydir\files\ to make sure the files go into the files directory, not overwrite each other by going into a file called files.

     250 Edited macro is too large

The number of keystrokes that can be entered into a Macro varies between 100 and 500 depending on a number of factors. The keystrokes you have added while editing this macro have put it over the limit.

     251 Error opening macro file

The macro file you have specified may be in a directory that you do not have access rights to, or you may have specified a bad name or path. Or a disk error has occurred during the internal operation involved in opening the file.

     252 Already remembering

No other remembering session can be initiated in the middle of a Tools Macro Remember command. You may have executed Tools Macro Remember twice, or executed Remember Start after you began defining your macro.

     253 Error writing macro file

Check the path you have specified to ensure you have access rights to the directory. If the directory and path you have specified are available to you, either insufficient disk space remains to write the file, or a disk error has occurred during the internal operation involved in writing the file.

     254 Macro is too long

The number of keystrokes that can be entered into a Macro varies between 100 and 500 depending on a number of factors. The macro you have defined is too long. You must reduce its size.

     255 Key not definable as a macro

Certain keys that have special meaning to SmartWare cannot be defined as macros. These are Escape, Enter, F1, F10, Ctrl-C, Ctrl-M, Ctrl-F10, Alt-F10, and Shift-F10. Choose another key for your macro.

     256 Error reading macro file

The macro file cannot be read, possibly due to corruption of the file or a disk error. It may be necessary to restore from backup.

     257 Missing equal sign on line (line number)

In a macro file being loaded, the key to be defined is separated from the macro definition by an equal sign (=). This is missing. Either the definition was left off, or perhaps the preceding macro line was prematurely ended by omitting a comma at the end of the line to indicate a continuation.

     258 (Name) is not a valid keyname

In a macro file being loaded, the indicated name was expected to be the name of a key to define a macro for, but the name did not match that of a known key. Check for spelling errors. See Project Processing manual for list of valid keys.

     259 Macro for key (keyname) is too large

The macro for the key you indicated is too long and could not be loaded. Edit the file and reduce the size.

     260 Unrecognizable character at line (line #) column (column #)

An error was detected at approximately the line and column indicated by the error message. Edit the definition for proper syntax.

     261 No macros are currently defined

You have executed Tools Macro View to see all macros defined 1for this module. However, none have been defined or loaded.

     262 Key value too large to macro

The numeric value of the key is too large. This probably occurred in a KEY DEFINE command, where the key was defined as a number greater than 1023.

     263 Incomplete macro definition

A comma at the end of a line in a macro indicates that the definition continues on the next line; however, there is no next line. Remove the comma.

     300 Bad paging or data path in global preferences

A paging or data path specified in global preferences is invalid. The pathname may contain too many characters or an illegal character, or the path specified does not exist. Select Tools Preferences Global to make the correction.

     301 Bad path or path too long (path)

The specified path contained an illegal character, or contained more than the maximum number of allowable characters.

     302 Path not accessible (path)

The specified path does not exist. Numerous errors can cause this message. A directory name may be spelled incorrectly; the colon following the drive letter may have been omitted; an incorrect subdirectory may have been entered.

     303 Error creating preference file

In a multi-user environment, the system directory may be read-only. This message is issued when SmartWare is unable to create a preference file in a local directory. The disk or directory may be full.

     304 Cannot save preferences

You have "read-only" permission for certain files. You can specify settings in the Tools Preferences menus for use during the current session, but the settings will not be saved.

     305 Value must be between .1 and 2.0

The specified plotter pen width must be between .1 and 2 millimeters.

     306 Value must be between 1.00 and 100.00

The entries for paper width and paper length must be between 1 and 100 inches. The specified plotter speed must be between 1 and 100 centimeters per second.

     307 (driver type) driver (driver name) does not match equipment

The driver you have specified in Tools Preferences Hardware does not match the equipment being used. Refer to the Software System Manual for more information on selecting the appropriate driver files.

     308 Could not load (driver name) driver  -- none selected yet

SmartWare is unable to load a driver, e.g., the Text Screen driver, because none has been selected. The Tools Preferences Hardware menu is displayed so that you can make your selection.

     309 Screen font is missing or corrupted

A screen font file, having the extension .SFF, is missing or has become corrupted. Refer to the Install Manual for instructions on re-installing files.

     310 New screen size will activate upon re-entry

SmartWare has acknowledged your selection of a screen having a size different from the current screen, but the change will not take place until you exit and then reenter SmartWare.

     311 Could not load (driver name) driver -- Insufficient memory

Not enough memory is available to load the specified driver. Clear some room in memory and try again.

     312 Could not find (driver type) driver (driver name)

SmartWare is unable to locate the driver file indicated. It must be present in either the data or the system directory. You may have to re-execute Install to recover this driver.

     313 Device file (filename) was not found

SmartWare does not recognize the filename entered as a valid selection. If you typed the name rather than selecting it from the list, the name may have been misspelled. This message is also issued if you try to leave the Tools Preferences Hardware menu without selecting a Text Screen driver.

     314 Hardware driver will activate upon re-entry

The hardware driver has been changed in Tools Preferences Hardware, but the change will not take effect until SmartWare is restarted.

     315 Network driver will activate upon re-entry

The network driver has been changed in Tools Preferences Hardware, but the change will not take effect until SmartWare is restarted.

     316 Outdated SMARTHDW.DEF found. Install new one at your convenience.

You have installed a newer version of SmartWare, but there is still a hardware preferences file from an earlier version, possibly in your local directory. Use Tools File Erase to remove SMARTHDW.DEF from your home directory, then set up your hardware preferences again using Tools Preferences Hardware.

     317 Invalid plotter paper size.

The plotter paper size you have entered is invalid. Press F6 at the prompt to display a list of valid paper sizes and select one from this list. Alternatively, the paper size you have selected may not be supported by your plotter.

     318 Error loading plotter descriptor at line %d.

SmartWare has encountered an error at the specified line in the descriptor file. You can attempt to edit the plotter descriptor, or contact Technical Support.

     Error opening plotter descriptor

The plotter descriptor you have specified either is in a directory that you do not have access rights to, or a disk error has occurred during the internal operation involved in opening the file.

     320 Error in plotter command definition.

If you receive this error using a plotter definition file that that you have edited, you have entered a command that the plotter driver cannot interpret. If you are using a plotter definition file supplied by SmartWare Corp., please contact Technical Support.

      321 Missing character comparison table (table name), defaulting.

The comparison table you have specified on the Global Preferences menu could not be found in the resource library. Make sure you have that file in the Miscellaneous category of the appropriate resource library. The system has defaulted to using the internal American/English table.

     322 Bad comparison table (table name) line (position) col (position), defaulting.

The comparison table you have specified on the Global Preferences menu contains a bad format at the specified location. This should only occur if you have edited the .CCT file or created your own .CCT file. Correct the error at the specified location and try to specify the table again. In the interim, SmartWare has defaulted to the internal American/English table.

     350 Unable to prerasterize font

This is a general message indicating that an error preventing rasterization has occurred.

     351 Graphics fonts not supported on selected printer

The printer you have selected does not support graphics fonts. Graphics capability is required for prerasterizing fonts.

     352 Unable to find valid font

SmartWare is unable to find any valid filled-area or prerasterized fonts to convert.

     353 Unable to access filled area font file

SmartWare is unable to access the filled area font file for the typeface requested.

     354 Cannot prerasterize, pixel size too large

Some of the combinations of point size and printer resolution are too large to be prerasterized. The font can be printed as a filled area font.

     355 Too many sizes prerasterized for the font family

Only 10 point sizes per typeface can be prerasterized for each printer resolution.

     356 Unable to create temporary file

SmartWare is unable to create the temporary file used in making a new font file, probably because of a restriction of privileges or insufficient disk space.

     370  Warning:  Some memory lost during DOS execution

Running some memory-resident programs from Tools OS may cause this error message to be displayed. The message indicates that the program has taken some memory formerly available for SmartWare. It may be necessary to exit SmartWare and reboot your machine to clear this block in memory.

     371  DOS access not successful

For some reason, SmartWare is unable to access DOS. The COMMAND.COM file could be missing or inaccessible.

     372 DOS access is disabled

You cannot access the operating system at this time. The project being executed contains the OSEXIT OFF command, which prevents access to DOS. After the project has finished running, operating system access is reactivated.

     373 Error creating SmartWare save file for DOS shell.

You have attempted to write out part of SmartWare's environment with BIGOS. SmartWare was unable to create the save file necessary to accomplish this. You may not have the proper permissions, or you may not have enough disk space.

     374 Error writing SmartWare save file for DOS shell.

The save file created with BIGOS could not be written to disk. You may be trying to write to an invalid path, be restricted by permissions, or have insufficient disk space.

     375 No COMSPEC in environment for DOS shell.

COMSPEC could not be located in your DOS environment. Without it, BIGOS could not write out SmartWare's environment.

     380 Line is too long

In project files, any single command line must be less than 1024 characters in length and cannot be continued more than 50 lines. In editors, such as Tools Text-Editor, Remember Tools Edit, etc., lines must usually be less than 256 characters long.

     381 Text (text string) not found

The text string specified for search was not found. Check to make certain you entered the proper string and search options.

     400 Invalid FOPEN option

There are two categories of options to the FOPEN command, path and read/write mode. Only specific constants or expressions evaluating to integers are allowed. Read discussion of FOPEN command in the Project Processing manual for more information.

     401 Not enough values to satisfy template

The template in a PACK, UNPACK, MEMPACK, PEEK, POKE, INTERRUPT, or FARCALL command is expecting more parameters that were provided in the command line.

     402 Bad format in template

The template string in a PACK/UNPACK, MEMPACK/UNPACK, PEEK/POKE, INTERRUPT, FARCALL, BUFFER or MEMALLOC command is not correct. See the discussion of the appropriate command in the Project Processing Manual to determine proper command syntax.

     403 Too much menu text

Too much text has been entered to fit into the menu you have created. Approximately 500 characters of keyword text, including surrounding spaces is allowed. Either reduce the amount of text, or enlarge the menu.

     404 Too many menu choices

Too many menu choices have been entered for the designed menu. The number of choices must be reduced, or the menu size enlarged.

     405 No menu choices

Menu choices must be entered into the appropriate Screen command in order for them to appear in the menu.

     406 Menu area too small

Too many choices have been entered for the menu size indicated. Or, the area could be narrower than one of the keywords. Decrease number of choices, or increase size of menu.

     407 Printer not open, or opened in RAW mode

An LPRINT command is being executed while one of the following conditions exists: the printer was opened in RAW mode, or an OPEN-PRINTER command is being attempted when the printer is already open in RAW mode.

     408 Variable required

A number of project commands have parameters that must include a variable, cell reference or field reference as a place to store data. Check the requirements of the command you are executing in Project Processing Manual.

     409 Invalid line/column parameters

The line and column parameters specified in SCREEN commands must be between 1 and the maximum number of lines or columns displayed on your screen. Check these parameters to make sure they fall within these limitations.

     410 Error opening user file

The user file you have specified either is in a directory that you do not have access rights to, or a disk error has occurred during the internal operation involved in opening the file.

     411 Error closing user file

Either you do not have write access to the directory containing the file or a disk error has occurred during the internal process involved in closing the file. Any changes made to the file during this session have been lost. If you are unable to successfully close the file, the contents of the file are permanently lost.

     412 Error reading user file

The user file cannot be read, possibly due to corruption of the file or a disk error. It may be necessary to restore from backup.

     413 Error writing user file

Check the path you have specified to ensure you have access rights to the directory. If the directory and path you have specified are available to you, either insufficient disk space remains to write the file, or a disk error has occurred during the internal operation involved in writing the file.

     414 Error seeking user file

An error has occurred attempting to go to a position within the file using the FSEEK command.

     415 Error opening printer

A failure has occurred in attempting to execute the OPEN-PRINTER Command. This message was probably the last in a series of errors you received as SmartWare was not able to load the printer driver you selected, a generic printer driver, or to build any type of printer configuration. You may be attempting to do things with OPEN-PRINTER that are beyond scope of the command.

     416 Variable does not contain a valid save screen

Before the SCREEN RESTORE command can be used, the variable in it must be assigned a valid section of the screen with the SCREEN SAVE command. Without this, there is no screen to restore.

     417 Cursor type must be between 0 and 3

The LOCATE command can place one of four different types of cursors at a specific location. You must specify 0 for off or no cursor, 1 an underline, 2 for a square, or 3 for a rectangle.

     418 Reply buffer is full

The REPLY command has been used to provide responses to too many prompts. The buffer can hold approximately 22 responses.

     419 Not current revision, please recompile

You are trying to execute a project file compiled under an earlier version of the SmartWare Project File Compiler. Or, you may be trying to execute a non-project file. Recompile under the current compiler and try to execute again.

     420 Can't execute -- compiled in a different module

This project file cannot be executed in the current module, because it was compiled in a different module, and contains commands specific to that module. Or, you may be trying to execute a non-project file.

     421 Combined variable or array name lengths too long

During loading or execution of a project file, name and length information for all the public and external variables and arrays must fit in an internal buffer about 6,000 bytes long. Try reducing the length or quantity of your public or external names.

     422 Array exists with variable name (name)

All variables and arrays must have a name unique from any other variable or array. Declare variable with another name.

     423 Variable exists with array name (name)

All variables and arrays must have a name unique from any other variable or array. Declare array with another name.

     424 External variable not found (name)

The project is unable to find the variable referenced with the EXTERNAL command. The file containing the variable may not be loaded, or the variable was not declared as a PUBLIC variable.

     425 External array not found (name)

The project is unable to find the array referenced with the EXTERNAL command. The file containing the array may not be loaded, or the array was not declared as a PUBLIC array.

     426 Number of array dimensions different (array name)

You are declaring and referencing this array, with different dimensions. For example, you may have declared the variable cost[12], a one dimensional array, but later reference the array cost[1,12], a two dimensional array.

     427 Printing aborted

During LPRINT or LPRINTRAW, you aborted printing by pressing Escape or ^Z. You may want to turn Error Off in the project file and test for the CERROR number after each LPRINT or LPRINTRAW.

     428 File number already opened

This number has already been used to open a file with the FOPEN command. If you wish to open another file, you must assign a different number.

     429 File number not opened

The file number you requested must be opened using the FOPEN command before using commands such as FREAD, FSEEK, FWRITE or FCLOSE.

     430 Key string invalid

An invalid Key string has been specified. See discussion of KEY Command and KEYS Statement in the Project Processing Manual for valid string elements and format.

     431 Can't TRANSFER or EXECUTE from within module command

TRANSFER or EXECUTE commands can only be placed in Main section of the project file or in a function.

     432 Error seeking file

An error has occurred attempting to load the compiled version of the project file. You may have a bad run-time file. Recompile the project file and try again.

     433 On-Error command failed

The On-Error command has failed. Make sure the function it calls has been declared PUBLIC. If ON-ERROR calls an EXTERNAL function, make sure the file declaring it is loaded or executing.

     434 In valid buffer or memory record size

The size specified to allocate in a BUFFER or MEMALLOC command is either zero or too large to allocate (larger than approximately 65,500 bytes).

     435 Buffer or memory record too small

The buffer or memory record specified in PACK/UNPACK, MEMPACK/UNPACK, PEEK/POKE, INTERRUPT or FARCALL command is smaller than the template string is expecting.

     436 Only 20 breakpoints allowed

No more than 20 break points can be added to the list of conditions that cause the project file to be interrupted with the Remember Tools Trace command.

     437 Invalid double precision number in buffer or memory record

The template in an UNPACK, MEMUNPACK or PEEK command is attempting to load a double precision number that does not conform to SmartWare's format. It is probably accessing data that was not first stored with the PACK, MEMPACK or POKE command.

     438 Invalid SMARTPEEK or SMARTPOKE operation

This error message can be issued for several reasons. A code number may be out of range. You may be trying to write a non-writable option. You may be trying to write to a string field, using a string that is too long.

     439 Invalid memory record

The target parameter in a MEMPACK, MEMUNPACK, or MEMFREE command is not a record allocated using the MEMALLOC command.

     440 Invalid interrupt number or FARCALL address

The argument to INTERRUPT or FARCALL is zero or the INTERRUPT number is greater than 255. The numbers must fall within this range.

     441 Command conflict, can't execute SOUND, FREAD, MENU, or PROMPT command.

On of the commands listed above was being executed when a project function was called that also used one of these commands. This is not allowed because it will overwrite a SmartWare data area.

     464 Function or property (name) not found or object not set

The ActiveX object variable is either not set to a valid ActiveX object, or the function or property named is not a member of the object.

     465 Error Number: (number) Source: (source) (error)

The ActiveX object function or property caused an exception to occur. You should call the ACTXERROR function for a numerical description of the error or the ACTXERRORTEXT function for a textual description of the error.

     500 System locks not allowed on arrays

Arrays cannot be system locked. They can only be module locked. See discussion of Lock command in Project Processing Manual.

     501 Unexpected end of file

The project file ended unexpectedly. The error could be generated by a continuation character (\) in the last line of the file.

     502 Nesting error

An error has been encountered in the structure of nested commands in the project file. Any IF, FOR, WHILE, or CASE structure must be totally enclosed by another such structure. Carefully review the logic and flow of all commands in your nested structure.

     503 Leftover text found after evaluation

Extra characters, or characters not expected in the command syntax have been found in your project file. This typically indicates an error in an expression (such as a missing operator), extra arguments to a command, or the single apostrophe (`) was missing at the beginning of a COMMENT. Edit the file to remove these characters and recompile.

     504 Missing label name in LABEL or JUMP

A label name is missing in a LABEL or JUMP command. Enter a label name for each LABEL and JUMP command and recompile.

     505 Duplicate label within function

Each LABEL command within a function must have a unique name. You have two LABEL commands with the same name. Rename one and recompile.

     506 Unresolved label

A JUMP command has tried to jump to a label that does not exist in the current function. Make sure each JUMP command has a valid LABEL command.

     507 Bad FOR variable

The FOR Statement counter variable must be declared and conform to the rules for variable names discussed in the Project Processing manual.

     508 Missing = in FOR statement

The equal sign is missing in a FOR statement. The syntax for a FOR statement must be:

     FOR variable = numeric TO numeric

The variable must be followed by an equal sign.

     509 Missing TO in FOR statement

The word TO is missing in a FOR statement. The syntax for a FOR statement must be:

     FOR variable = numeric TO numeric

The numeric expressions must be separated by "TO".

     510 Expected STEP in FOR statement

The STEP option of the FOR statement sets the increment at which the counter variable is increased or decreased. It is the only thing allowed on the line with a FOR statement after the numeric expressions. The format must be:

     FOR variable = numeric TO numeric STEP numeric expression

     511 Expecting FUNCTION or End-of-file

You may be missing a FUNCTION definition or the END MAIN command is too early in the file.

     512 Statement out of sequences

All PUBLIC, GLOBAL and EXTERNAL statements have to be appear before the MAIN section of the project file, or between functions.

     513 Statement is unreachable

A Statement in your file is unreachable because commands before it direct project control away before it is executed. For example, you have a JUMP with no way to get to commands immediately following the JUMP.

     514 Command not valid at this point

The command indicated is used inappropriately in this structure. See discussion of the structure command in question, (CASE, ELSE, IF, WHEN, etc.) in Project Processing Manual.

     515 Not in IF

You have an END IF statement in your project file that does not have a matching IF statement. A structure cannot be ended unless it has been started.

     516 Not in CASE

You have an EXIT CASE or END CASE statement without a matching CASE statement. A structure cannot be ended unless it has been started.

     517 Not in FOR

You have an EXIT, END, or CONTINUE FOR statement without a matching FOR statement. A structure cannot be ended unless it has been started.

     518 Not in WHILE

You have an EXIT, END, or CONTINUE WHILE statement without a matching WHILE statement. A structure cannot be ended unless it has been started.

     519 Not in FUNCTION

You have an EXIT FUNCTION statement without a matching FUNCTION statement.

     520 Not in Main

You used an EXIT or END MAIN statement in a function.

     521 Missing End Function

Enter an END FUNCTION to match the FUNCTION statement in your project file and recompile.

     522 Missing End For

Close your FOR structure by entering the missing END FOR.

     523 Missing End While

Close your WHILE structure by entering the missing END WHILE.

     524 Missing End If

Close your IF structure by entering the missing END IF.

     525 Missing End Case

Close your CASE structure by entering the missing END CASE.

     526 Functions can not be LOCAL

Declare Functions GLOBAL, PUBLIC, or EXTERNAL, not LOCAL.

     527 Variable or function name already used

You are declaring two names that are not unique within the first 31 characters. Enter a unique variable or function name.

     528 Array dimension required

The size of an array must be included in its declaration.

     529 Invalid array dimension or parameter count

In the declaration of an array or a function, you have specified too large an array or function, or you have exceeded 25 arguments in the declaration of a function.

     530 Too many array dimensions

Arrays can only be declared up to three dimensions.

     531 Too many variables, functions, or arguments

Each project can contain 255 variables of each class and 254 functions of all classes combined. You have exceeded these limits.

     532 Expected non-array variable

A variable you declared as a variable or function is later referenced as an array. It must be referenced consistently throughout the project file.

     533 Expected array variable

A variable you declared as an array is later referenced as a variable or function. It must be referenced consistently throughout the project file.

     534 Too many entries on line

When using CLEAR, LOCK and UNLOCK statements, no more than 254 variables can be entered on one line.

     535 Undefined function

A PUBLIC or GLOBAL function was declared that was never found in the project file.

     536 Function declared external

A Function was declare EXTERNAL, but was then defined in the project file.

     537 RETURN from MAIN can have no arguments

Main Function cannot return a value.

     538 LOCAL or GLOBAL variables not usable in LOCK/UNLOCK

Only PUBLIC variables can be Locked or Unlocked.

     575 Error opening metafile (filename)

SmartWare is unable to open the metafile you have specified. The file may be in use at another station or in use in a different directory.

     576 Error reading metafile (filename)

SmartWare is unable to read the metafile you have specified. The file may have been imported incorrectly or damaged in some other way. Try generating a new metafile from the appropriate definition file or import it again.

     577 Error opening font file (filename)

SmartWare was unable to find the specified font file in the appropriate resource libraries. Check your resource library(ies) and make sure the font files are in the right place.

     578 Error reading font file (filename)

SmartWare was unable to read the specified font file in the appropriate resource libraries. Check your resource library(ies). If the font files are in there, they may have become corrupted. Use the Changes and Additions option of Install to reinstall them.

     579 Warning: Error opening (filename). Default font used.

SmartWare was unable to find a font you specified in your graph definition. A default font will be used, so text may have an unexpected appearance.

     580 Warning: Error reading (filename). Default font used.

SmartWare was unable to read a font file for a font you specified in your graph definition. A default font will be used, so text may have an unexpected appearance.

     600 Incorrect command syntax

The command format of the current command is not correct. This can occur while compiling a project file. Refer to Appendix A of Project Processing for a complete list of command formats. The message is also issued if you use Alt-X to edit a command and you enter an invalid command format.

     601 Unknown help number

Help information is not available for this item.

     602 Help information corrupted - may have to reinstall SmartWare

The files containing help information have been corrupted. Reinstall SmartWare.

     603 Error #<number>loading application or driver <filename><text>.

SmartWare has encountered a problem loading the specified application or driver. The following chart explains the conditions that generate each error number.

0 | Read or seek error on the specified file.
1 | Your static data segment size has grown too large.
2 | There has been a disk error attempting to read the specified file.
3 | Incompatible revision codes. This could occur if you have copied files from different versions of SmartWare.
4 | There is insufficient memory to load the application or driver
5 | There is insufficient memory to load the application or driver
6 | An overlay is missing. Please call Technical Support
7 | Either SmartWare is not functioning correctly or there is an incompatibility with your operating system. Please call Technical Support
8 | You have run out of protected mode selectors.
9-13 | If any of these errors are generated, contact Technical Support.

     604 Error reading menu from .AIF file

A menu cannot be read from the .AIF file, possibly due to corruption of the file or a disk error. It may be necessary to restore from backup.

     605 Unknown error (error number)

SmartWare does not recognize the number you have entered as a valid error number.

     606 Not a valid pathname

An invalid path was supplied in a filename.

     607 Invalid color number

The number you entered is not within the range of valid color numbers. Enter a valid color number.

     608 Too much locked public variable data -- some will be lost

When you go from one module to another all public variable data must be placed into an internal buffer of approximately 6,000 bytes so that memory can be defragmented. Any data not fitting into this buffer will be lost.

     609 Application not available

The module you have selected either has not been installed, or is otherwise not accessible. Verify that the files for the requested program are present. You may need to execute the Install program.

     610 Command line too long

From the menu, this error is generated if your choice of keywords and options exceeds 256 characters. For example, with the command Tools Copy, you can mark a number of files to be copied. These filenames all become part of the command line. If you select too many filenames, this error will be generated.

In the project processing compiler, this error is generated if you have a line of more than 1024 characters, or more than 50 lines connected with the continue symbol (\).

     611 Suspend not allowed at this time

In order to protect the integrity of the system, SmartWare cannot allow you to Suspend in your current situation. Severe system conflicts could result if a Suspend were allowed.

     612 Breakpoint or trace not allowed at this time

In order to protect the integrity of the system, SmartWare cannot allow you to trace in your current situation. Severe system conflicts could result if a Trace were allowed.

     613 Unable to load or open display driver

The driver you have selected with Tools Preferences Hardware cannot be opened or loaded. The file may be missing or may have been corrupted; it needs to be restored from backup or reinstalled.

This error may also occur if you try to initiate a graphics screen when running Unix character mode versions or text only hardware.

     615 Search string not found

Help information has been searched and the requested string cannot be found.

     616 Overlay load error <number> on overlay <number> <text>.

If you receive this message, an internal error has occurred when SmartWare attempted to load overlays. The following chart explains the conditions that generate each error number.

0 | Read or seek error on the specified file.
1 | Your static data segment size has grown too large.
2 | There has been a disk error attempting to read the specified file.
3 | Incompatible revision codes. This could occur if you have copied files from different versions of SmartWare.
4 | There is insufficient memory to load the application or driver
5 | There is insufficient memory to load the application or driver
6 | An overlay is missing. Please call Technical Support
7 | Either SmartWare is not functioning correctly or there is an incompatibility with your operating system. Please call Technical Support
8 | You have run out of protected mode selectors.
9-13 | If any of these errors are generated, contact Technical Support.

     617 All masks are bad, please try again.

After pressing F5, you have entered file masks the program does not understand. Use only standard DOS wild cards and be sure there is a space between each mask.

     620 Error creating new printer descriptor file.

SmartWare has been unable to write a new compiled printer descriptor (.cpd) from an earlier descriptor file (.dsc). Make sure that you have enough available disk space, and that you have write privileges to the directory.

     621 Error writing new printer descriptor file

SmartWare is unable to write out your new .cpd file. Check the path you have specified to ensure you have access rights to the directory. If the directory and path you have specified are available to you, either insufficient disk space remains to write the file, or a disk error has occurred during the internal operation involved in writing the file.

     622 DSC/LSC Compiler Editor internal error.

A fatal internal error had occurred in the Descriptor Editor or compiler. Exit the program as soon as possible.

     623 Insufficient memory to compile DSC/LSC

There is not enough available memory to allow the descriptor file to be compiled. Free up more memory and try to compile it again.

     624 DSC/LSC too many levels deep.

The descriptor file has too many nested calls to other "like" files. You must simplify the file before it can be compiled.

     625 Error opening DSC/LSC file.

The descriptor file or a like file that is referenced within it cannot be opened. Make sure all necessary files exist and have the correct path. Access may have been denied because the file is in use at another station.

     626 Invalid printer driver name.

The printer name is not one recognized by SmartWare. See the Software System Manual for a list of valid printer drivers.

     627 Unknown or invalid ID %d on line %ld.

The compiler cannot recognize the information identification number on the referenced line.

     628 Parse error at ID %d on line %ld.

The compiler cannot interpret the information on the referenced line.

     629 Storage overflow at ID %d.

Too much data was supplied for the given id#. Internal buffers have overflowed, you may have to reboot your machine.

     630 Insufficient memory to write DSC/LSC.

There is not enough available memory to write the descriptor file. Make more memory available and try again.

     631 Error adding group.

Either you are attempting to add a group at an inappropriate place, or you have already added the maximum number of groups.

     632 Error deleting group.

Either you are attempting to delete a group at an inappropriate place or you have attempted to delete the last group. There must always be at least one group on the menu.

     633 Insufficient memory to read DSC/LSC.

There is not enough memory available to read the descriptor file. Make more memory available and try again.

     634 DSC/LSC file format error.

The file you are trying to compile is not the appropriate format. The file has probably been corrupted. Try to restore it from backups or from install disks from the earlier version.

     635 Error opening DSC/LSC definition file.

SmartWare cannot find the file printer.def in the resource library. Make sure the file exists and has the correct path. Access may have been denied because file is in use at another station.

     636 Invalid data.

The data you have entered for this setting is invalid.

     637 Data error.

The data you have entered for this setting is invalid or inappropriate. Consult on-line help or the Software System Manual if you need assistance in determining an appropriate descriptor file.

     638 Must select at least %d item(s).

This setting requires that you select the minimum number of items indicated in the error message.

     639 Must select no more than %d items.

You have attempted to select too many items for this setting.

     650 Cannot modify file

The file you have specified cannot be modified because it is designated "read only" or because another user has access to it at this time.

     651 Note: No permission to save file under this name

A second user may be accessing the same file, or you may have "read-only" permission for the file. You can load the file, make changes, and view the revised version on the screen, but you cannot save it under this name.

     652 Error appending to file

SmartWare is unable to append to the specified file. The file may designated as read-only, or you might be appending to a file on a full disk.

     653 Error truncating file to zero length

During the process of maintaining ownership data on a file that is being saved in a multi-user environment, an error occurred and the save command cannot be completed. Try saving under a different name. If the current command or module has been exited, your changes will have been lost.

     654 No permission to save file under this name

In a multi-user environment, a second user may be accessing the same file. Also, some operating systems allow "read-only" permission to be granted to certain files. A file that does not have save permission can be modified in memory, but cannot be saved.

     655 Error creating file

An error was encountered while the program was attempting to create a file. This can occur if either the directory or the disk is full, or if the path or filename is invalid.

     656 Error writing file

Check the path you have specified to ensure you have access rights to the directory. If the directory and path you have specified are available to you, either insufficient disk space remains to write the file, or a disk error has occurred during the internal operation involved in writing the file.

     657 Invalid filename

You have entered an invalid filename; a maximum of 78 characters are allowed when specifying a drive and path in conjunction with a filename. Try the command again and specify a valid filename.

     658 Error opening file

This message indicates that the program could not open a file, which could occur if the file is not on the disk or the path is invalid.

     659 Invalid pathname

You have entered an invalid pathname; a maximum of 78 characters are allowed when specifying a drive and path in conjunction with a filename. Try the command again and specify a valid pathname.

     660 Error reading file

The file cannot be read, possibly due to corruption of the file or a disk error. It may be necessary to restore from backup.

     661 Unable to show all files -- showing as many as possible

This error is issued from the Tools Directory Display command if there are more than 500 files to be listed, or from a file prompting operation if there are more than 250 files to be listed. Only the first 500 (or 250) will be shown. You may need to be more selective when specifying the files to be listed.

     662 File (filename) not found

The program is unable to locate the file you have specified. Verify that the path and filename were spelled correctly, and if necessary, that the correct extension was sought.

     663 Unable to backup file, continue? (y/n)

Although Automatic Backup is set to "yes", SmartWare is unable to create a backup copy of the file. If you answer y, the file will be saved without a backup. If you answer n, the save operation will be aborted.

     664 File could not be reopened for update.

A file that was closed during editing in the Word Processor, Spreadsheet, or text editor could not be reopened when the time came to write it out. If the file is on a removable media, make sure the media is correctly in place.

     700 Font validation failed

There is probably bad data in a printer descriptor (.cpd) file. Reinstall the descriptor files.

     701 Font (font number) is not defined

You have selected a font number having no font definition. Define a font using this number, or select an existing font.

     702 No room for new fonts

SmartWare attempted to define a new font using the next available number, but could not do so without exceeding the maximum number of fonts allowed. The Database module allows 255 fonts. The Spreadsheet module allows 64 fonts. The Word Processor module allows 32 fonts.

     703 No fonts defined

There are no fonts to display in the Font Prompter.

     704 Font (font number) in use

You have attempted to delete a font that is being used. Only unused fonts (indicated by asterisks) can be deleted. Font 0 can never be deleted.

     705 Font number must be from 0 to (numeric value)

The font number you have specified does not fit within the allowable range. In the Database module, you can specify a font number from 0 through 254. In the Spreadsheet module, you can specify a number from 0 through 63; boldface and underscoring are considered font attributes. In the Word Processor module, you can specify a number from 0 through 31; boldface and underscoring are handled apart from font definitions.

     706 Size must be between (numeric value) and (numeric value)

The font size you have specified is outside the allowable range. Enter a value within the range stated in the error message.

     750 Default printer load failure

SmartWare attempted to load the ASCII_PR.PDV file because original printer initialization failed. The attempt was unsuccessful.

     751 Printer initialization failed -- loading default printer

A problem was encountered in loading your selected printer. The problem could be with the descriptor file or with the driver itself. In an effort to continue processing, SmartWare will load the default printer file.

     752 Printer driver load failed -- no printer loaded

SmartWare is unable to load the printer driver ASCII_PR.PDV. Either the file is not in the resource library, or there is not enough available memory to load it. No printer has been loaded.

     Print %s not in resource library - loading default printer.

The printer descriptor you specified on the Hardware Preferences screen could not be located in the resource library. SmartWare has attempted to load the default printer instead.

     755 Like files nested too deep

A top level descriptor file may call other printer descriptor files, called "like" files. This can occur no more than 10 times. The descriptor file exceeds the limit.

     756 No printer data file

A top level descriptor file can call other printer descriptor files, called "like" files. SmartWare is unable to open a descriptor file or a like file, or there is no like name in the descriptor file.

     757 Printer initialization failed

A problem, such as driver load failure or insufficient memory, occurred during printer initialization, resulting in a fatal error.

     758 Error loading printer descriptor information.

SmartWare is unable to load the currently selected printer descriptor. Make sure that this file is located in the appropriate resource library. If the file is in the proper place, it may have become corrupted. Use the Changes and Additions option of the Install program to reinstall the descriptor.

     770 Bad printer table

During font validation, SmartWare has encountered bad data, probably on styles in a printer descriptor (.cpd) file.

     771 Driver received bad command

A command that cannot be interpreted was issued to the print driver. You will probably need to contact Technical Support for assistance.

     772 Error rasterizing text

Numerous situations can cause this error message to be issued. There may be a problem reading the file. The amount of memory may be insufficient.

     773 No printer selected

SmartWare is unable to find any printer information at all. You will not be able to print until the situation has been corrected.

     774 Unable to rasterize graph

The graph cannot be printed due to rasterization failure. There may be bad data in the file, or insufficient memory.

     775 Insufficient memory to initialize rasterizer

There is not enough memory available to initialize the rasterizer.

     776 Graphics not supported on selected printer

The printer selected in the Tools Preferences Hardware menu cannot print graphics, e.g., a daisy wheel printer. Select an appropriate printer.

     778 Invalid paper profile.

The paper profile you have just specified is not understood by the system. You must enter a valid profile before leaving this menu. Use the F6 key to display valid options and select from them. Items appropriate for the current printer will be highlighted.

     780 Cannot set up printer.

A hardware error or internal printer error has occurred. Make sure that the printer is turned on and running properly, and that you have the proper printer descriptor file selected on the Hardware Preferences screen.

     781 Landscape mode unavailable. Continue printing in portrait mode? (y/n)

The currently selected printer does not support landscape printing. Answer Y to continue the print job in portrait mode, or N to terminate the print job.

     782 Graphics impossible with selected descriptor.

The graphics codes in the printer descriptor you have created or modified are incorrect. SmartWare cannot print graphics using this descriptor.

     783 Graphic band not contained within device window.

An internal error has occurred while trying to print graphics. Try selecting another printer descriptor and attempt to print again. This problem should be reported to Technical Support.

     784 Graphic band bigger than buffer to hold it.

An internal error has occurred while trying to print graphics. Try selecting another printer descriptor and attempt to print again. This problem should be reported to Technical Support.

     800 Error writing or closing file (filename)

Check the path you have specified to ensure you have access rights to the directory. If the directory and path you have specified are available to you, either insufficient disk space remains to write the file, or a disk error has occurred during the internal operation involved in writing the file.

     801 Value must be between (number) and (number)

This error, which is issued in several situations, indicates that the value entered is outside the range of acceptable values. Enter a value that falls between the two values displayed.

     802 Error reading file (filename) at line (line number)

The file cannot be read, possibly due to corruption of the file or a disk error. It may be necessary to restore from backup.

     803 Bad format in file (filename) at line (line number)

One of the program files has been corrupted. Reinstall the programs from the master disk.

     804 Too many open files

There are too many files open at one time. This could be caused by project file nesting that goes too deep or by too many SmartWare files open simultaneously. The number of files that can be open at one time is controlled by your CONFIG.SYS file. Refer to the Install Manual for information on changing the CONFIG.SYS file and using certain network drivers to allow more open files.

     805 Disk error

An unspecified disk error has occurred. Usually this message indicates that the disk or diskette is bad, or that there is a hardware problem.

     806 File (filename) in use at another station

This networking error informs you that you cannot access the specified file at this time. Wait for the other user to finish with the file, and then try again.

     850 Expanded memory failure

This error message generally indicates a hardware failure of your extended memory board. Exit and restart SmartWare. If this error message recurs, use the -e option when entering SmartWare to prevent use of expanded memory.

     851 Page file creation failure

This error indicates that the paging file for the virtual memory system cannot be created. This may indicate insufficient disk space, a bad paging path or someone else in a network already has a page file open in the current paging path. Try changing the paging path in Tools Preferences Global.

     852 Page file extend failure

This error indicates that the paging file for the virtual memory system could not be made larger. This may indicate insufficient disk space or other problems. You should exit the program as soon as possible.

     853 Page file read error

This error indicates that the virtual memory system has become corrupt. You should exit the program as soon as possible.

     854 Page file write error

This error indicates that the virtual memory system has become corrupt. You should exit the program as soon as possible.

     855 Page overwrite error

This error indicates that the virtual memory system has become corrupt. You should exit the program as soon as possible.

     856 Page map read/write failure

This error indicates that the virtual memory system has become corrupt. You should exit the program as soon as possible.

     900 All nodes already in use, or single user access not allowed

The maximum number of authorized workstations have accessed the system. You will not be able to enter SmartWare in multiuser mode until another user has exited. If single user access is being attempted (i.e.,no network driver has been selected), the user must have read/write permission to the REGIST.USR file. Network users need read-only access.

     901 Registration file is invalid

Your registration file may be missing or corrupt. It may be necessary to reinstall SmartWare or restore from a backup. Consult your dealer or Technical Support for assistance.

     902 Error opening/reading registration file

An error occurred with the registration file. The REGIST.USR file may be missing. Another possibility is that someone on the network is in SmartWare as a single user, i.e., without using a network driver. Everyone else is locked out of SmartWare. A third possibility is that certain Novell NET3.COM or ANET3.COM drivers, which contain an error, are being used. Contact Novell to correct the error.

     950 Wrong password

The password you entered is not correct. Remember passwords are case sensitive. Try again carefully checking spelling.

     951 Verification did not match

When you specify a password with the File Password Attach command, you are prompted to type it a second time for verification. You did not type the same characters both times, so the command failed.

     960 No screen and/or hardware driver set, aborting

You have not selected a hardware driver and/or a screen driver on the Hardware Preferences Screen accessed by the Tools Preferences Hardware command. As SmartWare cannot operate properly without these drivers, the program is aborting. Reenter SmartWare and select the necessary driver.

     961 User-defined menu keyword file format error

There is an error in the format of the file you used to define additional menu keywords. The format must be:

     Module number,menu number,menu keyword name,project file name,Autohelp

Module number must be a number 0-4. Menu number must be a number 1-16. Menu keywords must be less than 32 characters and consist only of letters, digits, $,-,/,',.,#,and _ . Project file name can include a path and must be a valid DOS filename, and Autohelp cannot exceed 80 characters.

     970 Can't alias segment (not low memory or out of selectors).

This message is generated if you use the PEEK/POKE command on extended memory. Try using the NATIVE PEEK/POKE command instead. If you are using the VIRSEG command and generate this message, you have run out of CPU descriptors.

     971 Insufficient low memory.

The LOW MEMALLOC command was not able to allocate the necessary amount of low memory.

     972 Virtual address or segment is not mapped to low memory.

You have attempted to use REALPTR or REALSEG on an extended memory address.

     973 Invalid selector length (must be 1 to 65536).

The length you specified for the VIRSEG command is invalid. It must be between 1 and 65536.

     974 Stack option invalid in protected mode.

You cannot use the STACK option of the INTERRUPT command in protected mode.

     975 Project protection error, address <address>.

The NATIVE PEEK/POKE or FARCALL command has detected an address that is invalid for the mode SmartWare is running in.

     976 Save files if necessary and exit immediately.

You have experienced a protection violation. In order to minimize damage to your files, you should save them and exit SmartWare.

     977 Insufficient or invalid chart data for this graph type.

The data block you have marked for this graph is insufficient or invalid. For specific information about the data structure needed for each graph type, see the Spreadsheet Manual.

     978 Unable to write metafile.

SmartWare Graphics in unable to write the metafile you are creating to disk. You may be out of disk space, or you may not have create permissions in the necessary directory. Check for these problems and try again.

     979 Not enough memory to draw chart.

SmartWare Graphics was not able to allocate enough memory to draw the chart you selected. Try to make more memory available to the system and try again.

     980 Axis scale min must be less than max.

The minimum value for axis scaling must be less than the maximum value. Use the Graph Define command to edit these settings.

     981 Axis scale division counts must be positive.

You have specified negative numbers for the number of major and minor axis divisions. These numbers must be positive. Use the Graph Define command to edit these settings.

     982 Only positive logarithms are allowed.

The data you marked to plot against a logarithmic axis included negative numbers or zero. Only positive logarithms are allowed.

     983 Logarithmic base must be greater than 1.

The number you specified for the logarithmic base was invalid. It must be greater than one. Use the Graph Define command to edit the Base for log scaling: setting. This setting can be found under the Scale Type: setting under the horizontal, vertical and auxiliary axis settings.

     984 Only positive percentages are allowed.

The data you have marked or referenced contains negative percentages or zero. Only positive percentages are allowed.

     990 Internal memory error (free)

A serious internal system error has occurred. Exit the program as soon as possible.


Database Command Reference

This section of on-line help, lists Database keywords (e.g., Data) in the order in which they appear on the SmartWare Database module menu. In keeping with the tree structure of the menu, options (Browse, Cross-Tab, Delete, etc.) are grouped under their keyword. Detailed usage instructions are included for each option.


Should You Use the User's Guide?

If you have some experience with a database program, we suggest that you read the user's guide, consisting of the first eight chapters of Database Manual.

If you have never used a database program, you may want to begin with the Database Tutorial, which provides basic, guided instructions on using SmartWare Database. Then read the first eight chapters of Database Manual, working through the practice exercises as you go.


Important Database Concepts

Before you begin working in SmartWare Database, there are several terms and concepts with which you should be familiar. The sections that follow contain brief discussions of these terms and concepts.

In addition, there is a section giving an overview of the basic steps in creating a new database. Step-by-step information for creating views, data-files, and tables is presented in Chapter 3 of Database Manual. Before creating a database, it is important to understand how all the pieces of the SmartWare Database relate to each other.


Database Terms Defined

A database is a collection of data organized around a specific need or purpose. In SmartWare, data is stored in data-files. A data-file is a disk file containing data organized into rows and columns. For example, a customer data-file might organize data like this:

     Acct#    Name           Address             City   ST  Zip
     100      Dave Beyers    123 A St.         Shawnee  KS 66203
     101      Mike Green     456 B St.         New York NY 10007
     102      Bob Beyers     123 A St.         Shawnee  KS 66203


Data-file Type

SmartWare uses three types of data-files:
Type | Other Name | Description
Smart4 | DB_TYPE_SW4 | Legacy SmartWare data-file.
C/S-Smart5 | DB_TYPE_SW5_CS | Client-Server data-file.
Local-Smart5 | DB_TYPE_SW5_LOC | Local version of the Client-Server data-file.

The Local-Smart5 and Smart4 data-file types behave almost identically. To use the C/S-Smart5 data-file type, a SmartWare Server must be set up. You can find the SmartWare Server in the setup program that was used to install this version of SmartWare.

Once a SmartWare Server is installed, SmartWare will prompt for the Server when creating or accessing a C/S-Smart5 data-file. There are multiple ways to specify the server:

Method | Example
Server Name (when on the same machine) | faircoms
IP Address | faircoms@127.0.0.1
Machine Name | faircoms@workpc

After SmartWare has prompted for Server, it will prompt for User ID and Password. By default, the SmartWare Server has two User ID/Password combinations listed below. For information on changing or adding User ID/Password combinations, consult the SmartWare Server Help.
User ID | Password
"" (blank) | "" (blank)
"ADMIN" | "ADMIN"

Server name and Password are case sensitive. User ID is not case sensitive.

Converting Between Data-types


Fields

All entries under a column heading are the same type of data. In other words, all entries under Acct# are account numbers, all entries under Name are customer names, and so forth. The columns represent fields in the data-file, and the column headings represent field names, which identify the fields. Thus, fields are columns designed to store specific pieces of information.


Records

Each row of data shown in the example represents a record in the data-file. A record consists of fields that describe a particular entity (in this case, a customer).


Views

A view is the screen through which you enter, see, edit, arrange, and otherwise manipulate records in your data-files.


Types of Views

Any view that you create is called a custom view. Your design can be simple or elaborate. Custom views, which have the extension .vw, can display all the fields in a data-file or only selected fields. You can also design a custom view to display fields from separate data-files.

When you create a data-file with your custom view, SmartWare also automatically creates a standard view, showing all fields in standard columnar format. Standard views have the extension .vws.


Viewing Multiple Files

Because SmartWare Database is a relational database system, you have the option of creating views that use fields from multiple data-files.


Linking Data-Files

When you create or attach multiple data-files within a custom view, you must link those data-files so that data in fields of corresponding records can be displayed simultaneously. This data thus appears as a single record, or view record.

Data-files are always linked in pairs. One file will be the "driver" file, i.e., the file that initiates a search for matching data. The other file will be the "driven" file, i.e., the file that is searched. Select, as links, fields that both data-files have in common.


Tables

A table is an area of a custom view in which multiple records from another data-file are shown in standard columnar format.


Field References

A field is identified by its name. When referring to a field, enclose the name in brackets, e.g., [address].

Refer to a field from another view by using the format [view.fieldname]. For example, [Inventry.Part#] references the field [Part#] in a view named Inventry.

Frequently in SmartWare Database, you are asked to enter a "field list." To respond, you can either type the field references, or you can select from a prompter list of available fields. If you type the references manually, use a semicolon to separate individual fields; use a vertical bar (|) to indicate a range of fields. Enclose an entire field list with brackets ([ ]).

The following examples illustrate the various ways you can specify fields in a field list:
Specification Format | Fields Selected
[Name;Address;Phone] | Fields [Name], [Address], and [Phone]
[Name|Zip] | Every field from [Name] through [Zip].
[Name;Date|Total] | The field [Name] and the fields [Date] through [Total].


Sorting Records

SmartWare Database allows two methods of sorting records: by key and by sort index. Records in order by a key are rearranged automatically when new entries are added. Records in order by a sort index are not rearranged automatically for new entries.

Keys are created from the Order Key Add command. Sorts are performed using the Order Sort commands.


Overview - Creating a Database

The following section is an overview of the basic steps necessary for creating a new database. Detailed instructions are provided in the Chapter 3 of Database Manual.


Step 1 - Create a View

The first step in creating a new database is to create a view by executing File Create. The View Definition Window, in which you define or select data-files and fields, appears.


Step 2 - Create a Data-File

Second, create a data-file by selecting the Create Data-File option from the View Definition menu.


Step 3 - Create Fields for the Data-File

The third step is to create fields for the data-file. Position the cursor anywhere on the screen where you want a field to be, and select Create Field Data-File from the View Definition menu. When you have finished defining fields (and any other items on the view), press F10.
IMPORTANT: To create a view that accesses data in an existing data-file, you follow many of the same steps. However, since you are not creating a new data-file, execute Attach Data-File (instead of Create Data-File) and Attach Field (instead of Create Field).


Creating a Table

If you want to insert a table into a view you are creating, there are four basic steps to follow. All applicable files must be active.
1. From the View Definition Window, move the cursor to a starting position in the view, and execute Create Table to define a table area. The empty structure for the table appears in the view. The table highlighter is displayed.
2. Execute Attach Data-File to attach the second data-file to the current view.
3. Execute Attach Field. Execute this command for each field to be displayed in the table. The table area automatically expands to allow for each field.
4. When you have finished attaching fields to the table and have returned to the View Definition Window by pressing F10, execute Edit Links to define a search link between the two data-files. The driver file is the original data-file attached to the view; the driven file is the file that will be searched for records to be displayed in the table. The linking fields are fields containing data both data-files have in common.

Be sure to specify that duplicate key values are allowed, in order that all appropriate records are displayed in the table. If the driven data-file does not have a key on the link field, you will be prompted for the key definition. You should allow duplicate keys, but you are free to choose the sort direction and the length of the key.


Using Database Commands

When you enter SmartWare Database, you will see the following keyword menu:

     Data  File  Order  Print  Tools  Window  Help  Remember  Quit

To execute a command, select from the keywords and the appropriate keyword options.

To cancel a command while selecting options and prompts, press either Escape or Alt-Z. To repeat execution of the previous command, press F9. To edit the format of the previous command, press Alt-X. The revised command will be executed when you press Enter.


Data Commands

The Data commands allow you to manipulate the data in your views and data-files. You can browse through records, perform cross-tabulation calculations, deactivate and reactivate records, and enter new data. You can select records based upon their contents, combine the data in two views to create a brand new view, or transfer data between two views. You can also send data to another SmartWare module.


Data options list

Data provides the following options:

Browse. Displays data in a view with each record occupying a single line and data for each field occupying a different column.

Cross-Tab. Creates a cross-tabulated summary of a view.

Delete. Toggles the record status of the current record between active and inactive status.

Enter. Allows you to enter new records at the end of the current file.

Find. Searches a field or set of fields in the current data-file for a specified data item equal to, greater than, less than, or containing a search data item.

Goto. Changes the current page, record, table, view, or window.

Query. Selects certain records for review.

Relate. Defines, executes, or undefines a relation that creates a new view from two other views.

Send. Sends data from the Database to another SmartWare module and exits to that module.

Transact. Executes a formula in a transaction definition file, causing data updates and transfers based on matching data in the linking fields between two views.

Utilities. Performs various database maintenance operations, including appending records from one view to another, changing count in a counter field, reconstructing damaged standard views or data-files, and purging deleted (inactive) records. Also provides a list of information about the current view.


Data Browse

Use Data Browse to review multiple records in a standard view format called "Browse Mode." In Browse Mode, each record occupies one line, and each field occupies a column.

In normal Browse Mode, the fields are displayed in columns as wide as the defined field width. In compressed Browse Mode, the display of fields wider than 14 characters is truncated. Pressing Alt-F4 toggles between normal and compressed Browse Modes.

The highlighter indicates the current record. You can use the Up-Arrow and Down-Arrow keys to move the highlighter to the next or previous logical record. The Home and End keys move the pointer to the first and last displayed records. Ctrl-Home moves the pointer to the first record in the logical order of the view; Ctrl-End moves to the last record in the logical order of the view.

The Right-Arrow and Left-Arrow keys move the display horizontally one field to bring more fields into view. Ctrl-Right-Arrow and Ctrl-Left-Arrow move the display horizontally one screen width. Page-Up and Page-Down move the display up and down one window height.
NOTE: If you access Browse Mode while in a view with a table area, only the first record from the table is displayed.


All, Fields, and Off

Select the Data Browse All option to turn on Browse Mode for all fields in the current view. All fields are available; SmartWare displays as many fields (and as many records) as will fit in the current window. Scroll to the right to see additional fields; scroll down to see additional records.


 Select Data Browse Fields to select only certain fields for display. You are prompted to select the fields to be shown.


 Select Data Browse Off to turn off Browse Mode for the current window. All fields become available, and the current record is redisplayed in the active view format.


Data Cross-Tab

Use Data Cross-Tab to perform summarized statistical calculations from data stored in the current view. The calculations to be performed are defined and saved in a cross-tab definition file. You can then execute the definition to output the summarized data either to a data-file or to a SmartWare text file.


Cross-Tab Keywords

Data Cross-Tab provides the following keyword options:

Create. Creates a Cross-Tab definition file that contains selection criteria and summary definitions.

Execute. Executes a Cross-Tab definition file.

Modify. Modifies an existing Cross-Tab definition file.

Remove. Deletes a Cross-Tab definition file.


Cross-Tabulation Overview

Suppose that you request a summary of telephone, travel, and postage expenses for the first three months of the year. You receive the following information:

Month | Telephone | Travel | Postage
Jan | 400 | 800 | 200
Feb | 450 | 850 | 250
Mar | 300 | 700 | 100

From this table you can see that the total telephone expense for January is 400. You can also see that the total travel expense for March is 700. In fact, by using the row and column headings you can find the appropriate value for any combination of month and expense.

Notice that the value 400 represents the sum of expenses occurring in January AND having the expense type "phone." The value 700 represents the sum of expenses occurring in March AND having the expense type "travel."

The Data Cross-Tab command provides the same sort of summarized information. To use Data Cross-Tab:
1. Create a cross-tab definition file.
2. Specify the selection conditions and the summary calculations to be performed.
3. Execute the definition file to obtain the resulting output.

For the example described in the overview, the selection conditions that specify the month are entered as "row match equations." The selection conditions that specify the type of expense are entered as "column match equations." The calculations to be performed are entered as "summary definitions."

For more information about row and column match equations, and summary definitions, see the section entitled Cross-Tabulating Data in Chapter 7 of the Database Manual.


Cross-Tab Create

Construct Cross-Tab

Creates a cross-tab definition file. After entering or selecting a name for the definition file, the Cross-Tabs Definition screen then appears.

An illustrations of a complete cross-tab definition is shown in Figure 9-2 in the Data Base Manual. Notice the two areas labeled Match Equ. The row match equations are entered below the Match Equ. label on the left. The column match equations are entered in the areas to the right of the other Match Equ. label. The calculation expressions are entered in the areas to the right of the Summary label.

The Cross-Tabs Definition screen has two modes, Command Mode and Enter Mode. Press Escape to toggle between Enter and Command Mode.

Enter Mode. Enter Mode allows you to bypass the options on the menu by simply typing expressions in the appropriate areas of the screen. Use the arrow keys to move the cursor.

You can enter match equations, titles, and summary definitions in Enter Mode. Refer to the discussion of the Edit and Summaries keywords for more information.

Press F6 to display a list of fields. Press F2 to edit an expression. Press F10 to complete the definition.
NOTE: The Options window is accessible only from Command Mode.

Command Mode. In Command Mode, the Cross-Tab Definition screen provides the following menu of options:

     Insert  Delete  Edit  Options  Summaries  Rejects  Quit

Use the arrow keys to move the cursor to any column or row of the definition screen outside the Options box. Press F10 to complete the definition.


Insert

Use the Insert keyword to insert a new blank row or column at the current cursor position on the Cross-Tab Definition Screen.


Delete

Use the Delete keyword to delete the entire row or column at the current cursor position on the Cross-Tab Definition Screen.


Edit

Use the Edit keyword to enter or edit match equations and titles. Press F10 to complete the entry.

Match Equations. A match equation is an expression describing conditions that are to be met to generate a row or column of cross-tabulated output. Row match equations control the generation of rows. Column match equations control the generation of columns. An implied AND operator exists between each row match equation and each column match equation in a definition.

A match equation can be any valid formula. Press F6 to display a prompter of available fields. After you select a field, complete the expression.

Examples:

     [Month]="Feb"
     [Type]="phone"
     [Amt]>100

Notice that text expressions require quotation marks, while numeric expressions do not. Also, be sure to enter upper and lower case characters appropriately.

Titles. Enter titles for the Row match output under Titles in the second column of the definition screen. Enter titles for the Column match output at the right of Titles. After you select Edit, type the title in the Control Area. The title will be inserted at the appropriate location when you press Enter.

To remove a title (while leaving the remainder of the definition intact), select Edit and press F8 (delete line).

To remove both the match equation and title, position the cursor in the row or column to be deleted and select Delete.


Options Window Definitions

The Cross-Tabs Options window allows you to define simple, quick cross tabulation definitions. The primary purpose of the Options window is to provide automatic "match unique data" expressions. Select the Options keyword to access the Options window of the screen.


 Once you select the Options keyword, another menu of options appears:

     Row-Automatic   Column-Automatic   Title

Row-Automatic affects the definition that appears at the right of Auto Row. Column-Automatic affects the definition that appears at the right of Auto Column, and the summary definition that appears at the right of Auto Summary. Title provides the general title for the leftmost column of any cross-tab output.


 If you select Row-Automatic or Column-Automatic, select Define to create or change the definition, or select Undefine to remove the definition.

If you enter a field name at Auto Row, the Database generates one row of output for each unique entry in the field. The generated row includes the result of every column match equation and corresponding summary definition specified on the definition screen. Rows generated by the Row-Automatic option appear after rows of output generated by manually defined row match equations.

If you specify a field name at the right of Auto Column, the Database produces an additional single column of output for every unique entry in the specified field.

The output from the Auto Summary definition appears under the columns generated by the Auto Column field specification. This output appears following any columns generated by manually defined column match equations.
NOTE: The Auto Row option and the Auto Column/Auto Summary option are equivalent to "match unique" in SmartWare 3.10 and earlier.


 The Auto Row Option. To specify a field for Auto Row, select a field from the prompter list of available fields. The Database enters the field name at the right of Auto Row in the Options area.


 To remove the current auto row field, select Options Row-Automatic Undefine.


 The Auto Column/Auto Summary Option. To specify a field for Auto Column, choose a field from the prompter list. You are then asked to choose an Auto Summary definition type from one of the summary definition types (e.g., S-Sum) listed on the menu. After you select the type, you are prompted to select the field on which the calculation is to be performed. The auto column and auto summary definitions are then inserted in the Options window.


 To remove the current auto column field and summary definition, select Options Column-Automatic Undefine.


 Column Title. Enter the title describing the first column of output (the heading to appear above the row match titles) at Title. Type the title as it is to appear in the output. The Database then enters that title for you at the right of Title in the Options area.


Summaries

Enter a summary definition above the column match equation to which it pertains. To enter the definition, select Summaries. An option list of the summary definition types is displayed.

If you select Sum, Average, Count, Variance, Standard-Deviation, Sum-Squares, Minimum, or Maximum, a prompter appears showing available fields. When you select a field, the Database enters the full summary definition (e.g., Sum[Quantity]) in the row to the right of Summary in the current column. If you select Remove, nothing is entered.
NOTE: If you edit a definition created in SmartWare 3.10, the Count option is displayed as Count[]. If you execute the cross-tab definition without editing this setting, SmartWare counts the records in the main data-file. If you edit the setting, you must then specify a field.

To remove the summary definition for a column, select Summary and select Remove.


 Valid summary definition types and their meanings are listed in Table 9-1.

Table 9-1
Summary Definition Type | Action
A-Avg | Averages information.
C-Count | Counts occurrences.
M-Max | Specifies maximum value.
N-Min | Specifies minimum value.
S-Sum | Sums information.
D-Std-Dev | Specifies standard deviation.
Q-Sum-Squares | Specifies sum of squares.
V-Variance | Specifies statistical variance.
R-Remove | Removes a summary definition.


Rejects

You can specify Rejects as a column match equation or a row match equation. This is equivalent to "match others" in SmartWare 3.10.

If you enter Rejects as a row match equation, the Database evaluates each column match equation for records that cannot be selected by the other row match equations. The result is presented in an additional row of output.

If you enter Rejects as a column match equation, the Database evaluates each row match equation for records that cannot be selected by the other column match equations. The result is presented in an additional column of output.

To enter Rejects at the current cursor position, select Rejects.
NOTE: The Database does not check Auto Rows and Auto Columns when determining if a record is a reject. All match formulas are processed first, then Rejects and then Autos.


Quit

Select the Quit keyword to leave the Cross-Tabs definition screen. You are asked whether you want to abandon the current changes. Specify y to exit without retaining the changes. Specify n to remain in the Cross-Tabs definition screen.


Cross-Tab Execute

Select Data Cross-Tab Execute to create either a SmartWare text file or a new data-file based upon a cross-tab definition. You are prompted to specify the definition file to execute.


 Select Smart if you want to create a file that can be read into another SmartWare module. Select Data-File if you want to create a new data-file containing the summarized data. You are prompted to specify a name for the output file. If you select Smart, specify a filename and an extension.


Cross-Tab Modify

Select Data Cross-Tab Modify to change a Cross-Tab definition file and the summary definition it contains.


Cross-Tab Remove

Select Data Cross-Tab Remove to delete a Cross-Tab definition file and the summary definition it contains.


Delete

Use Delete to toggle the current record(s) between active and inactive status. An inactive record can be withheld from data processing activity but remains physically present in the data-file.


 The two options of Delete are Record and Table-Record. When the cursor is outside a table area, always select the Record option. When the cursor is located within a table area, select Record if you want to delete all information relating to the current record, including the records in a table area. Select Table-Record if you want to delete only the record highlighted in the current table.

The Delete status of a main data-file record is indicated by the word Del in a small box in the lower right corner of the screen. Deleted table records cease to be displayed in the table area, giving the visual effect of being deleted.

NOTE: If two or more data-files are attached to a view, the extent of the deletion of a view record is controlled by the Delete status tied to main data-file setting in the Edit Links menu. If delete status is tied to the main data-file, appropriate records are deactivated (or reactivated) in both the main data-file and the driven file. If delete status is not tied to the main data-file, the record is deactivated (or reactivated) in the main data-file only.

Table 9-2 shows how the Edit Links setting works when deleting records from different types of views.

Table 9-2
View Description | Edit Links setting | Result of Data Delete Record from the main view
One data-file | none | Current record in the main data-file is deleted/activated.
Two data-files, no table | NO | Main data-file record is deleted/activated; driven data-file record is not affected.
Two data-files, no table | YES | Main data-file record is deleted/activated; driven data-file record is also deleted/activated.
Two data-files, one in a table. | NO | Main data-file record is deleted/activated; table records are not affected, but can be deleted/activated with Data Delete Table-Record, or with Ctrl-F8 in Enter/Update Mode.
Two data-files, one in a table. | YES | Main data-file record is deleted/activated; all table records pertaining to the view record are automatically deleted or activated.

Records can also be deleted by using the Replace Delete action of Data Query. Unlike the Data Delete command, Replace Delete always deletes records; it does not toggle a record's delete status between active and inactive.


Enter

Use Enter to add new records to the current view and its data-files. The Database is placed in Enter/Update Mode, and a new blank record appears in the current window. The cursor is positioned in the first field of the new record. You can begin entering new data, or if you wish, you can move backwards in the view to modify existing records.


 Use Update to change data in an existing record.
NOTE: Pressing Escape while in Command Mode invokes Enter/Update Mode, and positions the cursor on the current record, ready for modification.

If the current window is one of multiple windows on the screen, it expands to fill the Data Window Area.


 To enter the data for a record, just type information into the appropriate fields. If you prefer, you can press Alt-T to access the Field Text Editor, which works just like the Tools Text-Editor.

The following table lists additional keys that help you enter data.

Key | Action
Insert | Toggles Insert Mode ON and OFF.
Delete | Deletes the character at the current cursor position.
Backspace | Deletes the character to the left of the current cursor position.
F2 | Enters the current system date into the current field.
Alt-F2 | Enters the current system time into the current field.
F7 | Reformats a multi-line field so that a word is not broken at the end of a line.
F8 | Deletes all characters on the current line of a field.
F9 | Repeats data from the same field of the previous record.

Press Enter (or F10 if you have entered multi-line data) to move the cursor to the next field. (If Yes has been selected for the Field Definition Menu item Automatic Advance on Full Field?, the cursor automatically moves to the next field when you fill the current field to capacity.)

If your view is larger than one page/screen, the next page/screen appears as soon as the cursor leaves the last field on the current page.

If you are entering table records, press F10 after the last table entry to exit the table area.

When you finish entering new view records, move the cursor to the first available position in the next blank record and press Escape to return to Command/View Mode.

All previously entered records are saved. If you leave the cursor positioned within the last record entered, that record is not automatically saved when you press Escape. If you have entered information into the record, you are asked if you want to save changes to the current record. If you answer no, the record is not saved.

To exit Enter/Update Mode immediately, press Ctrl-Enter.


Data Find

Select Data Find to search one or more fields in the current view for a specified data item and to display the records in which the data is found. The data search item cannot exceed 80 characters.


 Select from the search field from the available fields. You can instruct SmartWare to search multiple fields by pressing F6 to create a list of fields. Pressing F7 allows you to remove a field from the list.

The F2 key toggles between Prompter mode, which allows you to point to fields to be selected, and Editor mode, which allows you to type field names (even those containing spaces) manually. Press Enter or F10 to complete the field list.
NOTE: All fields being searched must be the same type.

Comparison Options

After you finish entering the field list, the following comparison options appear:


 Equal. Search for data that exactly matches the specified search item.


 Greater-Than. Search for data that is greater than the specified search item.


 Less-Than. Searches for data that is less than the specified search item.


 Partial. Attempts to match the search item with every sequence of characters in the field. For example, "Kemp" could be entered as a search item in order to find records containing the data items "James D. Kempton" and "Kemp Photograph, Inc" in a field. The Partial option can be used only for alphanumeric or inverted fields.


Search Type Options

Next, specify the search type. A prompt appears asking you to select from the following options:

     B Backward  F Forward  G Global  I Ignore Case  W Whole Words Only

Enter one or more option letters in logical combination for the search you wish to conduct.

Table 9-4
Backward | Searches from the current record back toward the front of the data-file.
Forward | Searches from the current record forward to the end of the data-file.
Global | Searches the entire data-file from beginning to end, given current logical record order.
Ignore Case | Searches without regard to upper or lower case. For alphanumeric or inverted fields only.
Whole Words Only | Searches for whole words. For alphanumeric or inverted fields only.

If you do not enter an option, a case-sensitive search starts at the current record and proceeds toward the end of the data-file in logical record order.

When a record containing the search data is found, you are asked if you want the Database to search for the next occurrence of the search item. If so, press Y. If not, press N to return to Command/View Mode with the "found" record in the current window.

If you want to interrupt a search while it is in progress, press Ctrl-Z. To continue the search using the previous options, press Alt-R.


Binary Search

A B-tree search is much faster than a sequential search of the file. The conditions for performing such a search are as follows:
*** The search field list can consist of only one field.
** The field being searched must be a data-file field, not a view field or project processing variable.
** The field being searched must be a key field, although the view need not be in order by that key.
** If the view is not in key order, you must specify the Global search option, rather than Forward or Backward. The field must be from the view's main (driver) data-file.
** You cannot use the Ignore Case option.

If you use the Equal option, SmartWare searches for an exact match. If no match is found, SmartWare notifies you with a message.


Data Goto

Use Data Goto to change the current page, record, table, view, or window.


Goto Options

Data Goto provides the following options:

Page. Changes the page/screen that appears in the current window.

Record. Changes the record that appears in the current window.

Table. Goes to and makes current a table area in the current view.

View. Displays an active view in the current window.

Window. Changes the current window.


Goto Page

If you select Data Goto Page, you can choose between the options Next and Previous. If you select Next, the next sequential page appears in the current window. If you select Previous, the previous page appears. These options are provided for use with Project Processing. In normal operation, use Page-Down to display the next page and Page-Up to display the previous page.


Goto Record

If you select Data Goto Record, enter the number of the record that you wish to access.

With the command list version of Goto Record, you can also select Next or Previous to move forward or backward between records. Generally, as an alternative to the Data Goto command, F6 is used to display the next record and F5, the previous record.

The First and Last options of Data Goto do not appear on the screen but can be used in Project Processing.


Goto Table

If you select Data Goto Table, you are then prompted to enter a table name. When you do so, the highlighter moves into the table area and the table becomes current.


Goto View

If you select Data Goto View, you are then prompted to enter a view name. When you do so, the view becomes current.

If the highlighter is in a table area, you can select View and enter the current view name to deactivate the table and return to the view.


Goto Window

If you select Data Goto Window, enter the number of the window you want to go to. Remember that you can use Alt-F8 to display the next window and Alt-F7 to display the previous window.


Data Query

Select Data Query commands to create, execute, modify, or remove a query definition. There are three main uses for queries:
*** To select records based upon criteria that you supply and store the records either in an index or in a new data-file.
** To generate statistical information without creating any new files.
** To perform an action upon existing records without creating any new files. You can replace the contents of fields, or you can change the active/inactive status of records.

Refer to Chapter 5 of Database Manual for additional information and examples of queries.


Query Options

Data Query provides the following options:

Create. Creates a reusable query definition that is saved in a query definition file.

Execute. Creates an index of the records selected from the current view, based upon the query definition, or creates a new data-file containing the queried records. Also performs actions or statistical calculations on existing records.

Modify. Modifies a query definition file.

Now. Creates a definition and executes the query in a single command.

Remove. Deletes a query definition file.


Query Create

Construct Query

Creates a query definition and stores it in a definition file. The command list version of this command allows you to create definitions that are new or similar to other queries.


 Select New if you intend to create the query definition from scratch. Select Similar if you want to create a query definition similar to an already existing query definition. If you select Similar, a prompter showing the existing query definitions appears, and you select the query definition that you want to use.

The Query Editor then appears. It will contain no expressions if you are creating a new definition, but will display expressions from the copied definition file if you are creating a similar definition.


The Query Editor

The Query Editor, which resembles a view in Enter/Update mode, allows you to enter one or more selection criteria expressions in either of two areas of the Query Editor.

The following table lists keys that can be used within the Query Editor.

Key | Action
Escape | Quit and abandon changes.
F1 | Help.
F3 | Goes to previous field.
F4 | Goes to next field.
F6 | Displays prompter showing available fields.
F8 | Deletes information in current field.
F10 | Saves current query definition.
Alt-Q | Displays a window for entering or editing a view expression.
Alt-F2 | Clears entire query definition.
Alt-P | Prints current query definition.
Alt-T | Accesses a text editor in the Control Area.
Alt-W | Writes current query definition to a disk file in ASCII format under a name you specify.

You can enter an expression directly into a field in the Query Editor, or you can press Alt-Q to invoke the View Expression window, which is similar to the Tools Text-Editor and uses the same function keys. If you use the View Expression window, press F10 to return to the Query Editor after the expression has been entered. When the View Expression window contains an expression, the word View is displayed on the Status Line.

Query expressions can contain literal or constant data, field references, calculations, functions, logical and relational operators, and some special words and symbols.

Boolean functions, such as ISSTRING, ISBLANK, DELETED, and NOT, return either "true" or "false" and are especially useful for query definitions.

NOTE: Always put a space between the < symbol and a negative number, i.e., < -32.
Operator | Meaning
= | equals
== | equals without regard to case
! | contains
!! | does not contain
> | is greater than
>= | is greater than or equal to
< | is less than
<= | is less than or equal to
<> | does not equal

Besides selecting records, you can create query definitions that perform statistical calculations based upon data in the records. Use the File SDb functions, such as FILESUM, in the expression. Refer to Formula Reference Manual for more information on using File SDb functions.

You can also define queries that perform actions upon existing records. You can change the data in selected records, or you can change the active/inactive status of records. Entering action expressions suppresses the generation of additional files.

SmartWare allows you to use either of two types of query expressions: Query By Example (QBE) expressions or full formula expressions. QBE expressions are always entered in the fields displayed on the Query Editor. Full formula expressions typically are entered in the View Expression window, but can also be entered directly in fields on the Query Editor.


Query By Example

QBE expressions provide SmartWare with examples of data to be selected. For example, typing Smith in a [Name] field instructs SmartWare to select any records with "Smith" as the data in the [Name] field. The implied field reference is to the current field.
IMPORTANT: To search for a value that is less than a negative number, always put a space between the less-than symbol (<) and the negative number. For example, < -10 instructs SmartWare to search for values that are less than -10. If you omit the space, SmartWare interprets the expression as a replace action. In the -10 example, the values in the field will be replaced by the number 10.
NOTE: It is only necessary to enclose text in quotation marks if there is a risk that the text might be interpreted as part of a calculation. To ensure that SmartWare is able to distinguish between text and a project variable name, always use full formula expressions with project variables (e.g., [] = varname).

QBE expressions have an implied "AND" between fields. If, in the same query specifying "Smith" in the [Name] field, you also enter MO in a [State] field, you are instructing SmartWare to select records in which [Name] equals "Smith" and [State] equals "MO".

High and Low. High and Low are simple, stand-alone expressions that can be used in QBE style definitions. High selects the record in which a particular field contains the largest value. Low selects the record having the lowest value. You can also use the format High n or Low n, where n is the number of highest or lowest records to select. "Tying" records are included in the group of high or low values.

Range Operator. The range operator .. is a special relational operator, available only in QBE style definitions. Used before a value (..10) the range operator means "less than or equal to" the value. Used after a value, the operator means "greater than or equal to" the value. The expression 5..10 means greater than or equal to 5 and less than or equal to 10.

QBE Patterns. QBE patterns are wildcard strings. The asterisk (*) matches any sequence of characters. The question mark (?) matches one character.

Examples:

*g? | matches any string of data having "g" as the next to the last character.
PN?? | matches any 4-character string beginning with "PN".
r*y | matches any string beginning with "r" and ending with "y".
r**y | is legal as the equivalent of r*y.

In date strings, the asterisk matches any individual day, month, or year. In time strings, the asterisk matches any hour, minute, or second specifications. The question mark cannot be used in date or time strings.

Wildcard dates are composed of the elements that can be used in custom date formats. For example, a wildcard entry of Tuesday will select all records having "Tuesday" in the date field, even though the entry is in a format such as 05/04/1989. Legal combinations are as follows:

Wildcard | Use
dayname | to match a particular day of the week, e.g., Tuesday.
mon or month | to match a particular month, e.g., May.
yy or yyyy | to match a particular year, e.g., 89 or 1989.
d/mon | to match date and month, e.g., 4/May.
mon/yy or mon/yyyy or mm/yy | to match month and year, e.g. May/89, may/1989, or 5/89
mon/d/yy or d/mon/yy or mm/d/yy, or d/mm/yy or yy/mm/d | to match month, date, and year, according to the date format being used.

The / can be replaced by -, , or a space. The characters represented by m, d, and y can be numbers or *.

The format for wildcard time is the same as for constant time entries except for the presence of wildcard characters.

Example:

     hh
     hha  or hhp
     hh:mm  or hh:mma  or hh:mmp
     hh:mm:ss  or hh:mm:ssa  or hh:mm:ssp

The characters hh, mm, or ss can be numbers or *.
IMPORTANT: Because multiplication of date and time expressions is valid, quotation marks must enclose a date or time string that begins with an asterisk.

QBE Summary Statistics. Enter the File SDb function directly into the appropriate field. An example of a summary statistic expression that might be entered in an [Amount] field is filesum, which would return the sum of the values in the [Amount] field.

QBE Actions. Actions consist of deleting or activating records, or replacing field data. Type <-activate or <-delete to change the active/inactive status of records. To replace field data, type the symbols <- followed by the replacement value.

You can combine a QBE selection expression in the same field with a summary statistic and an action expression if you separate them with commas. For example, typing <100,<-delete,filesum in the [Amount] field would select all records in which the [Amount] field is less than 100, delete those records, and provide the total of the [Amount] fields from the records selected.


Full Formula Expressions

In contrast to QBE expressions, full formula expressions require complete formulas. In other words, you must supply both sides of an "equation." Field references must be specified where needed; the current field is not implied as with QBE expressions. Enclose text strings with quotation marks.

Examples:

     [Amount] = 100
     [Name]=="Jones"
     [Name]< "G"
     [Amount] >= 200 and [Amount] <= 800
     not(deleted)

Notice that in the example using the NOT and DELETED functions, no field reference is needed.

Full Expression Summary Statistics. Summary statistics cannot be obtained from a query definition using a full formula expression. Use a QBE style definition instead.

Full Expression Actions. The action options are replace [field] = followed by a value, replace activate, and replace delete. Do not use a comma between the selection expression and the replacement action. If you omit selection criteria, the replacement is performed on every record. Enclose text strings in quotation marks.

Examples:

     [Salesman] = "Wilson" replace [Salesman] = "Madison"
     [Salesman] = "Madison" replace activate
     [Amount] < 1 replace [Amount] = 0


Query Execute

Use Data Query Execute to perform the tasks specified in a query definition. You are prompted for the name of the definition file to execute.

With the pulldown version of Query Execute, the index is created using the name of the query definition. The command list version however, requests the index name (see below).


Index

If you select the Index option of Data Query Execute, you are prompted to enter a name for the index to be created. The Database begins the selection process, comparing the selection criteria to each record in the current view. If a record meets the criteria, the record number is stored in the index file. When all the records have been processed, the Database displays the selected records through the newly created index.

As the records are processed, the number of records searched and the total number of records in the file are displayed in the Control Area of the screen.

When the query is finished, the Query Summary box is displayed. The Query Summary box shows the number of records searched, the number of matches found, and the name of the index created.


Data-File

If you select the Data-File option of Data Query Execute, you are prompted for the name of the new data-file. Records conforming to the criteria in a specified query definition file are placed in the new data-file. You are also prompted for the fields to include.
NOTE: If one of the new data-file fields is a calculated field, only the result, not the formula, is placed into the new field.


Statistical Summary Data

If the query definition requests statistical summary information, you are asked to specify the name of the definition file to process, but the output options Index and Data-File are not provided. Instead, the query begins processing immediately. When the query is complete, the Query Summary box lists the number of records searched, the number of matches found, and the result of the statistical calculation, e.g., Count of [Customer]: 10.


Query Action Results

If the query definition requests a replacement action, you are asked to specify the name of the definition file to execute, but the output options Index and Data-File are not provided. The query action is performed upon existing records in the data-file. The query begins processing immediately and when completed, the Query Summary is shown, listing the total number of records searched, the number of matches found, and the number of replacements made.


Query Modify

Select Data Query Modify to modify an existing query definition file. Query definitions can be changed and reused; it is not necessary to create a new definition file each time, unless you want to keep a particular definition.

You are prompted for the name of the definition file to modify.


Query Now

Select Data Query Now to create a query definition, execute the query, and display the records through the new index, all in one step. Use the Now option when you want to select records quickly and you really have no need for the query definition in the future.

When you select Data Query Now, the Query Editor is displayed. You can enter expressions just as you would using Data Query Create. Press F10 to finish the definition; the Database immediately queries the current view.

SmartWare displays in the Control Area the number of records searched and the total number of records in the current view. When the query is finished, the Query Summary is shown, listing the number of records searched, the number of matches found, and the name of the index created, "qnow."
Comment: If additional index files are created, they are given the name qnowX, where X is a number.

The Database automatically retains the most recent Now query definition in qnow.dfq.


Query Remove

Select Data Query Remove to delete a query definition file. A prompter list of definition files is shown. Index files are still accessible with the Order Change Index command.


Data Relate

Use the Data Relate commands to create a new standard view and data-file by combining data from two views. The content of the new file is determined by a relationship you define between the two source files. The relationship can be drawn according to one of four relation types: Intersect, Not-Intersect, Subtract, and Union.

To define a relationship, you must be able to relate the two original views by way of "link fields." Link fields must be of the same field type. The following conditions must also be met to establish and use a relational link:
*** The two views to relate must be active.
** The link field(s) in the view you specify as View #2 must be key field(s).

In addition, if the link field of View #1 is a key field, the relation types Intersect, Not-Intersect, and Subtract will be processed more quickly.
NOTE: Relation definition links are temporary and are used only during the execution of the Data Relate Execute command.

The new view and data-file are assigned a record structure based upon the fields in one or both of the source views. The new view will be in key order. You indicate the fields to be included when you define the relation. Link fields from View #2 are automatically included in the new view.

You can specify fields in one or more table areas of View #1 as link fields, and specify fields to be included in the new view from both View #1 and View #2. If multiple table areas are specified, they are processed in reverse order of reference in the definition.


Data Relate Options

Data Relate provides the following keyword options:

Create. Creates a relate definition, saving it in a relate definition file.

Execute. Creates a new view based on a predefined relate definition.

Modify. Modifies a relate definition file.

Remove. Deletes a relate definition file.


Relate Create

Construct Relate

To use create Relate definitions, both source views must be active.


The Relate Definition Menu

The Relate Definition Menu appears. It lists the possible relate options you can specify for your new view. The following items appear in the menu. A pointer appears next to the first line:

     View 1:
     Link field(s):

     View 2:
     Link field(s):

     Relate Type: Intersect  Not-Intersect  Subtract  Union
     New Database:
     New Database Fields:

The Related Views. Enter the name of the first view next to View 1: and the name of the second view next to View 2:. You can press F6 to display a supporting menu with the names of all currently active views. Use the pointer to identify a view for selection, then press F10 or Enter to select the view.

The Link Fields. Enter the link field(s) of View #1 and View #2. Remember that each link field of View #2 must be a key field. You can press F6 to display a menu with the names of all currently active fields in the corresponding view. Use the pointer to identify a field for selection, then press F6 again to select the field. To unselect a field, press F7.

Through the selection of link fields, you can define two different types of relations: one-to-one and many-to-one. In a one-to-one relation, only one match is allowed between the data items of two link fields. In a many-to-one relation, there may be multiple matches from View #1 to a single item in View #2.

One-to-One Relations. One-to-one relations use one or more link fields. To define a one-to-one relation, you must specify the same number of link fields in each view. The first field is the primary link and each subsequent field is a secondary link. The secondary links in View #2 must be minor keys for the key field. The primary and secondary links for View #2 must have the same respective field types as those specified for View #1. Secondary links further distinguish those records that have identical data items in the primary link field. For example, you could define a social security number field as the secondary link for a name field. If your view contains several identical entries in the name field, the Database uses the social security number to differentiate the records. A match requires both identical names and social security numbers.

In the example relation, [Name] is a key field in the emp view. [SocSec] is its minor key. [Name] in the emp view corresponds to [Salesman] in the inv view. [SocSec] in the emp view corresponds to [SS#] in the inv view. For a match to occur when the relation is executed, the corresponding fields must both contain identical data.

Emp.vw |
[Name] | [SocSec]
John Brown | 112-99-3392
John Brown | 112-08-1001
Bill Smith | 408-34-7755
Bill Smith | 121-32-6789
Jim Smith | 121-99-3393
Inv.vw |
[Salesman] | [SS#]
John Brown | 112-99-3392
John Brown | 112-08-1001
Bill Smith | 511-46-4924
Bill Smythe | 143-22-6369
Jim Smith | 121-99-3393

The link fields would be specified as follows:

     View 1: inv
     Link field(s): [Salesman;SS#]

     View 2: emp
     Link field(s): [Name;SocSec]
     Relate Type:  Intersect

In our example, three matches occur as follows:

[Name] | [SocSec] | [Salesman] | [SS#]
John Brown | 112-99-3392 | John Brown | 112-99-3392
John Brown | 112-08-1001 | John Brown | 112-08-1001
Jim Smith | 121-99-3393 | Jim Smith | 121-99-3393

Many-to-One Relations. Many-to-one relationships involve one link defined for View #2 and more than one link for View #1. All links in View #1 must have the same field type as the link in View #2. The multiple links in View #1 are not secondary links but separate primary links back to the link in View #2.

Secondary links are allowed if you specify for each link in View #1 primary-secondary multiples that correspond to the primary-secondary structure of the key in View #2. For example, if you specify a primary and two secondaries for the link in View #2, you must also specify a primary and two secondary link fields for View #1.

In this sample relate definition, fields [subst1] and [subst2] of each record in material.vw are compared to field [subst] in invntory.vw. If either [subst1] or [subst2] in material.vw contains data identical to that of [subst] in invntory.vw, a match occurs. If data in both [subst1] and [subst2] of material.vw matches the record(s) in invntory.vw, a two-record match occurs.

The following example data shows the link field settings and records from the two source views.

     View 1: material
     Link field(s): [subst1;subst2]

     View 2: invntory
     Link field(s): [subst]

     View 1                View 2
     [subst1]     [subst2]        [subst]

     Wood        Wood              Wood       (Match 2 Records)
     Paper       Rock              Paper      (Match 1 Record)
     Rock        Rock              Stone      (No Match)

For an Intersect relate type, this example results in the creation of three records for the new view.

Many-to-one relations are useful when you have more than one field per record to link with your other view. A more detailed example of a many-to-one relation appears after the discussion of the remaining items on the Relate Definition Menu.

Relate Type. Select a relate type from Intersect, Not-Intersect, Subtract, and Union. Relate type determines which records are placed in the new view when the relation process is executed.

The Intersect relate type puts a record in the new view for every match between the link field(s) of the two source views.

The Not-Intersect relate type puts records in the new view for each item of link field data in View #1 that does not have matches in View #2 and each item of link field data in View #2 that does not have matches in View #1.
NOTE: Records in a view created by a Not-Intersect relation are equivalent to those in a view created by a Union relation minus those in a view created by Intersect.

The Subtract relate type creates new records for each item of link field data in View #1 for which there is no match in View #2.
NOTE: The records in a view created by a Subtract relation are equivalent to those in a view created by Not-Intersect minus the records from View #2.

The Union relate type places records in the new view:
*** for every match found between the two source views
** for every data item in the link field of View #2 not matched in View #1
** for every data item in the link field of View #1 not matched in View #2
NOTE: The records in a view created by a Union type relation are equivalent to those in a view created by Intersect plus those in a view created by Not-Intersect.

New Database. On this line of the Relate Definition Menu, enter a name for the new view.

New Database Fields. With the pointer on this line of the Relate Definition Menu, you can select the fields for your new view. Records containing data in these new fields from one or both of the source views are created in the new view, according to the conditions of the relate type. The link fields of View #2 are automatically included in the new view. Use F6 to display the available fields.

Use F3 and F4 to change the menu of fields shown in the prompter from the fields of one view to the other.

After you press F10, a second window appears underneath the relate definition. This new window contains a columnar list of the fields to be included in your new view. In the column titled New Name, assign names to the new fields by typing the names opposite the source field. Name duplications are marked by asterisks (*) at the left of the duplicate source field names. Eliminate all duplicate field names by renaming one of each set.

After you review and change the new view's field names, press F10 to complete the definition and return to Command/View Mode. Or, to return to the first relate definition screen, press Escape.


Relate Examples

As an example, assume you want to use Data Relate to combine two personnel file views into a new view titled combo. One view titled employee contains general information about the employees. The other view titled history contains data on the employees' job histories and salaries. [Name] is specified as the link field in both views.

View: employee | View: history
[name] | [name]
[adrs] | [former employer]
[city] | [former salary]
[state] | [date hired]
[zip] | [current salary]
[phone] | [dept]
[age] | [SSN]
[birthday] | [supervis]

The entry on the New Database Fields line could be [employee.adrs|zip;history.dept;SSN;supervis].

The resulting record structure would be as follows:

View: combo |
[name] | <--- link field
[adrs] | <--- (from Employee)
[city] | <--- (from Employee)
[state] | <--- (from Employee)
[zip] | <--- (from Employee)
[dept] | <--- (from History)
[SSN] | <--- (from History)
[supervis] | <--- (from History)

An Example of a Many-to-One Relation. Many-to-one relations enable you to specify more than one primary link in one of the views. In this example, suppose you are a college administrator who has a view of class listings and a view of students enrolled in those classes:

View #1: enroll

[student] [class1] [class2] [class3]
Rec.
1 Charlotte C210 L109 M101
2 Suzanne C201 M101 W105
3 Jon C100 X900 W105

View #2: class

[class no.] [class descr.]
Rec.
1 C100 Intro microcomputing
2 C201 Applied data manag.
3 C210 Word processing
4 L109 Graphics design
5 M101 Spreadsheet math
6 R151 World religions
7 W105 Western civ

You are using a many-to-one relation to compare three link fields [class1], [class2], and [class3] in the enroll view with one link field [class no.] in the class view. The new fields are to be [class descr.] from the class view and [student] from the enroll view. Specifying an intersect relation, you generate the following master class listing view:

View: clmaster

[class no.] [class descr.] [student]
Rec.
1 C210 Word processing Charlotte
2 L109 Graphics design Charlotte
3 M101 Spreadsheet math Charlotte
4 C201 Applied data manag. Suzanne
5 M101 Spreadsheet math Suzanne
6 W105 Western civ Suzanne
7 C100 Intro microcomputing Jon
8 W105 Western civ Jon

You can also specify a not-intersect relationship to list those classes for which no one signed up and those students using invalid class numbers (not found in the class view). The resulting view would appear as:

View: not_int

[class no.] [class descr.] [student]
Rec.
1 R151 World religions
2 X900 Jon


Relate Execute

This creates a new view from the fields in two source views according to the relate definition you stored in a predefined definition file. Both source views must be active when the command is executed.

After you select the definition file, the program begins the relation process. First, SmartWare creates the structure of the new data-file, based upon the specified fields in the source views. Then, data from the source views is transferred to the new data-file. When execution is complete, the new (standard) view is displayed in the current window, with a message indicating how many records it contains. The record format (fixed or variable length) is the same as that of View #2.
NOTE: If a link or a new field is a calculated field, only the result, not the formula, is placed into the new field.

If links or new data-file fields have been specified from a table, each record in the table is processed before the next view record is read. After each of these table records is read, the entire view record (i.e., the fields outside the table area plus all records in the table area) is related to the other view.

If fields from more than one table are specified, records from the last table in the view are read while the other tables remain constant. For example, assume there are two tables: Table A and Table B. The records in Table B are read and compared to the first record in Table A. After all Table B records have been read, SmartWare moves to the second record in Table A and reads all the Table B records again. This process, which continues until all records in every table are read, generates all possible record combinations.


Transact Remove

Select Data Transact Remove to delete a transact definition file. You are prompted to enter the name of the definition file to be deleted.


Relate Modify

Select Data Relate Modify to edit a relate definition file. You are prompted to specify the name of the file to modify. The Relate Definition Menu then appears, providing the same options as those provided by Data Relate Create.


Relate Remove

Select Data Relate Remove to delete a relate definition file. You are prompted to specify the name of the file to remove. Removing the definition file has no effect on the source views or the new standard view and data-file.


Data Send

Data Send moves information from the Database to another SmartWare module and exits to that module. You can send information to the Communications module, to the Spreadsheet, or to the Word Processor.


Send Options

Data Send provides two options: Data Send All and Data Send Cross-Tab.

Data Send All. Sends the data in the selected fields from all records in the current view's driver data-file to another module.

Data Send Cross-Tab. Sends the text output resulting from a cross-tab operation on the current view's data to another module.


Data Send All

Data Send All allows you to select the fields to be included in the send operation; records consisting of data in the selected fields are then sent to the module you specify.


Send All Communications

You can send Database information to SmartWare Communications for transmission to another terminal.

If you select the Data Send All Communications option, you must choose whether to send information as Data or as Text.


 Data. Selecting the Data option causes the information you are sending to be stored in a temporary file with an .iff extension. Database information stored in this format is generally used for merge printing in SmartWare Word Processor. Field information is surrounded by quotation marks. The .iff file is not loaded when the program enters SmartWare.

Once you've sent information to SmartWare Communications using the Data option, you can transmit the resulting .iff file to another SmartWare user via SmartWare Communications. The remote operator can then use the .iff file for merge printing.
IMPORTANT: The .iff file is a temporary file. Once you leave the application to which you sent your data, the .iff file is erased. If you wish to use the same data again some other time, you will have to send it again. If you anticipate having to reuse data sent from SmartWare Database, you should use File Export rather than Data Send.


 Text. When you select the Text option, the data you send to Communications is stored in a permanent file that can be transmitted at a later date. Field information is not surrounded by quotation marks as it is when you select the Data option.


 Both the Data and Text options prompt you to send data either in Row-Format or in Column Format. For examples of these formats, see the discussion under Data Send Spreadsheet or Data Send Wordprocessor Text. Next, you must select from a prompter the fields whose information you want to send. Press F6 to select each field and F10 when you are finished.


 Last, you are also prompted to specify a project filename to execute upon entering SmartWare Communications. If you do not wish to execute a project, just press Enter.


Send All Spreadsheet

If you select the Data Send All Spreadsheet option, you must select the Column-Format or Row-Format option and specify the fields whose data you want to send. Notice in the following example how data appears in the Spreadsheet window when you have selected the Row-Format option:

Name | Number | Phone
George | 234 | (913) 642-7469
Tom | 578 | (913) 642-4723

If you send those same records to the Spreadsheet using the Column-Format option, the display would appear as follows:

Name | George | Tom
Number | 234 | 578
Phone | (913) 642-7469 | (913) 642-4723


 After specifying the fields to send, you are prompted to enter a project file to execute upon entering SmartWare Spreadsheet. If you do not want to execute a project file, just press Enter. When you complete this last entry, all views and data-files are unloaded. The specified data is sent to the Spreadsheet and appears on the Spreadsheet window. If you specified a project to be executed upon entry, the project is executed.


Send All Wordprocessor

If you select Wordprocessor, you must then select either the Data or Text option.


 Data. Choose Data when you want to use your information for merge printing. If you choose the Data option, the data will be found in a file named after the original data-file, but with an .iff extension. The .iff file is not loaded when the program enters SmartWare Word Processor; however, you can immediately start a merge print.
IMPORTANT: The .iff file is a temporary file. Once you leave the application to which you sent your data, the .iff file is erased. If you wish to use the same data again some other time, you will have to send it again. If you anticipate having to reuse data sent from SmartWare Database, you should use File Export rather than Data Send.

Information sent using the Data option is surrounded by quotation marks. A data-file of two records containing the fields "Name," "Number," and "Phone" sent to SmartWare Word Processor would appear as follows if you loaded it after entering the Word Processor:

"Name" | "Number" | "Phone"
"George" | "234" | "(913) 642-7469"
"Tom" | "578" | "(913) 642-4723"


 Text. Choose Text when you want to insert data directly into a particular document. When you choose the Text option, the data you send is displayed on the screen when you reach the Word Processor. Data sent in Text format is separated by spaces.


 With the Text option, you can choose to send data in row format or in column format. For example, if you send the data-file from the previous example to SmartWare Word Processor after selecting the Row-Format option, you would see the following display when you reached the Word Processor:

Name | Number | Phone
George | 234 | (913) 642-7469
Tom | 578 | (913) 642-4723

If you send those same records to the Word Processor using the Column-Format option, the display would appear as follows:

Name | George | Tom
Number | 234 | 578
Phone | (913) 642-7469 | (913) 642-4723


 When you complete this last entry, all views and data-files are unloaded. The specified data is sent to the Word Processor, and the data you sent with the Text option appears in the Word Processor Window. If you specified a project to be executed upon arrival, the project is executed.


 After selecting Row-Format or Column-Format, you must specify the fields whose data you want to send. Finally, you are prompted to enter a project file to be executed upon entry to SmartWare Word Processor. If you do not want to execute a project, just press Enter.


Data Send Cross-Tab

Data Send Cross-Tab allows you to send the output resulting from a cross-tab operation on the current view's data to another module. Select the module from the option menu.


 If you select Data Send Cross-Tab, you are prompted to specify the name of the cross-tab definition file to be used. Use Data Cross-Tab Create to create the definition file to be executed.


Send Cross-Tab Communications

You can send cross-tabulated output to SmartWare Communications for transmission to another terminal.


 If you select Data Send Cross-Tab, you are prompted to enter a project file to execute upon entry into the Communication module. If you do not want to execute a project file, just press Enter. The cross-tab output is sent as a text file to the Communication module. If you specified a project to be executed upon entry, the project is executed.


Send Cross-Tab Spreadsheet

You can send cross-tabulated output to SmartWare Spreadsheet.


 If you select Data Send Cross-Tab, you are prompted to enter a project file to execute upon entry into the Spreadsheet module. If you do not want to execute a project file, just press Enter. The cross-tab output is sent as a text file to the Spreadsheet module. If you specified a project to be executed upon entry, the project is executed.


Send Cross-Tab Wordprocessor

You can send cross-tabulated output to SmartWare Word Processor.


 If you select Data Send Cross-Tab, you are prompted to enter a project file to execute upon entry into the Word Processor module. If you do not want to execute a project file, just press Enter. The cross-tab output is sent as a text file to the Word Processor module. If you specified a project to be executed upon entry, the project is executed.


File Send

Send moves information from the Database to the Spreadsheet or Wordprocessor module and exits to that module.

Spreadsheet

You can send data by selecting the field names from the field prompter or you can send cross-tabulated output (summarized).

If you send summarized data, select the cross-tab file from the dialog box. Use the Construct menu to create a cross-tab definition if required.

Wordprocessor

You can send data by selecting the field names from the field prompter.


Data Transact

Select Data Transact to transfer data between views based on a formula you define.

The view that initiates a transaction is called the "driver" view. The other views are called "driven" views.

The source of the data may be a single field or a formula. The field receiving data is a "destination field." A destination field can be in the driver view or the current driven view.

Creating a transaction definition requires that you specify "link fields." These are fields in the driver and driven views that cause a transaction to occur when matching data is found. The following conditions must be met in order to establish and use a transaction link:
*** The driver and driven views must be active.
** Paired link fields must have the same field type (e.g., alpha, numeric, etc.).
** The link field in the driven view must be a key field and cannot be in a table.
** A destination field can be in a table only if it is in the same table as the driver link field. A destination field can never be in a table of a driven view.

When you execute Data Transact, the Database moves to the first record in the view specified as the "driver view." It processes transactions one link group at a time. A link group is a group of consecutively defined link definitions having driver fields in the same view area (main area or table area) and each driving a different view. Link definitions are described in detail below.

The actions under a group are processed only if all links in the group have at least one match (duplicates can exist in different numbers for each link). Requiring the group to match completely ensures that all or none of a simple transaction record is processed. This allows better restarts and repeat executions.

Delete on match occurs only when one or more defined link groups match.

A table area in the driver view can be processed only if a link has been defined from the field(s) in the area. Repeating areas in driven views are not processed.
NOTE: In Novell's Transaction Tracking System, the actions defined under a group are processed as one TTS transaction.


Data Transact Options

Data Transact provides the following options:

Create. Creates a transaction definition, saving it in a transact definition file.

Execute. Executes a transaction definition.

Modify. Modifies a transaction definition.

Remove. Deletes a transact definition file and the transaction definition it contains.


Transact Create

Construct Transact

Creates a transaction definition file.


The Transact Definition Menu

The Transact Definition Menu appears. It is divided into three parts as follows: Driver Definition, Link Definition, and Action Definition.

     Driver View:                             (DRIVER DEFINITION)
     Delete Driver View record on match:  No   Yes
     Audit: None  Printer  File
     Audit File Name:

     Driver link field:                        (LINK DEFINITION)
     Driven view name:
     Driven link field:

     Destination View.Field:         (ACTION DEFINITION)
     Source (View.Field/Formula):

Use the following keyboard keys when working with the Transact Definition Menu:

Table 9-8
Key | Action
F2 | Edits text.
F3 | Blanks text.
F5 | Displays the formula editor when on a source line of the Action definition.
F6 | Displays a prompter showing fields or views.
F7 | Inserts an Action or Link group.
F8 | Removes an Action or Link group.

The driver definition items appear only once in the definition. A link definition may appear any number of times in the definition. An action definition also may appear any number of times.

As soon as you make a valid entry in any line of the last link definition, the system appends another blank link definition and action definition at the bottom of the menu. Therefore, you can define multiple link definitions.

As soon as you make a valid entry in any line of the last action definition for any link definition, the system adds a blank action definition. Therefore, you can define multiple actions for each link definition.

You can also insert a link definition or an action definition. To do this, move the arrow to the link or action definition that will follow the inserted definition and press F7. A blank definition of the same type as the definition to which the arrow points is inserted.

To remove a link or action definition, point the arrow at any line in the definition to remove and press F8. If the definition being removed is a link definition with actions defined, you are asked to verify that you want the link and actions removed. If you answer Yes, the link and action definitions are removed. If you answer No, they are not removed.

The following are true of a transaction definition:
*** Only one Driver view can be in a transaction.
** You can define any number of links.
** The Driven view specification for each link may differ, but each driven view must be active.
** You must define one or more actions under each link.
** The Destination field can be in either the driver or the driven view of the link for which the action is defined.
** The Source specification can be either a formula or a field specification. A field specification here indicates a transfer of data from that field as the action in the transaction.


Transact Driver Definition

With the pointer at the first line of the driver definition, Driver View:, specify the name of the driver view for this transaction. If you press F6, you can select a view from a prompter list of all currently active views.

On the Delete Driver View record on match: No  Yes line, you can instruct SmartWare to delete every record in the driver view for which a match is found when the transaction is executed. The deleted records are not used the next time the transaction is run. This option allows you to use only records entered since the last transaction. If a Table area is involved in a transaction, then subject to limitations set in the Edit Links menu of the File Create or File Modify commands, only the view's main file record will be deleted when a match occurs. (See Data Delete Record for information about effects on table records.)

On the Audit: None  Printer  File line, you can specify whether you want to print an audit report of processed data. You can write the report to a file or print the report. If you print to a file, you must provide a file name on the Audit File Name: line. An audit report generates information in the following format:

     Transaction Audit Report
     Definition: name.dft (where "name" is the definition file)
     Date: DD/MM/YY  Time: HH:MM:SS

A : B
J : K
C : D Key: E
F.G <H> = I

A is the name of the driver view.

B is the record number of a record in driver view A.

J is the name of a table (when one is being processed)

K is the number of a record in the table J (when a table is being processed).

C is the name of the driven view.

D is the record number of a record in the driven view C for which a match in the link field was found.

E is the data in the link field of the driver view record B.

F is the name of the view containing the field G, which is affected by action resulting from the match.

G is the name of the field which is affected by action resulting from the match.

H is the old data in the field G.

I is the new data in the field G which resulted from the action.

The following is an example of a transaction audit report:

     Transaction Audit Report
     Definition: employee.dft
     Date: 08/23/88  Time: 14:43:31

     emp_1 : 1
     emp_2 : 4                Key: Allen
     [emp_2.dept] <Finance> = Sales
     [emp_2.salary] <$17,000> = $18,300

     emp_1 : 2
     emp_2 : No Match    Key: Polk

     emp_1 : 3
     emp_2 : 2           Key: Morris
     [emp_2.dept] <Marketing> = Sales
     [Emp_2.salary] <$15,500> = $16,200

     emp_1 : 4
     emp_2 : No Match    Key: Woodrow

     ** End of Audit Report **


Transact Link Definition

On the Driver link field: line, you can specify link field(s) for the driver view. Secondary link fields are allowed. If you press F6, you can display a prompter showing the names of all currently available fields.

On the Driven view name: line, you can specify the name of a driven view for this transaction. If you press F6, you can display a prompter showing the names of all currently active views.

On the Driven link field: line, you can specify the link field for your driven view. It must be a key field. Press F6 to display a prompter showing fields from the driven view. If secondary link fields were specified, minor key fields must be specified here.

Multiple Links to a Table Area. If you define multiple links from two or more views into a table area of the driver view, save processing time by making the link definitions for them consecutive on the Transact Definition Menu. Do this because the Database processes the links in the order of their appearance on the Transact Definition Menu. In this case, the Database has to make only one pass through the records in the table area. If the link definitions are not consecutive, (i.e., if link definitions for links outside the table area are inserted between these link definitions), the Database has to make multiple passes through the table area records.


Transact Action Definition

On the Destination (View.Field): line, enter the name of the destination field for the link. Since the field can be in either the driver or the driven view, the view must be specified (e.g., Employee.Address specifies the [Address] field in the view entitled Employee). Use F6 to display a list of available fields. Use F3 and F4 to toggle the prompter's display of field names among the active views.

On the Source (View.Field/Formula): line, enter the name of the source field for a data transfer from that field, or enter a formula specifying a result for the destination field. Since a source field can be in either the driver or the driven view, the view must be specified. Use F6 to display a list of available fields.


Transact Execute

This performs a data transfer, based on the transaction in a transact definition file. The driver and all driven views must be active. You are prompted to enter the name of the transact definition file to execute.


Transact Modify

Select Data Transact Modify to edit a transact definition file. You are prompted for the name of the definition file to modify. The settings provided by the Data Transact Create command are also available when you modify an existing definition file.


Data Transact Server-Transaction

Select Data Transact Server-Transaction to create a server-side transaction with a C/S-Smart5 data-file.

A server-side transaction is a way to make changes, add, and delete records in such a way that all changes can be aborted or committed.


Data Transact Server-Transaction Options

Data Transact Server-Transaction provides the following options:


Begin

Starts a server-side transaction. All changes made to the data-file will be visible only to this server connection (this user) until the transaction is committed.


Commit

Makes all changes made since the beginning of the server-side transaction visible to all users and connections.

For example:
     Your C/S-Smart5 data-file has 3 records.
     DATA TRANSACT SERVER-TRANSACTION BEGIN "MYDB"
     LOCK-RECORD
     [A] = "CHANGE"
     WRITE-RECORD 'CHANGE CURRENT RECORD
     DATA ENTER LOCK
     [A] = "TEST2"
     WRITE-RECORD 'NOW 4 RECORDS
     DATA TRANSACT SERVER-TRANSACTION COMMIT "MYDB"

When the commit is executed, all data-file changes since the begin are applied so now all users and connections to this data-file will see the changes made by this user.


Abort

Cancels the server-side transaction and discards all changes made since the beginning of the transaction.

For example:
     Your C/S-Smart5 data-file has 3 records.
     DATA TRANSACT SERVER-TRANSACTION BEGIN "MYDB"
     LOCK-RECORD
     [A] = "CHANGE"
     WRITE-RECORD 'CHANGE CURRENT RECORD
     DATA ENTER LOCK
     [A] = "TEST2"
     WRITE-RECORD 'NOW 4 RECORDS
     DATA TRANSACT SERVER-TRANSACTION ABORT "MYDB"

When the abort is executed, all data-file changes since the begin are discarded, so the "test2" record is removed and the change made to the current record was rolled back. The data-file will only have 3 records at the end of this example.


Set-Save-Point

Sets a point such that the server-side transaction can be restored to this point.


Restore-Save-Point

Restores all data-file changes to what the data-file looked like when the set-point was set.

For example:
     Your C/S-Smart5 data-file has 3 records.
     DATA TRANSACT SERVER-TRANSACTION BEGIN "MYDB"
     DATA ENTER LOCK
     [A] = "TEST1"
     WRITE-RECORD 'NOW 4 RECORDS
     DATA TRANSACT SERVER-TRANSACTION SET-SAVE-POINT "MYDB"
     DATA ENTER LOCK
     [A] = "TEST2"
     WRITE-RECORD 'NOW 5 RECORDS
     DATA TRANSACT SERVER-TRANSACTION SET-SAVE-POINT "MYDB"
     DATA ENTER LOCK
     [A] = "TEST3"
     WRITE-RECORD 'NOW 6 RECORDS
     DATA TRANSACT SERVER-TRANSACTION RESTORE-SAVE-POINT "MYDB:2"
     'NOW THERE ARE 5 RECORDS AGAIN
     DATA TRANSACT SERVER-TRANSACTION RESTORE-SAVE-POINT "MYDB:1"
     'NOW THERE ARE 4 RECORDS AGAIN
     DATA TRANSACT SERVER-TRANSACTION COMMIT "MYDB"

When the restore-save-point is executed, the "test2" record is discarded, so at the end of this example, the data-file will contain 4 records.


Data Utilities

Use the Data Utilities commands to perform various database maintenance operations.


Data Utilities Options

Data Utilities provides the following options:

Append. Appends data from a second view to the end of the current view.

Change-Count. Sets a new count for the next record entered into a counter field or renumbers all current values in a counter field.

File-Fix. Reconstructs lost or damaged standard views or data-files.

Information. Displays the specifications for the view in the current window.

Purge. Removes all inactive records from a data-file, returning the available disk space previously occupied by those records.


Utilities Append

Use Data Utilities Append to add records from a source view to the end of a destination view. The source view must be active; the destination view must be in the current window. The views do not have to have identical structures. The Append command restructures data taken from the source to match the structure of the current view.

Data Utilities Append is often used to add records from small data entry files to a larger, master data-file. The data entry files are created from the master view by replicating its file structure.

Replicating a file structure
NOTE: You can use Data Utilities Append only with single data-file views.


 Before you execute Append, load or activate the source view, then load the destination view. When you select Append, you are prompted to specify the name of the source view, aided by a prompter.


The Append Definition Menu

The Append Definition Menu appears. It allows you to modify the way in which the source view is appended. The Append Definition Menu relates the source fields to the destination fields in a columnar format. The source field names appear in the left column and the destination names appear at the right.

When the Database creates the Append Definition Menu, it compares field names in the source and the destination views. If it finds matching field names, it assumes a corresponding transfer and lists the matching fields in adjacent columns. If it cannot find a matching source name for a field, a blank line appears in the source column opposite the unmatched destination field.

To add or change a predefined field transfer, use the pointer to identify the source field you want to modify.

If you want to insert a source field name, press F7 to display a prompter showing available fields in the source file. Then use the pointer in the prompter to identify a field name, pressing Enter or F6 to select the name for the source field column.

If you want to delete a source field name and remove the defined transfer, press F8 while the pointer is next to the source field you want deleted.

When you finish entering the append definition, data from each of the defined source fields is placed in its corresponding destination field, creating one new record for every record in the source file. The records are added to the end of the current view.


Utilities Change-Count

Use Data Utilities Change-Count to set the value of a counter field for the next new record, or to renumber all current values in the counter field of one of the current view's data-files. You are prompted to enter a new count, which must be a number from 1 to 2,000,000,000.


 Next. Select Next to set the value of the counter field for the next record entered into the data-file. This only affects records entered after the command is executed.


 Renumber. Select Renumber to set the starting value for renumbering the counter field within all records currently in the data-file, starting from the first physical record.


Utilities File-Fix

Use Data Utilities File-Fix to reconstruct lost or damaged standard views and data-files when the view displays garbled data or faulty formatting, or when the view cannot be loaded or activated because of error conditions. File-Fix, which cannot be used on active views or data-files, provides the options Data-File and View.


 Data-File. Select Data-File to recreate the PIX file for a variable-length data-file or to remove all the old versions of a variable-length data-file's updated records. Keys for the data-file are also rebuilt.

Each variable-length data-file has a PIX (physical index) file. A PIX file maintains essential information about the physical location of all variable-length records in a data-file. Each PIX file receives the same name as its associated data-file and a .pix extension.


 You are prompted to enter the name of the data-file.


 View. If you do not have a backup copy of a view, select the View option of File-Fix to rebuild the standard view attached to a given data-file.
IMPORTANT: File-Fix View rebuilds a standard view from scratch by examining the contents of the data-file. Since calculations, jump rules, colors, and other attributes are stored with the view, these features are lost if the view is restored using this method. If possible, restore a view file from backup rather than using the File-Fix View option.


 You are prompted to enter the name of the standard view to be restored.


Utilities Information

Select Data Utilities Information to display specifications for the current view and its data-files in the View Information window.

The View Information window is divided into six sections for the currently active view:
*** View
** Data-Files
** Keys on Driver Data-File
** Keys on Driven Data-Files
** Tables
** Fields

You can send the information to a printer by pressing Alt-P, or you can save the information to disk by pressing Alt-W and specifying a name for the file.
NOTE: If the view is in Browse Mode, only the fields selected to be browsed are listed in the View Information window.


View

This section provides information about the current view.

View Name. The name of the view is shown here. If the view is not in the current directory, the complete path is shown.

Date Created. This item shows the date that the current view was created.

Last Edited. This item shows the date of the most recent modification to the view definition.

Field Count. Field Count shows the number of fields present on the view.

Record Count. This item shows the number of records contained in the view's driver data-file.

Password/Encryption. Yes indicates that the view has been assigned a password and is therefore encrypted. No indicates that no password has been assigned.


Data-Files

The Data-Files section of the View Information window provides information about each attached data-file, including link definition information. The following information is presented for each data-file attached to the view.

Data-File. The name of the data-file is shown here. If the data-file does not reside in the same directory as the view, the complete path is given.

Field Count. The number of fields in the data-file is shown. Fields are included in the count, regardless of whether they are attached to the view.

Total Record Length. This item shows the combined length of all of the fields in the data-file, regardless of whether the fields are attached to the view.

Date of Last Addition. This item shows the date on which the most recent data entry activity occurred.

File Format. Fixed indicates fixed-length format. Variable indicates variable-length format.

Password. Yes indicates that a password has been assigned to the data-file. No indicates that no password has been assigned.

Encryption. Yes indicates that the data-file is encrypted. No indicates that the data-file is not encrypted.

Link. If the data-file is the main data-file or is the only data-file associated with the view, the entry for this item is DRIVER. If the data-file being described is a driven file, the link is shown in one of the following ways:

     FIELD->[Filename.FIELD_A]
     FIELD->FIELD_A

FIELD is the name of the link field in the driver file. [Filename.FIELD_A] indicates that FIELD_A, the link field from the driven file, is not on the current view; Filename is the name of the driven data-file. FIELD_A (without brackets and filename) indicates that FIELD_A is on the current view.


Keys on DRIVER Data-File

This section describes the keys from the driver file that have been defined for the current view. The categories are repeated for each major key. If no keys are defined, this section does not appear.

Major. This item shows the name, length, and data type of a field designated a major key field.

Minor. This item shows the name, length, and data type of a field designated a minor key field in a key definition.

Data-File. This item provides the name of the data-file that contains the major and minor key fields. Duplicates. Yes indicates that duplicate entries are allowed in the key. No indicates that duplicates are not allowed.


Keys on DRIVEN Data-Files

This section describes the keys from the driven files that have been defined for the current view. The categories are repeated for each major key. This section appears only when a driven file key field is present on the view.

Major. This item shows the name, length, and data type of a field designated a major key field.

Minor. This item shows the name, length, and data type of a field designated a minor key field in a key definition.

Data-File. This item provides the name of the data-file that contains the major and minor key fields.

Duplicates. Yes indicates that duplicate entries are allowed in the key. No indicates that duplicates are not allowed.


Tables

This section lists the name of each table on the current view and the name of the data-file from which each table is built.


Fields

This section provides structural information about the fields associated with the current view. The categories are repeated for each field.
NOTE: For more information regarding field attributes, refer to the discussion of the Field Definition Menu in the File Commands section of Chapter 9 of the Database Manual.

Field Number. This item shows the field's input order position.

Field Name. The name of the field being described is shown here.

Is a Major in a Key. This item indicates whether the field is a major key field.

Data-File. The name of the data-file in which the field resides is shown here.

Contained in Table. This item indicates whether the field is used in a table on the current view. If the field is used in a table, the name of the table is shown. No indicates that the field is not used in a table.

Field Type. This item tells the type of data that can be stored in the field.

Data-File Field Width. This item shows the maximum number of characters that can be entered or stored in the field.
NOTE: The storage size of a numeric field is always 8 bytes, regardless of the number of characters entered or displayed.

Screen Field Width. This item shows the maximum number of characters that the field has been designated to display on the screen.

Title Placement. Title Placement shows the location of the field name on the view: Above-Field or Left-of-Field. If the field name is not visible on the view, this item is none.

Entry Status. The settings for this item are:
*** Read/Write, which grants standard read/write permission to the field
** Read-Only, which prohibits the user from entering data into the field
** Mandatory-Entry, which requires the user to enter data into the field

Auto Adv on Full. Yes indicates that, during data entry, the cursor advances to the next field as soon as the field becomes full. No indicates that the cursor remains in the field until the user presses F10 or Enter.

Display Format. This item shows the settings used to control the display of data in the field. The settings represent (in order):
*** numeric precision
** alignment
** numeric type
** numeric options

For example, 2r$p displays a field entry with two decimal places, right alignment, and a currency symbol; negatives are denoted by parentheses. For more information, refer to the section on Field Display Format in the discussion of the Field Definition Menu in Chapter 9 of the Database Manual.

Input Mask. This item shows the settings used to control valid input into the field. The basic template for an input mask character is nMc, where n is an optional repeat-count indicator, M is the mask character, and c is an option case-modifier. A mask character represents one character position in an input stream. For more information, refer to the Input Mask section in the Field Definition Menu discussion in Chapter 9 of the Database Manual.

Data Entry Message. If a prompt or reminder message is to be displayed during data entry, the text of the message is shown here. Otherwise, this item shows none.

Default Equation. If a default equation has been defined for the field, the equation is shown here. If the field has no default equation, this item shows none.

Menu Type. Menu type can be Bar, Popup, or Data-File. If the field has no menu attached, this item shows none.
*** Menu Choices. If Menu Type is Bar or Popup, the selection entries on the menu are listed here. If Menu Type is none or Data-File, the Menu Choices item does not appear.
** Menu Returned Field. If Menu Type is Data-file, the data-file field from which data is obtained is shown. If Menu Type is not Data-File, this item is not listed.
NOTE: When a field name is enclosed in brackets, the field is a data-file field; the name of the data-file precedes the name of the field. When the field name is not enclosed in brackets, the field is on the current view and the name shown is the field name displayed on the view.
*** Menu Display Fields. If Menu Type is Data-File, the data-file fields displayed on the menu are listed here. If Menu Type is not Data-File, this item is not present. The field reference conventions described in the previous note also apply to the Menu Display Fields item.

Calculation Type. If the field has a calculation attached, the type of calculation is shown here. Calculation types are: Immediate, Wait, and Manual. If no calculation is attached to the field, this item is none.
*** Calculation Equation. The expression defining the calculation to be performed is shown here. If Calculation Type is none, this item is not listed.

Rules. Yes indicates that the field has one or more rules attached. Rule Type, Rule Equation, and Color/To/Msg categories are repeated for each rule. No indicates that no rule is attached.
*** Rule Type. A rule can be one of three types: Color, Error Check, or Jump. If the Rules item is No, this item is not listed.
** Rule Equation. The rule equation expression is shown here. If the Rules item is No, this item is not listed.
** Color/To/Msg. If the Rule Type is Color, this item shows the pair of numbers representing foreground and background colors to be used. If the Rule Type is Error Check, this item shows the message to be displayed. If the Rule Type is Jump, this item shows the destination field. If the Rule item is No, this item is not listed.


Utilities Purge

Use Data Utilities Purge to remove all inactive records from a data-file, making available the disk space previously occupied by those records. (Records can be deactivated by executing Data Delete.) You are prompted to enter the name of the data-file (which cannot be active) to be purged. Since Purge rewrites the entire data-file, you are warned All records marked for deletion will be made irrecoverable. Continue? (y/n). If you answer y, the command executes. If you answer n, no records are purged.

Data Delete


Utilities Recalc-All

Use Data Utilities Recalc-All to update all calculations in a view. (In a table, only the first record is recalculated.) This command can be useful if you add a new calculation to a view and want to quickly and easily update all records. Records are recalculated in the current view order. This means that if the view is currently in index order, only records in the index will be recalculated.


File Commands

File commands allow you to create, modify and manipulate views, data-files, fields and their structures.


File options list

File provides the following keyword options:

Load. Reads a view and its associated data-files from the disk into memory, displaying the view in the current window on the screen.

Create. Creates new views, data-files, fields, etc.

Modify. Edits an existing view and its associated data structures.

Save. Saves the current view's data-files to disk.

Unload. Removes one or all active views and their associated data-files from memory.

Activate. Reads a view and its associated data-files into memory.

Display-Active. Displays the names of all views and data-files currently active.

Import. Reads data into the current data-file from a disk file using one of five available disk file formats.

Export. Writes data from the current data-file into a disk file using one of six available file formats.

Password. Attaches or removes password protection to/from a view or its associated data-files.


File Load

File Open

Select File Load, or File Open in pulldown menus to read a view and its associated data-files from the disk into memory, displaying the view in the current window. If a view is in the current window when you load a second view, the first view is not unloaded, but remains active in background memory. There are two load options: Custom-View and Standard-View.


 Custom-View. Select Custom-View to load a view specially designed by you or another user.


 Standard-View. Select Standard-View to load a view automatically created by SmartWare for a particular data-file.


 Select or enter the filename of the view you want to load.

Loading a File Exclusively

When using SmartWare Database with a network driver, you can load files exclusively. This prevents any other user from loading the file as long as you hold it exclusively.

The command to load a view exclusive is:

File Load Custom-View "viewname" exclusive

Exclusive load is also available for standard views. If someone else is currently using any of the data-files attached to the view, an error message will be generated, and you will not be able to load the file. To load exclusive from the command: Press ALT-X; clear the last command from the line by pressing F8; and enter the load command in the format shown above.

Loading a file exclusive will make all key buffers available to you on that file for operations such as Browsing, Finds or Updates, thereby improving performance.


File Create

File Create, which establishes a new view, is the command to use as the first step in creating a new database. Part of the creation process includes creating a new data-file, in which to store data entered through your view, or attaching an existing data-file to the new view. Important Database Concepts in Chapter 2 of Database Manual gives an overview of the creation process for views and data-files. If you have not already done so, please review this important discussion.


 After executing File Create, you are first prompted to enter a name for the view. Enter a name different from that of any other existing view. Then choose between the options New and Similar.


 New or Similar. Choose New to create a new view from scratch. Choose Similar to use an existing view as a template to create the new view.
NOTE: A view created from the Similar option will be identical to the existing view. The same data-files will be attached; the same fields will be key fields; calculated fields will be the same, and so forth. If you want the view to be different from the source view, you can make changes through the View Definition window.


 Custom-View or Standard-View. If you choose Similar, you must decide whether a Custom-View or a Standard-View will be used as the template. After choosing between the Custom-View and Standard-View options, a prompter appears showing the names of existing views. Select the name of the view to use as a template.


 Password or No-Password. Whether you initially selected New or Similar, you must specify whether you want password protection for the new view. If you select No-Password, no password is assigned to the view. If you specify Password, the Database will also "encrypt" the view on disk (provide an additional level of protection by making the data unreadable unless the password is entered).

You are then asked to enter up to 16 characters for your password. The Database will prompt you to enter the password a second time for verification.

When you have finished with the password option, the View Definition Window appears. The name of the view is shown next to the word View: in the lower-left corner of the screen.

Once you have defined the basic foundation of your view, you can use the View Definition Window keywords to create a data-file, define data-file fields and create items such as tables, rules, boxes and notes within your view. For more information, see the related topic The View Definition Window.

Database Preferences
Password for an Existing View
View Definition Window


File Modify

File Modify allows you to edit, add to or delete parts of an existing view.


 Custom-View or Standard-View. After selecting the File Modify command, specify whether you want to modify a Custom-view or a Standard-view. You are then prompted to specify the name of the view to be modified. You cannot modify a view that is in more than one window. After you select the view, the View Definition Window appears.

View Definition Window
IMPORTANT: SmartWare retains a copy of your file in memory until restructuring is complete. Allow enough memory for both versions.
NOTE: File Create and File Modify give you access to the same View Definition keywords discussed in the next section.

For more information about modifying a view see Modifying a View in Chapter 3 of Database Manual.


The View Definition Window

The View Definition Window is a special editor that gives you access to a unique set of View Definition commands. It permits you to create or modify one specified view and its structural definition. You can create a maximum of 1000 fields on a view. If you are creating a new view, no items appear on the view. If you are creating a Similar view, or modifying an existing view, the view you have specified appears in the Window.

The following View Definition Window keywords appear:

Attach. Attaches an existing data-file or field to the current view.

Create. Creates a new structure for the current view (a box, calculation, data-file, etc.).

Delete. Deletes a block area or a specific item from the current view.

Edit. Edits an item of the current view definition.

Input-Order. Changes the order in which users enter data into fields on the view.

Move. Moves a block area or a specific item to a different location on the current view.

Paint. Changes the colors used in selected areas of the display screen.

Replicate. Detaches the current data-file and creates a new, empty data-file. Also duplicates a field for use with the current view.
IMPORTANT: The instructions for the View Definition Window keywords are arranged alphabetically, rather than in a step-by-step sequence.

If you are creating a view, first select View Definition keywords Create Data-File to create a new data-file in which to store the data. Or select Attach Data-File to attach an existing data-file to the view.

At that point, you can select Create Field with the Data-File option to create fields for the data-file. You can also define other items for the view or edit existing items. The important thing to remember is that a data-file must be created or attached to the view before you create or attach fields or other field related items. If you need additional step-by-step information, refer to Chapter 3 of Database Manual.


Attach

The View Definition keyword Attach is used to attach an existing data-file or field to the current view. A data-file itself must be attached to a view before any of the data-file's fields can be attached.


Attach Data-File

Select the View Definition keywords Attach Data-file to attach an existing data-file to the current view. A prompter list of existing data-files in the current directory is then displayed. Move the pointer to the data-file you wish to attach to your view and press Enter, or enter the name of the data-file manually. The data-file is now attached to the view.


Attach Field

The View Definition keywords Attach Field allow you to attach fields to the view you are creating or modifying. Before attaching a field to a view, the data-file that contains it must be attached. Move the cursor to the position on the screen where you want the field to appear before executing the command.


 A prompter then appears listing the fields in the data-files attached to the view. You can type the field name manually or you can use the cursor keys to point to the field you want to select. In addition, the following keys can be used to help you select a field.
Key | Action
F2 | Toggles between Prompter and Editor mode. Either mode allows you to type a fieldname, but only Editor mode allows you to type a fieldname containing a space.
F3 | Displays fields from the previous data-file list if multiple data-files are attached.
F4 | Displays fields from the next data-file list if multiple data-files are attached.
F10 or Enter | Completes the selection of a field.

F6 and F7 are normally used for selecting and unselecting fields for a field list, which is not a valid entry for this command.

If the name of the field you specify is identical to that of a field already on the view, you are prompted to enter another name.


Attach Project-File

The View Definition keywords Attach Project-File allow you to attach a project file to the view you are creating or modifying. This project file will be automatically loaded when the view is loaded and automatically unloaded when the view is unloaded. You can use project file to define view events such as ViewLoad.

ViewLoad
ViewUnload
CurrentRecord


Create

Use the View Definition keyword Create to create a new data structure for the current view.


Create Box

By creating or editing a box on the View Definition window, you can define rectangular areas on the view. After you select the Box option, choose either the Double or Single option.


 Double or Single. The Double option draws a box using double lines; the Single option uses a single line.


 Optional Foreground Color. To give the box a foreground color, enter a number from the list of colors that appears at the bottom of the screen. You can press Enter to accept the default color. If you accept the default color, you can later change the color of the box with the Window Paint commands. If you set a color for the box with this prompt, that color cannot be painted. It can only be changed by executing File Modify and changing this setting.


 At the prompt, move the cursor vertically and horizontally to produce or resize a box or line. Use F2 to reset anchor if necessary. You can create a maximum of 3200 boxes and notes on one view.
NOTE: Boxes and lines have the lowest priority of all items on the view, allowing other items to overwrite all or part of a box or line.


Create Calculation

When you create or edit a Calculation, a prompter appears showing available fields. After you select a field, you must choose an option from among Immediate, Wait, or Manual.


 Immediate. If you select Immediate, the Database calculates the value of the field when the cursor arrives at the field. The Immediate option is selected automatically if you do not select one of the other options.


 Wait. If you select Wait, the Database performs the calculation and waits with the cursor in the calculated field until Enter is pressed.


 Same. When you edit an existing calculation (using the Edit Calculation command), an additional option, Same, is displayed with Immediate, Wait, and Manual. Selecting Same instructs SmartWare to retain the current calculation type.


Manual. If you select Manual, the Database enters the calculated value into the field when the data entry user presses Alt-F5. The user then can accept or change this entered value.

Example:

     IF DBINFO(db_recalc) <> TRUE
                THEN ASK ("Enter name")
     ELSE NOCHANGE

The Formula Editor appears allowing you to enter or edit the formula you wish to attach to this field. The result of this calculation will become the contents of your calculated field.

DBINFO Function

The Formula Editor

The Formula Editor, which is very similar to the Text Editor of the Tools commands, temporarily displaces the display of the View Definition Window.

You can reference fields in a formula by name, as in [Price] * [Quantity]. If a field has been assigned an alias, use the alias in a formula. You can also reference fields by field number ([3] * [4]) although this is strongly discouraged. You can enter a field list (e.g., [Name;Address;City;State]) by using brackets and semicolons. You can also specify a range of fields (e.g., [Name|City], meaning fields [Name] through [City]) with the brackets and the vertical bar. To reference an external field, include the view name followed by a period along with the field name (e.g., [Invoice.Cust#]).
IMPORTANT: A custom view and its standard view are closely "linked" during the initial creation process. If you create fields for both views, assign an alias to a field in the custom view, and then use the alias in a calculation, the calculation becomes invalid for the standard view, and therefore, is deleted.

Formulas can contain numbers and other expressions, arithmetic operators (+ for addition; - for subtraction; * for multiplication; / for division; ^ for exponentiation), and SmartWare functions (e.g., SUM, AVG). For more information on using formulas in SmartWare, refer to Formula Reference Manual.

Use the Cursor Movement keys to move around the Formula Editor. In addition, the keys listed in Table 9-9 can be used to facilitate creating or editing a formula.

Table 9-9
Key | Action
Delete | Deletes character at current cursor position
Backspace | Moves cursor left one character, deleting the character
Insert | Toggles Insert Mode On or Off
F1 | Access SmartWare Help
F2 | Shows list of additional function keys
F3 | Allows you to perform a search in the Formula Editor
F4 | Allows you to perform a search and replace operation in the Formula Editor
F5 | Calculates the formula and displays the result in the Control Area
F6 | Displays a list of available fields which can be selected
F7 | Inserts a line. The line contains any data currently in the delete buffer.
F8 | Deletes a line and places the line's contents into the delete buffer.
F9 | Repeats previous Find or Replace command
Alt-F2 | Clears the Formula Editor
Alt-G | Allows you to go to a specified line
Alt-F3 | Allows you to read in another file. This is particularly useful if you want to use a complex formula created in the Text Editor
Alt-I | Inserts an area of copied or deleted data
Alt-C | Copies an area of data
Alt-P | Prints the formula
Alt-D | Deletes an area of data
Ctrl-Y | Deletes a line without storing data in the delete buffer
F10 | Stores the defined calculation for the field and exits the Formula Editor
Escape | Exits the Formula Editor without saving the calculation


Create Data-File

Create Data-File allows you to create a new data-file for the current view. When you are creating a new database, select this option before you begin defining fields. You are prompted to specify a name for the data-file. Then choose whether the data-file is to be Fixed-Length or Variable-Length.


 Fixed-Length. If you select Fixed-Length, the records in your new data-file are required to be the same length. Each field in a fixed-length data-file is allocated a specific length, regardless how much data is entered into any field.


 Variable-Length. If you select Variable-Length, the records in your new data-file are not required to be any particular length. A field in a variable-length data-file is only allocated as much disk space as needed to save the data entered.
NOTE: In general, a fixed-length data-file requires more disk space while providing faster data access times. A variable-length data-file requires longer access times while increasing disk storage efficiency.


 Password or No-Password. Specify whether you want to attach a password to the data-file and, if so, whether to encrypt the data-file for further protection. The password can be up to 16 characters long.
Comment: Specify in Tools Preferences Database whether encryption should be in standard or alternate form.

When the command is completed, the new data-file is established and ready to accept any fields, field calculations, etc., that you wish to create for it using the View Definition Window.
IMPORTANT: If you create or attach more than one data-file to a view, the Database does not allow you to leave the View Definition Window until you have established links among the data-files. Establish links by executing the Edit Links command.


 Local-Smart5. Select Local-Smart5 to use the Local-Smart5 data-file type.


 C/S-Smart5. Select C/S-Smart5 to use the C/S-Smart5 data-file type.


 Smart4. Select Smart4 to use the Smart4 data-file type.


Create Field

Move the cursor to the position you want for your new field on the view before executing Create Field. After you select Create Field, you are prompted to define a name for the field. Enter a unique name that does not exceed 20 characters. Spaces can be used in a name. A prompt then appears asking you to specify whether this field will be a Data-File field, a View field, or a Project-Processing variable.

Editing a Field
Field Definition Menu
Field Display Format
Field Input Mask


 Data-File. Select Data-File if you want data entered through this field to be stored in the data-file on disk. If you are creating a new database, this is the option to use to create fields for your data-file.


 View. Select View if you do not want the field's data to be stored in the data-file on disk. For example, you may want to see the results of a calculated field when view records are displayed, but you have no need of storing the result amounts. The calculated field could be defined as a View field.


 Project-Processing. Select Project-Processing if you want to create the field as a Project Processing variable. In this case, data entered into the field is also not stored on disk but is accessible from outside the view.

After you specify Data-File, View, or Project-Processing for the field, the Field Definition Menu appears. It shows the field options you can specify for your new field.

Field Definition Menu
Field Display Format
Field Input Mask


Field Definition Menu

On the Field Definition Menu the name of the field is displayed at the top of the screen. If the field is a data-file field, the name appears in the format data-file.field (where EMP.Name specifies the [Name] field in the data-file EMP). If the field is a view field or a project variable, only the field name appears (e.g., Name).


 You are prompted to enter a name for the new data-file that will be created. Choose whether the new data-file is to have fixed-length records or variable length records. Then, specify whether the data-file is to be password protected and, if so, whether you want it encrypted. Prompts appear for you to enter the password. The command is executed when you press Enter.


Field Type

Select from one of the available field types. Two types, Inverted and Alpha, are for alphanumeric data. The remaining field types are for numeric data in various formats. The default is Alpha.

Inverted. An inverted field, which can contain any keyboard characters, is sorted by the last word in the field. For example, if "John Smith" is entered into an inverted field, "Smith" rather than "John" would be used in a sort.
NOTE: To force the sort to use a specific word rather than the last word in the field, insert a backslash (\) before the word to be used, as in "The \Smith Company".

Alpha. An alpha (or alphanumeric) field can contain any keyboard characters. A long alpha field will extend to the rightmost edge of the current window and then wrap to additional lines as necessary.
NOTE: Quotation marks (") are used as field delimiters in ASCII and SmartWare file formats. Using quotation marks in alpha fields, although valid, could cause problems in importing and exporting files.

Numeric. A numeric field can contain numbers. You can enter up to 255 characters into a numeric field, but SmartWare "rounds" the value so that it is expressed to 15 significant digits.

Counter. A counter field contains an automatically assigned sequential number for each record.

Date. A date field is a special type of numeric field. A date can be entered using alpha characters, as in August 15, 1990, or 15 August 1990. A date can also be entered using numeric characters, as in 8/15/90 or 8-15-90. Date entries are interpreted according to the Date Style setting in Tools Preferences Global. The display defaults to Date2 format unless you specify otherwise with a Field Display Format specification.

Time. A time field is a special type of numeric field. Time can be entered in either 12-hour or 24-hour format. The display is based upon the Time Format setting in Tools Preferences Global, unless you specify otherwise with a Field Display Format specification.


Field Width

For numeric fields, Field Width represents display width and the number of characters that can be entered into the field. You can specify a value from 1 to 255; however, because numeric fields cannot wrap to additional lines, the field's position in the view may dictate fewer than 255 positions.
Comment: Storage width for a numeric field is always 8 bytes, regardless of display width.

When you first create a numeric field, you enter the display width here. Be sure to allow room for additional characters, such as commas and currency symbols, that might be displayed. Later, if you decide to edit the field, you can change the display width by marking the positions on the view; you cannot, however, change the setting from this menu.

For alpha (and inverted) fields, Field Width represents storage width, i.e., the number of characters that can be stored. Alpha fields, which can wrap to additional lines, can contain several thousand characters. Inverted fields can contain up to 100 characters.

When you first create an alpha field, the value you specify for Field Width determines both storage width and display width. Later, if you choose to edit the field, you can alter the display width by marking the positions on the view. Storage width can be altered by changing the setting in the menu.
NOTE: Display width and storage width need not match for alpha fields. For example, if the display width is larger than the storage width, the highlighter marking the field in Enter Mode extends past the last point at which you can type characters.


Title Placement

Title Placement allows you to specify where the field name should be displayed in relation to the field itself.

None. Select None if you do not want the field name to appear at all.

Above-Field. Select Above-Field to position the field name over the field.

Left-of-Field. Select Left-of-Field to position the field name to the left of the field. This is the default setting.


Extended Options

If you move the pointer to Extended Field Options and select Yes, you can access an additional set of options. Otherwise, you can press F10 to complete the current selections and exit the Field Definition Menu.

The extended field options are as follows:


View Field Name

This option allows you to change the name that will be displayed on the view in place of the actual field name. For example, you may wish to name a field "Acct#" in the standard view/data-file, but you want "Account Number" to appear on the current view.
IMPORTANT: If the renamed field is used in a calculation, the calculation must be revised to reference the new name. If, during the process of creating a new data-file (i.e., before you exit the View Definition Window), you rename a field and therefore revise a calculation, you invalidate the formula in the standard view. An error message is displayed informing you that the calculation will be deleted from the standard view.

The maximum length of the new name is 20 characters. Spaces can be used.


Field Attributes

This option allows you to select an access/entry attribute for the field.

Read/Write. The initial default is Read/Write, granting standard read/write permission to your field.

Read-Only. If you select Read-Only, the content of the field is displayed but no data can be entered.

Mandatory-Entry. If you select Mandatory-Entry, the user is required to enter data into the field to complete the record.

Project-Write. A Project-Write field is Read Only to users, but is Read/Write to project processing files.


Automatic Advance

You can choose whether you want to use the "automatic advance" feature during data entry. If you select Yes, the cursor will advance to the next field as soon as the field becomes full. If you select No, which is the default setting, the cursor will remain in the field until the user presses Enter or F10.


Colors

     Title foreground, background color:  0,0
     Data foreground, background color:  0,0

With the color settings, you can change the foreground (characters) and background colors used in the display of the field name (Title) or the input data (Data) on the view. Press F6 to show a list of numbered colors at the bottom of the screen. You will first be prompted for a background color, and then a foreground color. To select a color, enter the appropriate number. If you wish to accept the default colors, press Enter.
NOTE: If you select colors on these settings, they cannot be changed by the Window Paint command. The colors can only be changed by modifying the file and changing these settings. If you accept the default colors for these settings, you can later change them temporarily with the Window Paint commands. Painted colors are only good for the current session. If you unload and then reload the view, the colors revert to those specified in the view definition.

Painting a Window


Field Display Format

You can define a display format (maximum of 100 characters) for a field. This allows you to enhance the display of data so that text, numbers, dates, times, and other types of entries are displayed properly. A list of available format characters appears when you press F6.

Specify the Field Display Format settings in the following order:

     Precision, Alignment, Type, Options.

Example:

     2r$p

Do not use spaces or commas to separate the settings. For example, 2r$p specifies a precision of two decimal places, right alignment, the use of the currency symbol, and the use of parentheses for negative values. If the user types the number 10 in the field, $10.00 will be displayed and aligned against the right side of the field. If the user enters -10, the value is displayed as ($10.00)

Precision. The Precision specification can be a number between 0 and 15 that indicates the number of places displayed right of the decimal in a number. If you enter no precision, the display precision specified at the Default numeric format: item in Tools Preferences Database is used. To display whole numbers, specify 0 (zero) as the precision.

Alignment. The Alignment setting can be one of the following:

L | Left Justification
R | Right Justification
M | Middle (Centered) Justification

These align the data within the supplied width of the field. If no alignment is specified, left justification is used. In a numeric field, if the Field Display Format causes the data to be too wide, asterisks are shown across the width of the field.

Type. Numeric fields can have one of the following Type specifications:

NOTE: Date formats must begin with an uppercase D, e.g., Dmm/dd/yy or D2.
$ | Dollars
% | Percent
E | E-Notation
H | Histogram or bar format
, | Commas (valid only when precision is specified)
Dn | Date Format, where n = 1, 2, or 3
Tn | Time, where n=1 for 12-hr. format and n=2 for 24-hr. format.
dd | Numeric Day showing two characters for single-digit days (e.g., 04)
d | Numeric Day showing one character for single-digit days (e.g., 4)
day | Text day of the week (e.g., Thursday)
mm | Numeric Month showing two characters for single-digit months (e.g., 06)
m | Numeric Month showing one character for single-digit months (e.g., 6)
mon | Text Month (3-characters)
month | Text Month (all characters)
yy | Numeric Year (2-digit)
yyyy | Numeric Year (4-digit)
D | Custom date specification followed by format for custom date (e.g., Dmm/yy).

If you enter more than one Type specification, the last (rightmost) Type specification is used.

Numeric Options. Numeric fields can have one of the following Options:

F | Fill with *
Z | Single blank space for zero
P | Parentheses around negative number
B | Negative number with cr, positive number with db
C | Negative number with cr

The P, B, and C Options specifications are applied only if you also enter an appropriate Type specification (i.e., $, %, or E).

All other data characters are treated as literals (i.e., characters like /, -, or "spaces"). If you want any of the above specifications treated literally, precede them with \.

Consider the following examples:

An entry of 32694 into a field with display format specifications Dd/m/yy would appear as 6/7/89.

An entry of 100 into a field with display format specifications 2M$F would appear as **$100.00 **.

An entry of 5 into a field with display format specification H would appear as +++++.

An entry of .1 into a field with display format specification % would appear as 10%.

An entry of -100.2 into a field with display format specifications 0P would appear as (100).


Field Input Mask

The Input Mask setting allows you to control the format and validity of data that is entered into a field. A mask character controls one position in an input stream. You can also control groups of characters by defining mask options.

You can specify an input mask string of up to 100 characters for any field; the mask should be appropriate for the field type (i.e., do not specify an alphabetic mask for a numeric field).

NOTE: Input masks are permitted on date fields, but they require special consideration. If you define an input mask for a date field, be sure the mask is compatible with the display format. For example, if the input mask is AAA ##, ####, the display format should be Dmon dd, yyyy. If the mask and the display format do not match, the mask is used during Enter Mode but is ignored during Update Mode, allowing free-form input in the field. If you do not define a mask for a date field, either alphabetic or numeric dates can be entered. The dates must be entered according to the Date Style setting on the Global Preferences Menu.

The basic template for specifying a mask character is nMc, where n is an optional repeat-count indicator, M is the mask character, and c is an optional case-modifier.

A list of mask characters and symbols is displayed when you press F6.

Repeat-count Indicators. A repeat-count indicator is an asterisk followed by a number. The number indicates how many character positions are to use the mask specification immediately following the indicator. A repeat-count indicator can precede the mask characters A, N, X, #, or a list. For example, *5A equals AAAAA.

Mask Characters. A mask character denotes the type of input data that is valid for each position in a field. A mask character can be one of the special characters described in Table 9-13. A mask character can also be a literal character, or can be comprised of a list of characters.

Table 9-13
Special Mask Character | Meaning
A | Alphabetic character only
# | Numeric character only
N | Alphanumeric character
X | Any character

Literal Characters. A literal character pre-enters a character in a particular position in a field. For example, parentheses and hyphens are commonly specified as literal characters in the input masks of fields storing telephone numbers.

To use a special mask character as a literal character instead of the mask it represents, you must place a backslash (\) in front of it. For example, if you want to use the letter A as the letter A, and not to specify an alphabetic character, you must precede it with a backslash.

Lists. A list specifies a set of characters, any of which is acceptable input for the particular character position. A list is indicated by brackets: [ ]. A range of characters can also be specified inside a list (i.e., [a-m]). The ! symbol is used to exclude a character from a list. For example, [a-t!i!m] allows lowercase a through t, except for i and m.

Case-modifiers. Valid case-modifiers are U and L; they force the input characters to uppercase or lowercase, respectively. They can only follow the mask characters A, N, X, or a list.

Options. An option controls a group of character positions, rather than a single position. An option marker { } indicates a set of input characters that, once begun, must be completed. For example, {###} requires that if data is entered in any of the three positions, data must also be entered in the other two positions.

Options can be nested, as in the following example:

     {###{##}###}
        123   45   678

If input position 1, 2, 3, 6, 7 or 8 is filled, all other positions except 4 and 5 must also be filled. Positions 4 and 5 remain optional. If 4 or 5 is filled, all eight positions must be filled.


Data Entry Message

You can specify a prompt or reminder message (maximum of 100 characters) for a field. Data entry messages are displayed during data entry.


Default Equation

You can enter a default calculation formula (maximum of 255 characters) for a field. During data entry in Enter mode, the calculation is performed and the result inserted in the field whenever the cursor moves to the field and finds it blank. The user has the option of accepting the result or entering an overriding value. In Update mode, recalculation is performed only if the user blanks the field, moves the cursor out of the field, and then moves back.

Data inserted in a field by the default calculation is not affected by the field input mask.


Create Menu

Use Create Menu to define a menu of selection items for a field on the current view. Use Edit Menu to modify an existing menu on the current view.

You can create a bar menu, a popup menu, or a data-file menu. A bar menu lists the choices at the field location on the view. A popup menu is a prompter list of items that appears when the cursor moves to the field. A data-file menu is a type of popup menu that lists data from a data-file as the selection items.

During an Enter/Update session, the user indicates the choice by moving the highlighter or pointer to the desired item on the menu and pressing Enter. The item selected from a bar or popup menu is then inserted in the field. If the item selected is from a data-file menu, the data inserted in the field is determined by the menu definition.

NOTE: When you edit a record during an Enter/Update session, SmartWare highlights or points to the currently selected entry on a bar or popup menu; on a data-file menu, the first entry is always highlighted.


 To define a menu, select Create Menu. When the prompter list of fields is displayed, select the field to which the menu is to be attached. Then select Bar, Popup, or Data-File.


 To revise a menu, select Edit Menu. When the prompter list of fields is displayed, select the field attached to the menu being edited. Then choose the type of menu you want: Same, Bar, Popup, or Data-File.


Bar

If you select Bar, a highlighted menu area is displayed next to the field name. You can press F4 to resize the area to avoid overlapping another field. Since the number of characters that can be stored is based upon field width, you may want to make the field as wide as the longest option on the menu to avoid truncation of data. You can specify a maximum of 500 characters of text. Type the selection items, separating one from the next with a space; the items themselves cannot contain a space. Press F10 to complete the definition.

NOTE: You cannot have a bar menu on a standard view; SmartWare converts the bar menu to a popup menu.


Popup

If you select Popup, the Popup Menu Editor (which is similar to the Tools Text Editor) is displayed. Enter the selection items on the Popup Menu Editor, separating one from another with a semicolon. If you prefer, you can omit the semicolons by entering one item per line. Popup items can contain spaces. The maximum number of choices on a popup menu is 64. Press F10 to complete the definition.


Create Note

You can insert a body of text onto the view or edit that text with the Note option. Notes can provide headings, instructions, reminders, or other types of information for the user.


 Move the cursor to a starting position on the view where the note is to appear. Then select Create Note. A prompt allowing you to enter an optional color appears. The available colors are displayed for you. You can press Enter to accept the default colors.
NOTE: If you accept the default colors, you can later temporarily change the colors using Window Paint. If you assign colors in the view definition, they can only be changed by modifying the file.

If you are editing the note, place the cursor on the note and execute Edit Note. You will then be prompted for your color choices.

Next, a highlighted area is displayed. This is where you will type the text of the note. To override the default area for the note, press F4. This allows you to redefine the note area without changing the anchor. When you press F10 to complete the entry, the note is automatically resized to occupy as little area as is necessary.


Create Rule

Select Create Rule to define conditions that will change the field color, generate a message or move the cursor to another field based upon data entered. You can create a maximum of 2000 rules on a field.

Edit an existing Rule by executing Edit Rule. Then specify which field's rule you wish to edit.

Once you have selected the rule field, the field name is displayed in the border area of the Rule Definition Menu. The following items appear in the menu:

     Rule Type:  Color  Error Check   Jump
     Rule Equation:
     Enter Foreground, Background Color:  0,0

Rule Type. You can select which kind of rule to define. Notice that when you move the Rule Type selection highlighter to Error-Check, the prompt on the bottom line changes to Enter the Message to Display When Equation Fails. If you move the highlighter to Jump, the prompt on the bottom line becomes Enter the name of the field to jump to:.

If you select... | You can create a conditional...
Color | change in field color.
Error-Check | message to be displayed.
Jump | jump to a specific destination field.

Rule Equation. Specify the condition for changing the field color or jumping to another field, or for displaying a message when the formula fails, by entering or editing a formula that evaluates the data entered in the current field. QBE expressions can be used in a rule equation.

It is not necessary to use the name of the current field in the formula. For example, to change the current field's color when the value entered is greater than 1000, you could enter the formula > 1000.

You can reference other fields in the formula. For example, if the field above the current field is called [Amount], you could use a formula such as > [Amount] to compare the value entered in the current field to the value in [Amount]. Press F6 for a list of available fields.

To correct the formula, type over the existing characters, or press F2 to edit. Press F3 to blank the formula.

Rule Details. The bottom line of the Rule Definition Menu allows you to specify the details of the action to be taken. If you selected Color as the Rule Type, you can change the foreground and background colors used to display data in the field. Press F6 for a list of colors. If you selected Error-Check, you can type a message that will be displayed. If you selected Jump, you can enter the name of the destination field. Press F6 for a list of available fields.

Press F10 to complete the rule definition.


Create Table

Create Table allows you to create a table area for the current view. Edit Table allows you to edit an existing Table area. This area cannot be less than four lines or greater than 19 lines. Table areas display fields in standard view format, thus allowing you to review and compare the field entries of multiple related records. You can scroll through a table if you need to see more records. You can create a maximum of 126 table areas on a view.
IMPORTANT: The records you want to display in a table must be from a data-file that is attached to the view.


Data-File

If you select Data-File, you are prompted to specify the name of the data-file containing the fields to be used on the menu.

The data-file must already be attached to the current view, but cannot be the main data-file. The data-file's standard view must be available.

If the data-file is attached to the view only for use by the menu, use Edit Links to set Process Key Links? to no for the menu data-file; it is not necessary to define linking fields.

After you specify the data-file, you are prompted to select the field or fields from which data is to be displayed on the menu.

After you specify the display fields, you are prompted to specify the field from which data is to be returned. The return field need not be one of the display fields.

After you specify the return field, define the location and size of the menu. The default size, represented by a box in the center of the screen, is based upon the fields selected to be displayed. Use the cursor movement keys to move or to resize the menu. F3 toggles between moving and resizing modes.

Press F10 or Enter to complete the definition.


Same

An additional option, Same, is listed when you select Edit Menu instead of Create Menu. Select Same when you want to change the contents of the menu without changing the menu type.

NOTE: The Same option does not invoke the prompter list of data-files for a data-file menu. To change the data-file referenced by the menu, use Create Menu Data-File to select another data-file.


 First, move the cursor to a starting position on the view. Then select Create Table from the View Definition Menu, and at the prompt, enter a name for the table. Next specify table length by moving the cursor from its anchoring position down to the bottom of your proposed table area; press Enter. The Table Definition Menu appears with the following items:

Table Titles. Specify whether you want field names displayed at the top of each column.

Table Column Separator. Specify whether you want vertical lines to separate the columns in the table.

Table Foreground, Background Color. You can enter numbers representing the foreground (characters) and background colors to be used in the table. Press F6 for a list of available colors.

Table Cursor Foreground, Background Color. You can enter numbers representing the foreground and background colors for the table cursor. Press F6 for a list of available colors.

If you have executed Edit Table, you can make changes to the size of the table, and any of the Table settings discussed above.

When you finish specifying items in the Table Definition Menu, press F10 to clear the window from the screen. The empty data structure for the new table then appears on the view, ready to accept the fields that you attach or create. The table highlighter is also displayed. Bear in mind that the commands you execute at this point directly affect the table area.

To attach a field, execute Attach Field and select the field to be attached. To create a field, execute the Create Field command and specify the name and options just as you normally would. Fields attached or created are placed in the table area to the right of the current cursor position. The table expands as you include more fields.

When you create a field for a table, you can create a data-file field, a view field, or even a project processing variable field (which could be tricky, due to the way a project variable is loaded during project execution.) When you attach a field to a table, you can only attach a data-file field since you are selecting fields from the standard view.

The following commands cannot be used while the table is active:
*** Create Box and Edit Box
** Create Note and Edit Note
** Create Table

When you have finished creating or attaching fields, field calculations, etc., within the table, press F10 to return to normal view definition. The cursor reappears on the view at a position just outside the new table.
NOTE: Only one data-file can be referenced by a table.


Create ActiveX

Select Create ActiveX to create an ActiveX control. ActiveX controls are controls that are created in an external language that can be inserted into SmartWare. ActiveX controls can be anything from a button or check box to a dialog.

You will be prompted for which ActiveX control to create. Then you will be prompted to give the ActiveX control a name. You will use this name to refer to the control through an SPL program.

ActiveX controls have properties that can be set when defining the View. You can also change most of the control properties through an SPL program. To reference an ActiveX control property in SPL, use the control name, followed by the member operator, followed by the property name.

For example (the control name is button1):
     If (button1.Visible)
        button1.Visible = False
     End If

ActiveX controls also have events that can be processed through an SPL program. An event is an SPL function that gets called automatically by the ActiveX control to let you know that something occurred. To reference an ActiveX control event in SPL, use the control name, followed an underscore, followed by the event name.

For example (the control name is button1):
     Function button1_Click()
        message "click"
     End Function

ActiveX controls also have methods that can be called. A method is simply a function that the ActiveX control will process. To reference an ActiveX control method in SPL, use the control name, followed by the member operator, followed by the method name, followed by its arguments.

For example (the control name is button1):
     button1.ShowAbout()

To get a list of available properties, events and methods for an ActiveX control, load a custom-view with an ActiveX control. Edit an SPL program, then press F6 and you will get a list of all properties, events and methods for all the ActiveX controls on your view.

You can attach an SPL project-file to be attached to the view and be automatically loaded when the view is loaded. This is a good place to interact with ActiveX controls.

Attach Project-File
Member Operator


Delete

Use the View Definition keyword Delete to delete from the current view all items within a specified area or to delete a single data structure item (i.e., field, table, etc.). Choose between the options Block and Item.


Delete Block

Select the Block option to delete one or more items in a specified area. Move the cursor from its anchoring position to outline the area to be deleted. To establish a new anchoring position, press F2. Press Enter to complete the area definition. Use caution; anything touching the box will be deleted.

If the block includes more than one item, a verification prompt appears. If any field is included in the block, you are asked if you want to delete the field(s) from the data-file or from the current view only.
NOTE: If you delete field(s) from the data-file, the Database breaks all connections to views on which the fields may have appeared.


Delete Item

If you select Delete Item, you can choose to delete a box, calculation, data-file, field, menu, note, rule, or table. Select the specific item to delete from a prompter listing.
NOTE: If you want to delete a box, a line or a text note, you must position your cursor on some part of that item before you execute Delete Item.


 Delete Item Box. If you select Box and the cursor is positioned on some part of a box on the view, that box is deleted from the view.


 Delete Item Calculation. If you select Calculation, you must specify the field containing the calculation. A prompter list showing the fields in the current view is displayed to help you. When you select the field, the associated calculation definition is deleted.


 Delete Item Data-File. Select Data-File to detach a data-file and associated fields from the current view. You can select the data-file from a prompter listing.


 Delete Item Field. If you select Field, you can specify the field to delete, aided by a prompter showing the fields attached to the current view.


 When you delete a field, you must indicate whether you want to delete the field from the view only (leaving it in the data-file) or from the data-file (which also deletes the field from the view). Deleting a field from the data-file causes the file to be restructured and could result in some data loss.
NOTE: Deleting a field from the standard view always results in the removal of the field from the data-file, regardless of which option you select. The fields available through the standard view cannot differ from the fields present in the data-file.


 Delete Item Menu. If you select Menu, specify the field containing the menu from a prompter showing the fields available in the current view. When you select a field, the Database deletes the associated menu from the current view.


 Delete Item Note. If you select Note and the cursor is positioned on some part of a note, that note is deleted from the view.


 Delete Item Rule. If you select Rule, you must specify the field containing the rule. A screen listing the rules defined for the selected field appears. Move the pointer to the rule you want to delete. Press F8 to delete the rule. You can delete more than one rule.


 Delete Item Table. If you select Table, a prompter listing tables in the current view appears. Select the table to be deleted. Delete Item Table deletes the table and the fields inside the table from the current view, but does not delete the fields from the data-file.


 Delete Item ActiveX. If you select ActiveX, a prompter listing ActiveX controls in the current view appears. Select the ActiveX control to be deleted. Delete Item ActiveX deletes the ActiveX control from the current view.


 Delete Item Project-File. If you select Project-File, the Project-File will be removed from the current view.


Edit

Select the View Definition keyword Edit to edit the data structures of the current view definition. If you want to edit a box, a line, or a text note, you must position the cursor on some part of that item before you execute Edit Box or Edit Note.

For details about the screens and prompts you can expect when editing a box, calculation, menu, or note, see the appropriate discussion under the related topic The View Definition Window.

View Definition Window
Box
Calculation
Field
Menu
Note
Rule
Table
ActiveX
Propety-Sheet


Edit Field

The Edit Field option is similar to the Create Field option, except that you can resize the width of the field with the cursor before the Field Definition Menu appears.

The display width of a numeric field can be modified by moving the cursor on the view. The display width of an alpha field can be modified by moving the cursor, and the storage width of an alpha field can be reset in the Field Width option of the Field Definition Menu.

When you edit a field, the Control Area displays the number of lines and columns currently within the marked area.

Field Definition Menu
Field Display Format
Field Input Mask


Edit Links

Edit Links allows you to create or modify the link definition between two data-files so that their corresponding records can be accessed simultaneously through one view. A view containing more than two data-files will have multiple pairs of link fields defined.

When you select Edit Links, the View Link Definition Menu appears.

Main data-file. The main data-file is the data-file associated with the custom view containing one or more "driver" fields. A driver field controls access to a record in another file by providing lookup criteria. SmartWare selects the first data-file you create or attach to the view as the main data-file, but you can change this default selection.

File-Type. You can specify the type of data-file type. If you select Calculation, an area to enter a File-type Calculation will appear.

File-Type Calculation. This option is visible only if File-type is set to Calculation. The first character should be an equal sign (=), and the following characters must be a numeric expression which evaluates to DB_TYPE_SW4 (1), DB_TYPE_SW5_LOC (2), or DB_TYPE_SW5_CS (3). See Calculating a data-file and path below for further explanation.

Server. You can specify the Server name if the data-file type is C/S-Smart5 or Calculation. If the first character is an equal sign (=), the following characters must be a text expression which evaluates to the name of a SmartWare Server. See Calculating a data-file and path below for further explanation.

User ID. You can specify the User ID if the data-file type is C/S-Smart5 or Calculation. If the first character is an equal sign (=), the following characters must be a text expression which evaluates to the name of a SmartWare Server user. See Calculating a data-file and path below for further explanation.

Password. You can specify the Password if the data-file type is C/S-Smart5 or Calculation. If the first character is an equal sign (=), the following characters must be a text expression which evaluates to the name of a SmartWare Server user's password. See Calculating a data-file and path below for further explanation.
Driven data-file. The "driven" data-file is the file to be searched for a record matching the data in the driver field.

Delete status tied to main data-file. If you select Yes for this option, the Data Delete command will affect records in both the main data-file and this driven file. If you select No, only the main data-file will be affected by Data Delete.

Process Key Links. If you select Yes, you are activating the link between two data-files. If you select No, the link is deactivated, even though linking fields have been selected. The records from the driven data-file will not appear on the view.

Field in driven data-file to link to. Enter the name of the field to be used as a link from the driven data-file. This field should correspond in content (although not necessarily in name) to the field selected as the driver field. To display a list of available fields, press F6. If the field you want to use has already been defined as a major key with minor key fields attached, you need specify only the major key field for this setting.

You can link fields with alpha data (e.g., alpha and inverted fields), but the widths of the link fields must be identical. You can also link fields with numeric data (e.g., counter, numeric, date, and time fields). You cannot link table areas to each other.

SmartWare will make this field a key field in the driven data-file.

Driver fields on view to link from. Enter the name of the field from the main data-file to be used as a link. This field must also be present on the current view. Press F6 for a list of available fields.

Substituting a data-file. The EDIT LINKS command allows you to detach a data file and attach another data file with an identical field layout. All fields remain unaffected. You may not substitute a data file that is currently being modified nor can you re-order the data-files while substituting.

Calculating a data-file and path. If the first character of the data-file is an equal sign (=), the following characters must be a text expression which evaluates to a file name without an extension. A path may also be included as part of the text expression. The intension of this feature is to allow the path to be calculated based on a public variable. This feature makes it easy to organize data files. The calculation is evaluated during when the data file is loaded and upon execution of the EDIT LINKS command.

NOTE: Use the calculated data-files with extreme caution. An error in the entered path could result in the custom view becomming unloadable and unfixable.

Press F10 to complete the definition. If a key is to be created from the driven key field, a Key Definition Menu appears. You can accept or modify the key definition just as you would using Order Key Add.
NOTE: Remember that the use of a table involves a one-to-many relationship. When defining the link field from the table's data-file (i.e., the driven file), be sure to allow duplicate key values, so that all appropriate records can be displayed in the table.

Using Keys


Edit Property-Sheet

The Edit Property-Sheet option will bring up the property sheet of the ActiveX control. Some ActiveX controls have defined their own property sheets and some have not.


 Select the option appropriate for the type of item to be moved: Box, Field, Note, Table, or ActiveX. If you select Field, Table or ActiveX, specify the name of the field, table, or ActiveX.

The item is then marked with a line or a box; use the cursor movement keys to relocate the item on the view.
Comment: If you move fields, you may want to reset the input order by selecting Input-Order from the View Definition Window.


Input-Order

Select the View Definition keyword Input-Order to change the order in which the cursor moves from field to field. The initial default order is the order in which the fields were created or attached to the current view.

When you select Input-Order, the cursor moves to the first field, according to current input order. Each field's sequence number is shown to the left of the input area line and in the Control Area.

The following menu appears at the bottom of your screen:

     F3 Prev Fld  F4 Next Fld  F6 Increment flds  Alt R Auto row  Alt O Original order

Use F3 and F4 to move from field to field. When you reach a field whose input sequence is to be changed, delete the number currently there, and type a new number in its place. The input order of other fields will be adjusted automatically when you move the cursor off the field. For example, if you specify a new input order of 1 to a field whose input order was 3, fields 1 and 2 become fields 2 and 3 in the new input order.

Use F6 to increment the current field by one. The input order of all other fields will adjust accordingly. In other words, field 1 becomes field 2, field 2 becomes field 3, and so on.

Use Alt-R to resequence the fields according to their locations on the screen (from top left to bottom right). This feature is especially helpful when you have rearranged items on the view.

Use Alt-O to return the original input order, i.e., the sequence before you selected Input-Order.

To exit without changing, press Escape. Press F10 to save the specified order and return to normal view definition.


Move

Select the View Definition keyword Move to relocate a block area or a specific data structure item (e.g., box, field, note, table, etc.) to a different place on the current view. When you select Move, you must choose either the Block or Item option.


Move Block

Move Block moves one or more items in a specified area of the view, using the cursor to identify the block and then to specify the new location for the block. The Control Area shows the number of lines and columns within the block area while you are defining the block. Any item that touches the block area will be moved.

When executed within a table, the Block option moves columns appropriate for the area specified.


Move Item

Move Item moves a specified box, field, note, or table on the current view. If you want to move a box, a line, or a textual note, position the cursor on some part of that item before you execute Move Item Box or Move Item Note.


Paint

Select the View Definition keyword Paint to change the colors of the window border, the data, graphics, titles, or the window background. The colors assigned through this option become a view's default colors, although the user can override them temporarily with the Window Paint commands.

For details about each of the options, see the discussion about the Window Paint commands.

Painting a Window


Replicate

Select the View Definition keyword Replicate to create a matching data-file or field for use with the current view. Replicate only copies structure. Use Data Utilities Append to transfer data.

Replicate provides the options Data-File and Field. If you want to replicate a field, first move the cursor to the location on the view that you want the replicated field to occupy before you execute the Replicate Field command.
NOTE: You do not have to use the Replicate Data-File command prior to using the Replicate Field command.


Replicate Data-File

When you execute the Data-File option of the View Definition keyword Replicate, the program creates an empty data-file with a record structure matching the original. If necessary, you can alter the new data-file structure before saving the view definition. Altered or not, the new data-file is attached to the current view; the original data-file is detached.

Replicating a data-file is particularly useful when you want to enter records into a small data-file instead of directly into a large master file. First, you would create a view similar to the master. Next, execute Replicate Data-file on the new view; this detaches the master data-file from the new view but creates another data-file with a structure matching the master. After you have entered records into the new data-file, execute the Data Utilities Append command to concatenate the records in the small data-file to the master. If you need to enter data into a smaller file on a regular basis, reuse the similar view each time you execute the Replicate Data-File command.


 When you select Data-File, you specify which data-file attached to the current view is to be replicated. A prompter showing the available data-files is displayed.


Replicate Field

After you move the cursor to the position on the view you want the replicated field to occupy, select Field and specify the field to be replicated, aided by a prompter showing the fields in the current view.


 After you select a field to copy, you are asked to enter a name for the new field. Then select one of the following field categories.


 Data-File. Select Data-File to create a data-file field. You are prompted for the name of the data-file.


 View. Select View if the field is to exist only on the view; a view field's data is not stored in a data-file.


 Project-Processing. Select Project-Processing to create a field that is a project processing variable.

Appending Data
Assigning and Detaching a Password on an Existing View
Database Preferences


Replicate ActiveX

After you move the cursor to the position on the view you want the replicated ActiveX control to occupy, select ActiveX and specify the control to be replicated, aided by a prompter showing the ActiveX controls in the current view.


 After you select a ActiveX control to copy, you are asked to enter a name for the new control.


File Save

File Save saves on disk changes or additions to your data (and some internal file information), without removing the view or its associated data-files from memory or from the window. If you are operating in a single user environment, you may want to execute File Save at regular intervals to keep the file as current as possible, in case of power failure or other abnormal exit condition.


File Unload

File Close

Removes one or more active views and associated files from memory. It also saves the data and additional internal file information on disk. If you are operating in a single user environment, you should unload your files when you have completed a data entry session.


 In command lists, File Unload provides the options All and View. Select All to remove all active views and their associated data-files from memory. Select View to remove a specific view and its associated data-files from memory.
NOTE: If a data-file is associated with more than one of the currently active views, it remains in memory until all of its associated views have been unloaded.

Loading a View
Activating a View
Displaying a List of Active Views


File Activate

Select File Activate to put a view in memory. If the current window is empty, the view is displayed in it. Use the Data Goto View command to bring an activated view into the current window.


 Activate provides the options Custom-View and Standard-View. Select Custom-View to place a custom view in memory. Select Standard-View to place a standard view in memory.

Unloading a View
Going to a View


File Display-Active

Select File Display-Active to list the names of all currently active views and data-files. This Index of Open Data Files includes:
*** the names of all views in memory
** the names of all data-files associated with active views
** the current order of each view. If in sequential order, "Physical" is displayed. If in key order, "Key:field" is displayed, where "field" represents the name of the key field. If in index order, the name of the index file is displayed.
** the number of records in each data-file

To return to the normal screen display, press any key.

Loading a View
Unloading a View
Activating a View
Ordering a View
Using a Query


File Import

Read a file created outside of SmartWare Database into the current data-file. Using File Import, you can read disk files in ASCII, dBase, fixed, Smart, or SmartWare 3.10 formats. You can only import into a view with one data-file.


Ascii and Smart

Select File Import Ascii to read in files stored in standard ASCII format. Select File Import Smart to read in files written out in Smart format from another SmartWare module. To use these options, you must make certain that the file you wish to import meets the format criteria listed in Chapter 8 of Database Manual under the section titled Ascii and Smart.
NOTE: To read in ASCII or Smart formats, you must have an existing data-file associated with the current view into which you can read the data.


 When you select either the Ascii or Smart format option, the Database allows you to "skip" certain fields that you do not want read from the import file. Do this by entering 0 at the position of the field in the field list you create. This capability is convenient for reading incompatible field formats.

After you enter the name of the import file to be read, a prompter of available data-file fields appears at the bottom of the screen. Use the pointer in the prompter to identify fields to receive the data from the import file. Since the fields in the import file may not have field names, import file fields are referenced by position in a record. Use F6 to attach a field to the field list and F7 to remove a field from the field list. You can also type the names of the fields, relative to import file field position, separating each pair of adjacent field names with a semicolon. Press F10 or Enter when you have finished selecting the data-file fields that will accept data from the import file fields.


Dbase

Select Dbase to import dBase II or dBase III files. Because a data record structure already exists in a dBase file, SmartWare Database defines a compatible record structure and creates corresponding data-files as the imported file is being read.
NOTE: Memo fields that exceed 5000 characters in length in dBase files are truncated to 5000 characters when read into SmartWare Database data-files.


Fixed

Select File Import Fixed to read a fixed length file.
NOTE: To read in files stored in fixed length format, you must have an existing data-file associated with the current view into which you can read the data.


 When reading in Fixed format, you cannot "skip" fields. You must read each field in sequential order. In files with fixed length fields, each field is allocated a specified length, regardless of how much data it contains. When you import fixed files, the Database uses two methods for reading field information, depending upon whether the field is alphanumeric or numeric.

If the field is alphanumeric (or inverted), the Database uses the field storage width of the destination field in the SmartWare data-file to determine how many characters to read. If the field is numeric (including date, time, or counter), the Database uses the display width of the destination field. The difference is based on the fact that the storage width for numeric fields is always 8 bytes, so if you change the display width on the view into which you are importing the fixed data, you can read more or fewer than eight characters into a numeric field.

SmartWare Database expects the length of each record in the import file to equal the length of each record in the data-file. If the record in the import file is longer than a record in the data-file, the extra characters are ignored. If the import file record is shorter than the data-file record, the Database proceeds to the next record of the import file, reading the next data item into the current field of the current data-file record.


310-Smart

Because a data record structure already exists in a SmartWare 3.10 file, SmartWare Database defines a compatible record structure and creates corresponding data-files as the imported file is being read. When you select the File Import command, you are asked to enter the filename of the file you wish to import. Next, you are prompted to enter a new name for the data-file that will be created when the file is imported.

As the file is being imported, the 3.10 keys are converted. In addition, 3.10 fields that were designed to hold Social Security numbers are converted to alphanumeric fields with a length of 11 and an input mask with the format ###-##-#### on the standard view. 3.10 phone fields are converted to alphanumeric fields with a length of 14 and an input mask in the format (###) ###-####. Calculations are imported along with their associated fields.


Local-Smart5

Select Local-Smart5 to convert to another of the SmartWare data-file types. Because a data record structure already exists in a Local-Smart5 file, SmartWare Database defines a compatible record structure and creates corresponding data-files as the imported file is being read.

Data-file Type


C/S-Smart5

Select C/S-Smart5 to convert to another of the SmartWare data-file types. Because a data record structure already exists in a C/S-Smart5 file, SmartWare Database defines a compatible record structure and creates corresponding data-files as the imported file is being read.

Data-file Type


4-Smart4

Select Smart4 to convert to another of the SmartWare data-file types. Because a data record structure already exists in a Smart4 file, SmartWare Database defines a compatible record structure and creates corresponding data-files as the imported file is being read.

Data-file Type

Exporting Information


File Export

Use File Export to write data from the current data-file into a new file using one of six available file formats. Using File Export from a command list, you can create disk files in ASCII, dBase III, DIF, SYLK, Smart, or text formats. The pulldown's dialog box provides ASCII, DIF, SYLK, Text, and dBase III formats.

The following options are available:


 Row-Format. Writes the records of the data-file along rows.


 Column-Format. Writes the records of the data-file in columns.


 You must specify the fields whose data is to be written. Use the pointer to identify an ordered list of field names from the prompter. Press F6 to select a name or F7 to unselect a name. Or type the names of the fields, in order, separating each pair of adjacent field names with a semicolon.


 Press F10 or Enter when you have finished selecting the field order. Then specify a name for the file.


Ascii

Write a file out in standard ASCII format. Each record in an ASCII file is terminated with a carriage return and a line feed. Fields in an ASCII file are separated by commas. Alphanumeric fields are surrounded by quotes, while numeric fields are not. The end of an ASCII file is marked by a ^Z (Control Z). The following is a sample record in ASCII file format:

     "text field",1000,"text field",300,400.25


Dif

Write a file out in DIF format. DIF (Data Interchange File) format is used primarily for transmitting data to non-SmartWare spreadsheets (e.g., VisiCalc).


M-Sylk

Write a file out in Microsoft's SYLK (Symbolic Link) format. The M-SYLK option is also used for transmitting to non-SmartWare spreadsheet programs (e.g., MultiPlan).


Smart

Write a file out in Smart format. Using this command creates a file that can be imported into another SmartWare module. Using File Export Smart is useful when you want to transfer information to another SmartWare module; File Import is used to read data into a worksheet in SmartWare Spreadsheet or into a document in SmartWare Word Processor. The resulting file can also be sent to SmartWare Communications for transmission to a remote operator.

Sometimes using File Export for transferring to another SmartWare module is preferable to using Send. Using Send Data results in a temporary .iff file that is erased once the target module is exited. By using File Export, a permanent file is created that can be reloaded at another time.

Each record in a Smart file is terminated with a carriage return and a line feed. Fields in a Smart file are separated by spaces. Alphanumeric fields are surrounded by quotation marks, while numeric fields are not. The end of a Smart file is marked by a ^Z (Control Z). The only difference between ASCII and Smart file formats is the ASCII use of commas instead of spaces between fields. The following is a sample record in Smart format:

     "text field" 1000 "text field" 300 400.25


Text

Write data out into textfile format. Text format is similar to Smart format, but there are no quotation marks around text items. Use the Text option to write a file that can be read into a document or textfile in SmartWare Word Processor. The following is a sample record in Text format:

     text field 1000 text field 300 400.25

When exporting fixed-length records with the Text option, each field is assigned a fixed width, regardless of the size of the data in it. In this way, the columns are always lined up as shown in the following example:

     John Smith       35 AMCE Supply      100.45
     Evelyn Jamison   42 Smith's Florist  257.12
     Tim Lee          27 Harper's         431.09


3-Dbase

Write a file out in dBase III format. Each SmartWare field type is converted to the nearest equivalent field type in dBase III. SmartWare time fields are converted to character format fields in dBase and given a length of 8 characters.
NOTE: Files in dBase III are limited to a maximum of 128 fields. Alphanumeric fields over 254 characters are truncated when converted to dBase III format.


Local-Smart5

Write a file out in Local-Smart5 format.

Data-file Type


C/S-Smart5

Write a file out in C/S-Smart5 format.

Data-file Type


4-Smart4

Write a file out in Smart4 format.

Data-file Type

Importing Information


File Password

Select File Password to attach password protection to a view or data-file in the current window, or to remove it. After a password has been assigned to a view or a data-file, the Database prompts each user for the assigned password before allowing the user to access the view or data-file. File Password provides the options Data-File and View.


File Password Data-File

If you select Data-File, you can assign or remove a password and encryption to the data-file. An encrypted file is stored in unreadable form on the disk. Encryption thus provides a second level of protection for your data.


 Enter a data-file name, aided by a prompter showing the data-files attached to the current view.


Attach

If you select Attach and the view or data-file has no password, you must enter a new password that includes up to 16 characters. You must enter it twice for verification. If you chose the Data-File option, you must also specify whether or not you want the data-file encrypted.

If you select Attach and the view or data-file has a password, you must enter the old password that you want to change. You have three chances to enter the password correctly before the program aborts the command. After you enter the old password, you must enter the new password twice for verification. If you chose the Data-File option, you must also specify whether or not you want the data-file encrypted.


File Password View

The View option assigns or removes a password to the current view and automatically encrypts or de-encrypts the view.


Remove

If you select Remove, and the view or data-file has a password, you must enter the password to remove. You have three chances to enter the password correctly before the program aborts the command. After you enter the old password, password protection is removed. The password and encryption are removed simultaneously.

Since the data-file is rewritten to disk when encryption is removed, it is a good idea to back up an encrypted version before executing the Remove option.

Creating a View
Creating a Data-File
Database Preferences


Order Commands

The Order commands allow you to organize your data in various ways.


Order options list

Order provides the following options:

Key. Adds, deletes, or rebuilds a key for records in a data-file.

Sort. Defines, executes, or undefines the criteria that sort the records in a view.

Manual. Indexes and orders records selected individually from the current view's data-files.

Change. Specifies the order in which you review or process the records of the current main data-file.


Order Key

Select Order Key to add, delete, or rebuild a key for records in a data-file. A key field is a designated field whose data (in alpha or numeric sequence) is used to arrange the display and processing order of records in view. Each key can be composed of a major key field and up to fifteen subordinate fields called "minor key fields." A minor key field is referenced for assignment of record order when the data in the major key field of two or more records is identical. A maximum of fifteen major keys can be included in a view's key file.

Once a key has been defined, records can be viewed in key order at any time by means of the Order Change Key command.


Order Key Options

Order Key provides the following options:

Add. Creates a new key for a data-file.

Delete. Removes and deletes an existing key.

Rebuild. Rebuilds all keys in the key file.


Key Add

If you select Order Key Add, a prompter showing the available fields appears. A "k" appears next to each field already defined as a major key field. Specify a list of one or more fields that are to make up the key. This can be done by pressing F6 to highlight the field at the prompter, or by typing in a list of fields, separated by semicolons. The first field selected is the major key field. Any subsequent fields entered in the field list are considered minor key fields. Press F10 when you have completed the list.

After you select the fields, the Key Definition Menu appears.


The Key Definition Menu

The Key Definition Menu allows you to refine the definition of the key you are creating. It first displays an option to allow or disallow entry of records with duplicate key field values.

The Key Definition Menu furnishes a three-column list that includes:
*** a list of field names you have selected, with the major key field at the top of the list
** the sorting orientation for the field name in the first column
** the length of an alpha or inverted key field (the maximum number of character positions the Database will reference to place records in the appropriate sequence). No length specification is shown for numeric fields because they are sorted by numeric value and not by the number of character positions searched.

To change the sorting orientation for a field, use the pointer to identify the field you want to modify. Type A to change the orientation to ascending or type D to change it to descending.

To lessen the number of character positions to be searched (and speed up the ordering process), you may want to enter a smaller number, if fewer characters can adequately determine the correct order for the file.


Key Delete

If you select Order Key Delete, a prompter showing available fields is displayed. A "k" appears next to each major key field previously defined. Use the pointer to identify the key to be deleted and press Enter to select the name, or type the name of the field directly. Press F6 to mark multiple keys for deletion. When you finish, the Database removes the key from the key file.


Key Rebuild

Select Order Key Rebuild if the key file has been lost or damaged. It rebuilds every key in the key file. If the current view has more than one data-file attached, only the key file of the main data-file is rebuilt.


Order Sort

Select Order Sort to define the criteria for sorting the records in the current view, store the sort criteria in a sort definition file, create an index file based on the chosen sorting criteria, and order the records according to the sort criteria. Viewing records in index order means looking at records as they appear through an index.

The sort definition file specifies the fields to use for sorting criteria (e.g., sort by [State] and then by [City]). Sort arranges records according to the alpha or numeric order of data in a designated major sort field and optional minor sort fields.

You can view or process records in index order at any time using the Order Change Index command.


Difference Between Sort Indexes and Keys

Sort processes only those records present in the current logical order (unlike Key, which accesses all records in the view). In addition, a sort index is not updated automatically when new records are added. You must create a new, more current version of the index. A key, on the other hand, is updated automatically when new records are entered.

A sort index is a list of record numbers arranged in a particular sequence. A view can have any number of indexes and up to fifteen major key fields.
IMPORTANT: Accented or "double" foreign language characters will not sort properly unless you select the character comparison table for that language. To select a character comparison table, select Tools Preferences Global and move the cursor to the Character Comparison Table: prompt. Press F6 to display a list of languages for which character comparison tables have been installed. Select the language you will be sorting.


Order Sort Options

Order Sort provides the following options:

Create. Creates reusable sorting criteria, saving them in a sort definition file.

Execute. Arranges the display and access order of records selected from the current view's data-files.

Modify. Modifies a sort definition file.

Now. Orders the records in the current view without saving the sorting criteria.

Remove. Deletes a sort definition file and the sorting criteria that it contains.


Sort Create

Select Order Sort Create to create sorting criteria and then store them in a sort definition file. You are asked to enter a name for the new sort definition file.

You are prompted to build a field list to specify the order in which fields will be used to sort records. A prompter showing available fields is displayed to aid you. The first field selected is the major sort field; any additional fields are minor sort fields. When you finish your selections and press Enter, the Sort Definition Menu appears.


Sort Definition Menu

The Sort Definition Menu lists the fields you have selected. To the right of each field name are two default settings: one signifying ascending or descending order, the other signifying the length of the field. You can use the cursor keys to point to and change the displayed settings.

The first item is for the sort type. The default is A for Ascending. If you desire a descending sort, enter D.

The second item represents the total length of an alpha or inverted field. Use this setting to control the number of character positions that will be referenced to perform the sort operation. This item cannot exceed 100 characters (if the field length was defined as equal to or greater than 100 characters, the Database displays 100 as the default). If you wish to create the sort definition to reference fewer than the total number of characters in the field, enter a smaller number to override the default setting.

The sum of lengths for all fields cannot exceed 500 characters. No length specification is made for numeric, date, time, or counter fields because they are sorted by total (not partial) numeric value. An implied, internal length of 8 bytes for a numeric field is included in tallying the 500 character limitation.


Sort Execute

Select Order Sort Execute to create a sort index file from a sort definition file. A sort index file lists the current sorted order of records.

When you select Order Sort Execute, SmartWare presents the following menu of sorting methods:

     Dictionary  Smart


 Dictionary. The Dictionary sort option orders uppercase and lowercase characters together.


 Smart. The Smart sort option orders uppercase characters before lowercase letters.


 You are prompted to enter the name of the sort definition file to be referenced. You can reuse the same sort definition file as often as necessary, a procedure especially useful for Project Processing applications.


 You are prompted to enter a sort index filename. Whether you should enter a new name or the name of an existing index depends upon how the index is to be used. An index is a "snapshot" of the records as they exist at a given point in time. If you need to retain a particular version of the records, specify a unique filename for each index. If you do not need "frozen" records, you can reuse the name of an existing index, as long as the view is not currently ordered by the same index. Be aware that if you do reuse an index, its existing data is overwritten.

After you specify an index, the Database begins the sorting process. First, the word "Sorting" appears at the bottom of the screen. If the sort must work in two or more areas of memory and then combine the data in each, the message "Merging" appears. When the sort is completed, and the sort index file is recorded on disk, the records appear in the window in sorted order, and you are returned to the command level.


Sort Modify

Select Order Sort Modify to modify an existing sort definition file. A prompter showing available sort definition files appears. When you select a sort definition file, the procedure is the same as the definition process described for the Create option.


Sort Now

Select Order Sort Now both to enter sorting criteria and to sort the current view. Use the Now option when you want to sort records quickly and you anticipate no need for the sorting criteria in the future. Now creates a sort definition and a sort index file in a one-step operation, but it does not save the sort definition in a sort definition file. It does not allow you to use both ascending and descending sort types in the same definition, or to set the number of characters that will be referenced for each field in the definition.

When you select Order Sort Now, SmartWare presents the following menu of sorting methods:

     Dictionary  Smart


 After you select the sort method, you are asked to enter a new sort index filename.


 You are then shown a prompter from which you can select sort fields. Press F6 to select a field for the sort field list; press F7 to remove a field from the sort field list. You can also use F2 to toggle between Prompter mode and Editor mode for specifying fields. Press Enter or F10 to complete the selection process.


 Next, you are asked to select either Ascending or Descending as the order.

When you press Enter, the sorting process proceeds. The records are displayed in index order when the sort is finished.


Sort Remove

Select Order Sort Remove to permanently remove a sort definition file and its sorting criteria from the disk. You are prompted for the name of the sort definition file to be deleted.
NOTE: Deleting a sort definition file does not delete the index created from it. You can still access the index by executing Order Change Index.


Order Manual

Use Order Manual to select individual records displayed in standard view format and create an index file. You are asked to enter an index filename, which can be a new index or an existing index that you wish to modify. Press F7 to select (highlight) or deselect a record for inclusion in the index. To abort, press Escape. When you press F10, all selected records are placed in the index, and the records in the data-file are ordered according to that index.

If the current view is in key order when you execute Order Manual, the view remains in key order while you select records. If the current view is in index order, the view reverts to physical order while you select records.

If you execute Order Manual and specify one of the current view's existing indexes, the records from the index are preselected for the Order Manual command. You can then press F7 to deselect records that are not to be included.


Order Change

Use the Order Change commands to display records in an existing key or index order, or to revert the display of records to physical order.


Order Change Options

Order Change provides the following options:

Key. Displays all records in the current view by a previously created key.

Index. Displays records from the current view according to a previously created sort or query index.

Physical. Displays records in the current view in physical (sequential) order.


Change Key

If you select Order Change Key, a prompter appears showing fields, with a "k" displayed next to each currently defined key field from the main data-file. When you pick a key field, the records are reordered according to the corresponding key, and the first record in that key order becomes the current record.

NOTE: When you enter or modify key field data through a view in key order, SmartWare updates the key file immediately, (i.e., as soon as you move the cursor off the record, and before the next record appears). Because updating the key file involves positioning the record in the appropriate location, the "next" and "previous" records may have changed.


Change Index

Index files can be created by the Order Sort, Order Manual or Data Query commands. When you select Order Change Index, you are asked to enter an index filename, aided by a prompter that lists existing index files. After you enter the name of the index file, the records are redisplayed according to the index, and the first record in the index order becomes the current record.


Change Physical

If you select Order Change Physical, the records of the data-file are returned to the physical or sequential order in which they were entered. The first physical record becomes the current record.


Print Commands

The Print commands allow you to output data from the Database to the screen, to a disk, or to a printer in a number of different formats. Two predefined formats are available, as well as custom report formats that can be designed to meet your needs.


Print options list

Print provides the following options:

Current-Record. Prints a copy of the current record in list, page, or view format.

View. Prints a copy of every record in the current view's data-files in list or report format.

Report. Creates, modifies, outputs, or removes a custom report definition file.


Print Current-Record

Print Current-Record prints information about the currently displayed record.


Current-Record List

The List option of Print Current-Record prints each field of the current record on a new line. It also includes the logical number of the record and indicates whether or not the record is active. Following is an example of output from the List option of Print Current-Record.

     Record#:1 Act:Y
     Name: John Tyler
     Account #: 176
     Phone: 212-573-5846
     City: New York
     State: NY
     Zip: 10004
NOTE: If you execute Print Current-Record List on a record with a view table in it, all records from the table will print out with the record, and will be indented five spaces. Following is an example of output including a record with a view table.

     Record #: 7 Act: Y
     Donor #: 121
     Name: Robin Murphy
     Address: 494 Lee Street
     City: Lenexa
     State: KS
     Zip: 66219
        Date: 02/15/1989
        Amount of Donation: $100.00

        Date: 03/21/1989
        Amount of Donation: $75.00

        Date: 04/17/1989
        Amount of Donation: $100.00


Current-Record Page

Print Current-Record Page prints the current page of the record in the current screen format. It furnishes the options All and Data.


 All. Print Current-Record Page All prints the entire page/screen, including field titles, text, and graphic characters. All does not print the command list or help lines. Following is an example of output from Page All:

     Account #  176
     Name  John Tyler
     Phone  212-573-5846
     City  New York   State  NY
     Zip  10004


 Data. Print Current-Record Page Data prints the data as it is displayed on the screen, but only the data in the fields is printed. No text, graphics, or field titles are printed. This option is useful for printed forms if the screen design matches the design of the form. Following is an example of output from Page Data:

     176
     John Tyler
     212-573-5846
     New York                  NY
     10004
NOTE: If you select Print Current-Record Page with a standard view loaded, the output will consist of all the records that are currently on the screen in tabular format.


Print Current-Record View

Print Current-Record View prints all pages of a multipage view in the format it appears on the screen. It provides the options All and Data. The All option prints data, field titles, text, and graphics, while the Data option prints data only.
NOTE: If you execute Print current-Record View with a standard view loaded, you will get all pages of the record the cursor is on in list format.


Print View

Print View allows you to print all the records in data-files attached to the current view. This information can be printed in a simple list format or in a tabular report format.
IMPORTANT: If you place your records in key order, that is the order they will be printed in. Likewise, if you place your records in index order, only those records in the index will be printed.


Print View List

Print View List prints each record of the current view in the current logical order of records. The following example shows list format.

     Record #:  1  Act: Y
     Name:  George Jones
     Company:  Sticom, Inc.
     Address:  256 Kimball Road
     City:  Kansas City
     State:  MO
     Phone:  (816)-736-4824

     Record #:  2  Act: Y
     Name:  Jo Garrett
     Company:  Genero, Inc.
     Address:  30 Oak Road
     City:  Kansas City
     State:  MO
     Phone:  (816)-354-5684

Any view table records on the view are indented five spaces when the list is printed. This allows you to easily identify view table records.


Print View Report

Print View Report prints each record of the current view in a predefined, columnar report format.

Name | Company | Phone
------------- | ---------------- | ---------------
George Jones | Sticom, Inc. | (816)-736-4824
Jo Garrett | Genero, Inc. | (816)-354-5684
John Tikin | Botkin Mfg. Co. | (816)-645-3851

View table records appear as additional columns with each record in the table area(s) occupying a line of output. All table records that correspond to a particular view record are printed before the next view record is printed.


Selecting Fields

After selecting either the List or Report option, a prompter list of available fields appears. Specify which fields you would like to print in your list or report. Move the pointer arrow using the arrow keys. To select a field to print, position the pointer next to it, and press F6. After you have specified all the fields you wish to print, press Enter.


Print Fields

A prompter list of available fields appears. Specify which fields you would like to print in your report. Use a mouse click to select each field. Use a double mouse click to select the last field.


Printing to Screen

Once you have specified the fields to print, choose either the Screen or Printer option. The Screen option allow you to output your data to the screen. The records will scroll through the screen in the format you have specified. You can control the scrolling speed by pressing a number. The higher the number, the faster the scroll rate (0 = 10). To pause scrolling, press any other key. Resume scrolling by pressing any key. The Screen option is an excellent way to "preview" your data before selecting the Printer option to send it to a printer.


Outputting to Printer

Select the Printer Option when you are ready to send data from the fields you have selected to a printer in List or Report format.


Print Report

Print Report allows you to define, modify, execute, or remove custom report definition files. Creating these files is more complicated and time consuming than using one of the predefined formats, but the results can make the effort worthwhile. By creating a report definition, you can specify multiple formats to be printed in the same report; the printing of fonts; and the insertion of additional text, calculations, breakpoints, and summary information.

The Database provides three types of custom reports: a table report, a form report and a combination report, which includes both a form and table on the same page. Many additional report options provide even more flexibility over the content and format of your report.
IMPORTANT: Report definitions are not tied to a particular view. As long as the field titles and overall record structure are consistent, a report definition can be used on any number of views. A view you intend to print with this definition must be loaded when you create and execute the file.


Table Report

In a table report, each record occupies a line, and each field is printed in a column. The following is a sample table report format.

     Name        Address      City       State    Zip

     John Doe    300 Main St.  Kansas City    MO    64114
     Bill Fold   1243 Oak St.  Kansas City    MO    64114
     Jim Nasium  2343 W. 112   Kansas City    MO    64114


Form Report

In a form report, fields can be placed anywhere on the page. This format can be used for mailing labels and preprinted forms. The following is an example of form report format:

     John Doe  (816)482-4921   134-35-7483
     Director, Product Services Rm. 137


Combination Reports

You can also create a combination report that includes both table and form formats. The following invoice is a common example of this type of report.

     John Doe
     ACME Service
     419 West Main Street
     Kansas City, MO 64114

     Quantity   Description   Unit Price    Total
     10      Office Chairs    95.00      959.00
     10      Desks           159.00     1590.00
     10      File Cabinets    69.00      690.00

     Grand Total 3239.00

The name and address section of the invoice is a form report, and the itemized list of purchases is a table report.

Page Definition, Combination Reports
Breakpoints in Combination Reports


Print Report Options

Report provides the following command options:

Create. Defines a custom report format.

Execute. Outputs a report to a printer, a disk file, or to the screen, based on a predefined report definition.

Modify. Edits an existing report definition.

Remove. Removes an existing report definition.


Print Report Create

With Print Report Create you can design a report definition that meets your specific needs. To begin creating a report definition, first load the view you wish to print a report from. Then execute Print Report Create, enter a name for the new report definition file, and choose between the New and Similar options.


 Create New. Select the New option if you intend to create the report definition from scratch.


 Create Similar. Select the Similar option if you want to create a report definition similar to an already existing report definition. If you select Similar, a prompter showing the existing report definitions appears so you can select the report definition that you wish to use as a template.

Report Definition Menu

After choosing between New or Similar, the Report Definition menu appears. Options in the menu at the bottom of the window include:

     Form   Table   Page   Edit-Fonts   Remove-Fonts
IMPORTANT: Most of the options that will be discussed under Report Definition can be accessed under both Print Report Create and Print Report Modify. In both cases, the options work the same. The only difference is that if you use them under Print Report Create, you will be creating a new definition; if you use them under Print Modify you will be editing an existing definition.


Form Definition

If you wish to define a form on your report page, select the Form option from the Report Definition menu. A blank Form Definition Screen appears.
IMPORTANT: You cannot execute the Form option until you have specified that there will be a form on the page. This is done with the Page option on this menu. Defining your page with the Page option is discussed later in this chapter.

A form can include database fields, text items, calculated items, page numbers, or labels. To define a form you insert one or more of these items into a form area on your screen that you specified on your page definition. You can also duplicate, update, move, and remove a form field or item.

To begin the form definition, use the arrow keys to position the cursor at the upper left corner of the area where you want to place a calculation, field, label, or text. Then select the appropriate option from the Form Definition menu.


Calculation

If you select Calculation, you are prompted to move the cursor to the lower right corner of the area to be defined and press Enter. When you do this, the defined area is shaded on your screen. Then you are prompted to enter the calculation at the bottom of the screen. Pressing F6 displays a prompter showing available view fields.

Select a field by moving the pointer arrow to it, or type the field name. Press Enter to enter that field into the current position in the formula you are creating. The calculation will occur during report printing. The same functions available for calculated fields are available here (see Formula Reference Guide for details). The maximum formula length is 255 characters.

At any point, you can press Escape to abandon your calculation and return to the Form Definition menu. Or, when you have completed your calculation, press F10 or Enter.


Calculated Options

The Calculated Options screen is then displayed. The settings on this screen are as follows:

     Flag the Display on Overflow:  Yes  No

This specifies whether an error message is to appear if calculated information overflows the defined area. Yes causes the program to stop and issue a message if an overflow condition exists; pressing any key continues the reporting process. No truncates any overflow without issuing an error message.

     Justify:  Left  Center  Right

This permits justification of the calculated information within the defined area.


Numeric Results

Calculations producing numeric results display the following additional prompt:

     Display: General  Formatted  Date  Time  Histogram

Neither General nor Histogram displays any more prompts. Histogram shows a series of pluses (+) or minuses (-) for the calculated value (e.g., -3 appears as ------).


Formatted Results

If you select Formatted, the following additional prompts appear:

     Precision: 0
     Special Formatting: None  Dollars  Percent  E-Notation
     Negative Formatting: Minus  Parentheses  Credit  Debit
     Use Commas:  Yes  No
     Check Protection:  Yes  No
     Blank when value is Zero: Yes  No

The Precision: prompt defines the precision for the result of your calculation. Enter a number between 0 and 15 to set the numeric precision you want for the result.

The Special Formatting: prompt specifies whether numbers are printed with a currency notation, a percent sign, in E-notation, or without special formatting.

The Negative Formatting: prompt specifies how negative numbers are formatted. You can choose to place a negative sign in front of the number, surround the number with parentheses, or print "cr" or "db" next to the number (to indicate credit or debit).

The Use Commas: prompt specifies whether or not numbers are printed with commas.

The Check Protection: prompt fills out a number to the full area width with asterisks (e.g., *****$100.00). This is useful for printing checks.

The Blank when Value is Zero: prompt specifies whether the calculated result is to appear blank if it is zero or whether zero is displayed.


Date Results

If you select Date, the following additional prompt appears:

     Date Format:  Date-1   Date-2  Date-3

These date formats refer to those set in Tool Preferences Global. You can specify what format you want a date to be displayed in.


Time Results

If you select Time, the following additional prompt appears:

     Time Format:  12-Hour  24-Hour

Here you specify whether times will be displayed in a 12- or 24-hour format.

To record your entries, press F10. To abandon them, press Escape. Either action returns you to the Form Definition menu.


Field

The Field option allows you to insert a field into an area. A prompter displays available fields and prompts you to select the field to insert. Move the pointer arrow to the field you desire, and press F6 or Enter to select it.

A line appears on the screen showing the width of the field you have selected. You can accept the size by pressing Enter, or use the cursor keys to resize the area and then press Enter.


Display Options

The Display Options screen then appears, offering the following settings:

     Flag the Display on Overflow:  Yes   No

This specifies whether an error message is to appear if field information overflows the defined area. Yes causes the program to stop and issue a message if an overflow condition exists. Pressing any key continues the reporting process. No truncates any overflow without issuing an error message.

     Justify:  Left  Center  Right

This permits justification of the field information within the area you defined.

If the field contains numeric information, the same set of additional prompts appear that are displayed for the Calculation option. See the previous discussion under Calculation for information about these prompts.

Calculation information

To record your entries, press F10. To abandon them, press Escape. Either action returns you to the Form Definition menu.


Label

Using the Label option, you can specify several fields for an area. It does not permit each field to be formatted individually as the Field option does. However, if you have more than one field on the same line in close proximity to each other, it is often best to set them up as a label, rather than as individual fields.

For example, if you specified the fields [City],[State], and [Zip] to print on one line, each field occupies a specific position. If the length of the city fluctuates, the spacing of the line can look odd. If you specify all three fields as one line in a label, the spacing is dynamic, and the [State] and [Zip] fields will adjust their position to the length of the data in the [City] field.

A prompt appears asking you to define the area in which you want to place the label. The line and column indicators at the bottom of the screen can help you determine the size of the area. Then press Enter.


Placing Fields

You can place fields in your label by pressing F6 to display a prompter list of available fields. Move the pointer to the field you wish to print on that particular line of the label, and press Enter. If you wish to select more than one field for a line, use F6 to highlight the fields and then press Enter. Press Enter again to move the cursor to the next line of the label and continue selecting fields for all lines.

Only one field list can be placed on any one line of the Label area. But a field list can contain one or more fields.
NOTE: When a label is printed, any field that contains no data is ignored.

A number of basic text editing keys are available to help you create or edit your label. Table 9-14 gives a brief description of each key.

Table 9-14
F3 | Finds a specific character string
F4 | Searches for and replaces an item within the label
F5 | Inserts the result of a calculation at the current cursor position
F7 | Inserts a blank line or the last deleted line at the current cursor position
F8 | Deletes the line at the current cursor position

You can abandon the Label definition at any time by pressing Escape. To record your Label definition, press F10.


Label Options

The Label Options menu then appears, offering the following settings.

     Justify:  Left  Center  Right

This allows justification of the field information within the area you defined.

     Flag the Display on Overflow:  Yes   No

This specifies whether an error message appears if field information overflows the defined area. Answering Yes informs the program to stop and issue a message if an overflow condition exists. Pressing any key continues the reporting process. Answering No truncates any overflow without issuing an error message.

     Obtain the Next Record Before processing the Label:  Yes   No

This is mainly for printing multiple records on one form. If you select Yes, a new record is read from the file before this area is printed. For example, when printing three-across mailing labels, you need to obtain new records before the second and third labels are printed across the page. For more information about the use of this option, see the discussion of mail labels in Chapter 6 of Database Manual.

You can define multiple label areas on a report using the same sequence.

To record your form definition, press F10. To abandon it, press Escape. Either action returns you to the Form Definition menu.


Page-Number

The Page-Number option allows placement of a page number on the report page. You are asked to define where you want to place the page number. Once the area is defined, press Enter.


Page-Number Options

The Page-Number Options screen then appears, offering the following settings:

     Page number control string: Page *

Optional text can be defined to accompany the page number. This text should include an embedded asterisk. Wherever the asterisk is positioned in the text, the page number is printed. For example, the entry Page * prints "Page 11", "Page 12".
NOTE: If the control string you enter is too long to fit into the area you defined, a warning message will be generated when you try to leave this screen.

     Justify:  Left  Center  Right

This allows the justification of the page number within the area you defined.

     Flag the Display on Overflow:  Yes   No

This specifies whether an error message appears if the page number overflows the defined area. Yes instructs the program to stop and issue a message if an overflow condition exists. Pressing any key continues the reporting process. No truncates any overflow without issuing an error message.

To record your page number definition, press F10. To abandon it, press Escape. Either action returns you to the Form Definition menu.


Text

The Text option allows you to place text on the form. When you select the option, a default size box appears. Use the cursor keys to resize the box to the area you want your text to occupy. Press Enter. You can type text anywhere in the box you have defined. The same editor keys discussed in Table 9-14 are available to you here. When you finish typing the text, press F10.


Text Options

The Text Option screen then appears offering the following setting:

     Justify:  Left  Center  Right

This allows you to justify the text inside the area you defined.
NOTE: When you finish, the box is resized to be as small as possible while containing the text entered and honoring justification boundaries.


Dupe

The Dupe option can save you time by duplicating a Calculation, Field, Label, Page-number, or Text area. You duplicate not only the appearance of the item, but also any optional settings you have specified for that definition.

The area duplicated is that in which the cursor resides when you select Dupe. If the cursor is not on an area containing a duplicable item, you are placed in a mode to define the area. Use the cursor keys to create a box surrounding the item(s) you wish to dupe. You can restart this marking process by pressing the F2 (anchor) key.

Press Enter when the items you wish to duplicate are within the box. Then use the cursor keys to move the box to the location you wish to place the duplicate items. Press Enter to complete the duplication and return to the Form Definition menu.


Move

Move enables you to move a Calculation, Field, Label, Page-number, or Text area.

The area moved is that in which the cursor resides when you select Move. If the cursor is not on an area containing a movable item, you are placed in a mode to define the area. Use the cursor keys to create a box surrounding the item(s) you wish to move. You can restart this marking process by pressing the F2 (anchor) key.

Press Enter when the items you wish to move are within the box. Then use the cursor keys to move the box to the location where you wish to place the moved items. Press Enter to complete the move and return to the Form Definition menu.


Remove

Remove permits you to remove a Calculation, Field, Label, Page-number, or Text area from your form definition. Position the cursor on the item you wish to remove and select the Remove option. The item disappears from the screen.

You can remove multiple items by placing your cursor near, but not on the items when you select Remove. Then you can use the cursor keys to define an area containing all the items you wish to remove. Press Enter when the box contains the appropriate items. If you specify removal of multiple items at once, a prompt is issued asking you to verify your wish to remove all the items.
NOTE: Whatever the cursor is on when the Remove option is selected is automatically removed. Be sure your cursor is in the proper position before selecting the option.


Update

The Update option allows you to edit many of the elements you have placed on your Form.

Calculations. If you select the Update option when the cursor is on a calculation, the equation for that calculation appears in the command area at the bottom of the screen and you can edit it. Press F10 when you are finished editing. The Calculation Options menu appears, and you are able to edit the settings for Overflow status, Justification, and Display formatting.

Fields. If you select the Update option when the cursor is on a field, the Display Options menu appears and you can edit the Overflow status and Justification settings.

Labels. If you select the Update option when the cursor is on a label, you can edit the contents of the label. This includes deleting or adding fields and inserting or deleting blank lines in the label. Press F10 when you are finished editing. The Label Option menu appears, and you can edit the Justification, Overflow status, and record processing settings.

Page Number. If you select the Update option when the cursor is on a page number, the Page Number Options menu appears and you can edit the Control String, Justification, and Overflow Status settings.

Text. If you select the Update option when the cursor is on a text block, you can edit the contents of the text block. Press F10 and the Text Options menu appears, allowing you to edit the Justification setting.


Set-Font

You can use various fonts to improve the appearance of your form. With the Set-Font option, you can establish the characteristics of the default font, or change the existing font for items on your form.


 Set-Font Default. The Default option allows you to set the font for any new items that will be entered.


 Set-Font Change. The Change option allows you to set the font for one or more existing items that you specify. If the cursor is not positioned on a defined item when you select Set-Font Change, you are first asked to specify the existing items by marking out an area using the cursor.


Font Prompter

For both Set-Font options, the Font prompter appears listing the available fonts. Either select an available font or press F6 to make a new font. If you press F6, the Font Selector is displayed.


Font Selector

The first item on the Font Selector is the current font family. If you want a font family other than the one shown, press F6. A prompter of available font families is displayed. Select one of the available font families.

The remainder of the items on the Font Selector include options for character set, size (in points), width, slant, weight, modifications, baseline shift, and color. If you specify superscript or subscript for Baseline Shift, an additional prompt appears requesting a "position" entry in points that assigns a distance above or below the baseline.

The source for the selected font family is also displayed (e.g., Internal-font for the Standard font family). Options that appear in parentheses are not supported by the currently selected printer (previously chosen by way of Tools Preferences Hardware). If you select parenthesized options, the system will match those choices as closely as possible with available options for your printer.

When you specify font characteristics on the Font Selector and then press F10 to accept the settings, you also record a newly available font. A new font, using the next available number, is added to the font prompter; an edited font is listed under the same number but reflects the revised attributes.

When the form is printed, if the contents of an item (e.g., a field) are larger than the area specified, the information is truncated. A message may appear depending on the setting of an overflow flag.


Table Definition

If you wish to define a tabular report, select the Table option from the Report Definition menu. The Table Definition menu then appears.
IMPORTANT: You cannot execute the Table option until you have specified that there will be a table on the page. This is done with the Page option on this menu. Defining your page with the Page option is discussed later in this chapter.

You can establish what information you wish to print in the columns of your tabular report, format those columns, and group the data in the columns in a logical manner. Calculations, text, titles, breakpoints, and summary information can also be added to your report table.


Columns

Defining a table requires you to select fields to print and to specify the width and position of columns to print them in. Start the process by selecting Columns from the Table option list. The Columns option list then appears:

     Calculation  Field  Text  Move  Remove  Update  Set-Font

Move the cursor to the position of the column where you want to place a calculation, field, or text.


Columns Calculation

If you select Columns Calculation, you are prompted to enter a formula. Press F6 to display a list of available fields. Select a field by moving the pointer to it, or type the field name. Press Enter to enter that field into the current cursor position in the formula you are creating. This calculation occurs during report printing. The same functions available for calculated fields are available here (see Formula Reference Manual for more detail). The maximum formula length is 255 characters. Press Enter when you have completed entering the formula.

Calculated Options. The Calculated Options screen then appears. The settings on this screen also appear after you define a field or text item. The following settings are offered.

     Column width:

This defines the width of the column. The column width can be any size from 1 to the maximum page width. Other constraints are that it be wider than the length of the longest heading line and that it fit on the page with the other defined columns. A default number is usually offered, but you can edit it.

     Heading
     Line 1:
     Line 2:

Here you can type in headings for the column you are defining. If you are defining a column using a database field, the second heading is automatically filled with the field title. This can be edited if desired.

     Justification:  Left  Center  Right  None

Choose the justification you desire for the column heading.

     Data

The following two settings affect the data that will be printed under the column heading.

     If the Display Overflows the Column Width: Wrap   Truncate

This setting specifies what happens to text that exceeds the defined column width. If the Truncate option is selected, only as much text as fits in the defined column is printed. If the Wrap option is selected, all of the text is printed in a column under the field title. Sentences are broken between words. There is no limit on number of lines to be wrapped.

     Justification:  Left  Center  Right

Here you can select justification for the data in the column.

The following items appear for Calculation definitions and for Field definitions, but not for Text definitions:

     Display: General  Formatted  Date  Time  Histogram
     Precision: 0
     Special Formatting:None  Currency  Percent  E-Notation
     Negative Number Formatting: Minus  Parentheses  Credit  Debit  Reject
     Use Commas:  Yes  No
     Blank when Value is Zero: Yes  No

These options have already been discussed in the section entitled Calculation under Form Definition. Consult that section for more information.

Calculation information

The only setting not previously discussed is the Reject option in the Negative Number Formatting: item. This outputs a blank when the content of the field or the result of the calculation is a negative value.

When you have completed your settings on any of these screens, press F10 and you will be returned to the Columns Option menu.


Columns Field

This option allows you to place a field from the current view into one of the columns on your report. A prompter list of available fields appears and you are asked to select the one you want to print. The Field Options screen then appears. The settings on this screen are the same as those discussed under Columns Calculation.


Columns Text

The option allows you to type in text that will be typed in a column on the report. When you select the Text option, the Text Options screen appears.

     Text:

Enter the text that you want to print in this column at this prompt. The other settings on this screen have already been discussed under Columns Calculation.


Columns Move

Columns Move repositions a column to a new position. Position the cursor on the column you wish to move and select the Move option. Then move the cursor to the new position for this column and press Enter. The column moves to a new position and you are returned to the Columns option list.


Columns Remove

Columns Remove removes a column definition from the report. Position the cursor on the column to remove and select the Remove option. The column is then removed.


Columns Update

Columns Update allows you to change the option settings that are defined for a column. Position the cursor on the column to edit and select the Update option. The previously defined item list is displayed, and you can edit the current settings. After finishing the edit, press F10 to record changes or Escape to abandon them. Either action returns you to the Columns option list.


Columns Set-Font

You can use various fonts to improve the appearance of the data in your columns. With the Set-Font option, you can establish the characteristics of the default font, or change the existing font for items on your form.


 Set-Font Default. The Default option allows you to set the font for any new columns that will be entered.


 Set-Font Change. The Change option allows you to set the font for one or more existing columns that you specify. The cursor must be positioned on a defined column when you select Set-Font Change, or an error message will be generated.

For information about the Font Prompter and Font Selector, select the following related topic.

Font Prompter and Font Selector


Breakpoints

Breakpoints are used to divide a table into similar subgroups of records, according to the data in a "break field". For example, you may want your sales reports grouped together according to territory. In order to accomplish this, you specify [Territory] as a break field.

Multiple breakpoints, each on a different break field, would subdivide each territory into smaller pieces (e.g., salesmen). You can designate up to 15 breakpoint definitions.
IMPORTANT: In order for breakpoints to print properly, the view must be ordered according to the field that is a break field. If you have defined multiple breakpoints, the order in which the break fields were selected must correspond to the order of major and minor fields in the key or sort.

For more information about when to use breakpoints and to see examples of printouts using breakpoints consult Chapter 6 of Database Manual.

When you select the Breakpoints option from the Table Definition menu, the Breakpoints option list appears:

     Add  Remove  Update  Set-Font

Multiple Breakpoints
Result Lines
Summary Types


Breakpoints Add

Breakpoints can be set when you are creating or modifying a report. When you select the Add option, a line appears at the top of the screen identifying the break by number. You are asked to move the highlighter to the field you wish to designate as the break field for this breakpoint. The cursor keys, space bar, or backspace key can be used to move the highlighter.

Press Enter when the highlighter is on the proper field. Or, you can press F6 to display a prompter list showing available fields and select the break field from the list.

The indicator "key" then appears under the break field, and the Totals Options screen appears.

Totals Options. The following settings can be made on the Totals Options screen for each break that you define:

     Output lines
     Line 1: Blank  Underscore  Double  Results  Omit
     Line 2: Blank  Underscore  Double  Results  Omit
     Line 3: Blank  Underscore  Double  Results  Omit
     Line 4: Blank  Underscore  Double  Results  Omit
     Line 5: Blank  Underscore  Double  Results  Omit

Up to five output lines can be printed for each break. Each line can be defined independently to contain a blank space, an underscore, a double underscore, the results of a defined summarization (e.g., sum, average, etc.) or to be omitted. For example, if you want to have a sum performed on the data in one subgroup of records, the result (total) can be printed before the next subgroup of records is printed. These five settings allow you to control the spacing and appearance of that result.


      Result Line Label: Total

This is an optional label which can be printed next to the result line you specified in the previous setting. If you are not printing a result, or do not wish a label for your result, use F3 to blank this setting. Total appears as a default title, but you can edit it.

Result line labels may be calculations. To use a calculation, enter the first character of the label as an equal sign (=), followed by an expression. This label text is calculated each time the report is printed. Labels are printed in the column to the left of the column containing the result. If there is not enough room on the page to the left of the result, the label is automatically wrapped to the next format line (Blank, Underline, Double, Results) of the current break. After the last format line is printed, any unprinted portion of the break label is ignored.

     Lines to Skip After Break:  0  1   2  3  4  5  New-Page

You can select the number of lines to skip after each break. Zero to five lines can be selected, or you can skip to the top of a new page after each break. This setting is of particular importance when you are printing combination reports. For example, if you are printing an invoice with a form at the top of the page and a table at the bottom, in order for the proper form and table items to print together, this setting must be on New Page. For more information, read the discussion of Combination Reports in Chapter 6 of Database Manual.

     Suppress Printing of Duplicate Field Entries:  Yes  No

This allows you to suppress printing of duplicate field entries for consecutive records. For example, if you are printing a report of the sales of each salesman, you might only want the salesman's name to appear once even if he has multiple sales. If you are setting up a breakpoint using the [salesman] field, each salesman's sales will be grouped together, and his name will only appear once in that grouping.

If you select Yes, the field entry is only printed once each time a new name is encountered. No causes the field entry to be printed every time. Examples of both options follow.

Duplicate Entries Not Suppressed

[Salesman] [Amount of Sale]
Jones $749.35
Jones $588.27
Jones $423.33

Kelly $960.77
Kelly $125.99

Smith $344.66
Smith $755.90
Smith $611.23

Duplicate Entries Suppressed

[Salesman] [Amount of Sale]
Jones $749.35
$588.27
$423.33

Kelly $960.77
$125.99

Smith $344.66
$755.90
$611.23

     Print the Record Count:  Yes   No

You can print the number of records in each group by answering Yes.

     Print the Calculation Names: Yes   No

You can perform multiple summarization operations on each subgroup of records created by a breakpoint. (All summarization types are discussed later in this chapter.)

For example, you may wish to know the total sales for each salesman, and the average dollar amount of his sales. This could be done by performing a sum operation, and an average (Avg) operation on the same breakpoint. All summarizations defined for the breakpoint will be grouped together to conserve vertical space. To avoid confusing multiple summarizations for a single column, you can choose Yes for this item. The name of the summary operation will be printed to the left of the result.

There is a way to print unique labels with these multiple summary operations that involves declaring more than one breakpoint for the same break field. This will be discussed later in this chapter.

     Print the Totals when the Break contains only One record?   Yes  No

Specify whether or not you want totals printed when there is only one record in the subgroup created by the break.

     Position the First Printed Character (optional):
     Line:
     Column:

You have the option of positioning the five output lines you set up with the first settings on this screen at any point in the table. If the position has already been passed by the printer when the operations are calculated, the break summarizations are printed on the next page. The default settings of 0 for both Line and Column cause summarizations to be printed on the next available line.

After you have specified your settings on the Totals Options screen, press F10. An option list showing all the summary options that can be performed on a breakpoint are displayed.


 You must move the highlighter to the field on which the operation will be performed. For example, if you want to total each salesman's sales figures, [Salesman] would be the break field, so that all the records will be grouped according to salesman. However, you want to know the total dollar amount of sales. You want to perform a sum operation on the [Amount of Sales] field.

Once the highlighter is on the appropriate field, press the letter that corresponds to the operation you wish to perform. Table 9-15 shows the available keys and their corresponding summarization types.


 Table 9-15
Key | Summarization Type
A | Average
C | Count
M | Maximum
N | Minimum
S | Sum
D | Standard-Deviation
Q | Sum-Squares
V | Variance
R | Remove

To clear a summarization on a column, move the highlighter to the Remove option and press Enter. If more than one summary option exists, a prompter will appear and you can move the arrow to the option you want to remove.

Multiple Summarizations

You can specify more than one operation to be performed on each subgroup of records. Just press additional letters in the order you want the result of the corresponding operation to be printed. Unless you have the prompt Print the Calculation Names: set to Yes on the Totals Options screen, no labels will print with the additional summarizations.

Calculation results are printed using the column's formatting except for Count, which prints a number aligned to the left of the column's decimal point.

After specifying a summarization type(s) for the chosen field, press F10 to record this break or Escape to abandon it. Either action returns you to the Breakpoints option list.


Unique Summary Labels

There may be times when you want more than the summary abbreviation to label your multiple summaries. You can define your own labels for multiple summaries.


Adding Break Lines

In order to define a unique label, you must add a "break line" to the existing breakpoint for each summary operation you are going to perform. This is done by selecting the same break field to be a breakpoint each time. You can only specify a breakpoint for each field once. Each subsequent time you select that same field to be a break field, you simply create a new line for the same break.

When you set up the breakpoint, you select a field such as [Salesman] to be the break field. On the Totals Options screen, adjust your settings to reflect how you would like this result to be printed. Bear in mind that any subsequent summary results will be printed directly after this result. You may want to avoid printing a line or leaving numerous spaces after the result. After pressing F10, you can choose a summarization option. Select only one operation. Press F10 to return to the Breakpoint Option list.

To add another break line, select the Add option, and select the same field as the break field. Press Enter. Notice that the line at the top of the screen now shows both a break number and a line number. The Totals Options screen then appears. Adjust the settings to reflect how you would like the results of this summary to be displayed. Remember that this result will be printed immediately after the result of the operation you have already defined for this breakpoint. At the prompt Result Line Label: type in the unique label you wish to attach to this result. Press F10. Move the highlighter to the field you want the summary operation to be performed on, and then select the appropriate key for the operation you desire.

You can continue adding break lines for each summary operation you want to perform.


Multiple Breakpoints

As previously mentioned, multiple breakpoints allow you to further subdivide grouping of your records. You can create additional breakpoints by selecting the Add option. You can scan the existing breakpoints for this table by using F3 and F4 to display the previous and next breaks, respectively. If you press Enter, on any break other than the last one, the break you are defining will take that break number, and the existing break will be moved to the next number. In other words, you do not erase a break definition by defining another one over it.

The order of multiple breakpoints is important. As the Database processes the records to print a report, it sorts the records first by the first breakpoint, then by the second, etc. By rearranging your breakpoints, you may change the meaning or the value of the printed data.
IMPORTANT: Before executing a definition with multiple breakpoints, the view must be ordered according to a key or sort. The order in which the break fields were selected must correspond to the order of major and minor fields in the key.


Breakpoints in Combination Reports

Breakpoints play an important role in combination reports. A common type of combination report is an invoice. A form at the top includes the name and address, and a table on the page gives a detailed list of purchases. The trick in printing invoices is to make sure that the purchases printed match the name and address on the form. By establishing the proper breakpoints and setting the Totals Options to call for a new page after each break, this can be accomplished.

For a detailed discussion of creating a combination report, read Chapter 6 in Database Manual.

Page Definition, Combination Reports


Breakpoints Remove

The Breakpoints Remove option permits you to remove a defined breakpoint. You can scan the defined breakpoints using F3 and F4 to display the previous and next breaks, respectively. After locating the correct breakpoint to remove, press Enter to remove the definition. Press F10 when you have deleted all the breaks that you wish to remove. Press Escape if you want to return to the Breakpoints option list without removing a Breakpoints definition.
NOTE: If you have already deleted one or more breaks, pressing Escape does not reinstate them.


Breakpoints Update

The Breakpoints Update option edits an existing Breakpoints definition. You can view all the existing breakpoints by using F3 to move to a previous break and F4 to move to the next break.

After locating the breakpoint you wish to edit, press Enter. You then have the option of changing the break field for this break. The currently defined break field is highlighted. If you wish to retain this break field, select it again by pressing Enter, otherwise move to the new break field and press Enter.

The Totals Options screen then appears and you can edit the previous settings. After you complete the edit, press F10. At this point you can remove, add, or change the summary options defined for this break. Move the highlighter if you wish to change the field the operation is done on. Use the R to remove any unwanted operations. Then press F10. You can edit other breakpoints, or press F10 again to return to the Breakpoint option list.
NOTE: If you have already modified and saved one or more breaks, pressing Escape does not restore them to their original settings.


Breakpoints Set-Font

With the Set-Font option, you set or change the font for the result line label or the result of the summary operation you have specified for a breakpoint.


 Set-Font Default. The Default option allows you to set the font for any new items that will be entered. As soon as you select the option, the Font Prompter appears.


 Set-Font Change. The Change option allows you to set the font for one or more existing items that you specify. After you select the Change option, you must go to the break you wish to change. Use the F3 key to move to a previous break and F4 to move to the next break. When the proper break number is displayed at the top of the screen, press Enter. A Font Prompter will appear. At this point you are setting the font for the result label that will be printed with this break.

Select the appropriate font, or press F6 to define a new one. Next you are asked to press Enter if you wish to change the font of the calculated result that will be printed with the result label. If you do, press Enter and a Font prompter will appear. If you don't want to change the font for the result, press F10.

When you have completed changing fonts for this break, press F10. You can then go to another break to edit the fonts, or press F10 to return to the Breakpoint Options list.

For information about the Font Prompter and Font Selector, select the following related topic.

Font Prompter and Font Selector


Grand-Totals

A grand total performs a summary operation just like those defined under breakpoints. The only difference is that breakpoint summaries are performed on a subgroup of records, while a grand total is performed on all records in the report. For example, if you want to calculate and print the total dollar amount of sales from all territories, you would specify a grand total on the [Amount of Sales] field. Grand totals can be set for one or more fields.

When you select Grand-Totals, the following option list appears:

     Add  Remove  Update  Set-Font


Grand-Totals Add

Grand-Totals Add can be used to add a grand total to a report during the creation or modification of the definition. Execute Grand-Totals Add and the Grand-Totals Options screen appears.

Grand Totals Options. On this screen, you have many of the same options available on the Breakpoint Options screen.

     Lines to Skip Before Grand Totals:  0  1   2  3  4  5  New-Page

You can select the number of lines to skip between the body of the table and the grand total result. Zero to five lines can be selected, or you can skip to the top of a new page before printing the grand total.

     Output lines
     Line 1: Blank  Underscore  Double  Results  Omit
     Line 2: Blank  Underscore  Double  Results  Omit
     Line 3: Blank  Underscore  Double  Results  Omit
     Line 4: Blank  Underscore  Double  Results  Omit
     Line 5: Blank  Underscore  Double  Results  Omit

Up to five output lines can be printed for grand total. Each line can be defined independently to contain a blank space, an underscore, a double underscore, the results of a defined summarization (e.g., sum, average, etc.), or to be omitted. For example, if you want to have a sum performed on all the records in the report, the result (total) can be printed at the end of the report. These five settings allow you to control the spacing and appearance of that result.

     Result Line Label: Grand Total

This is an optional label which can be printed next to the result line you specified in the previous setting. Grand Total appears as a default label, but you can edit it or blank the label text with F3.

Result line labels may be calculations. To use a calculation, enter the first character of the label as an equal sign (=), followed by an expression. This label text is calculated each time the report is printed. When printed, calculated labels that do not fit at the left of the left-most total column are automatically wrapped to the next format line (Blank, Underline, Double, Results). After the last format line is printed, any unprinted portion of the label is ignored.

     Suppress Printing of Duplicate Field Entries:  Yes  No

This allows you to suppress printing of duplicate field entries for consecutive records.

If you select Yes, the field entry is only printed once each time a new name is encountered. No causes the field entry to be printed every time.

     Print the Record Count:  Yes   No

You can print the number of records in your report by answering Yes. If the report contains only one record, no count is printed.

     Print the Calculation Names: Yes   No

You can perform multiple summary operations for each grand total.

For example, you may wish to know the total sales figure for the report and the average dollar amount of those sales. This could be done by performing a sum operation, and an average (Avg) operation on the same grand total. All summarizations defined for the grand total will be grouped together to conserve vertical space. To avoid confusing multiple summarizations for a single column, you can choose Yes for this item. The name of the summary operation will be printed to the left of the result.
NOTE: If you are performing a grand total on the left-most column in the table, there may not be room for the name of the operation to print to the left of the result. If possible, you can move your columns to allow room for the names to print.

     Print the Grand Totals when the Report contains only One record?   Yes  No

Specify whether or not you want totals printed when there is only one record in the report.

     Position the First Printed Character (optional):
     Line:
     Column:

You have the option of positioning the five output lines you set up with the first settings on this screen at any point in the table. If the position has already been passed by the printer when the operations are calculated, the grand totals are printed on the next page. The default settings of 0 for both Line and Column cause summarizations to be printed on the next available line.
NOTE: If you are performing grand totals on several columns, there may be a problem getting all results and totals to print in the same area. They may overlap. You may be able to use this prompt to adjust the positions of the result lines.

Summary Types. After completing the settings on the Grand Totals Options screen, press F10. The same list of summary options that is available for breakpoints is now displayed. Select the related topic Summary Types for a list of summarization types.

Summary Types

You must move the highlighter to the field on which the operation will be performed. For example, if you want to know the total dollar amount of sales for the whole report, you would perform a sum operation on the [Amount of Sales] field.

Once the highlighter is on the appropriate field, press the letter that corresponds to the operation you wish to perform. You can choose more than one summary for the same field. Just continue selecting the letters in the order you want the corresponding operation result to be printed. Press F10 when you are finished selecting operations. You are then returned to the Grand-Totals option list.


Grand-Totals Remove

With Grand-Totals Remove, you can clear a selected Grand-Totals line definition. Execute Grand-Totals Remove, and the last grand total definition is displayed. You can use F3 to move to previous definitions, and F4 to move to the next definition. When the proper definition is displayed, press Enter. The definition is then removed.

Press F10 when you have deleted all the definitions that you wish to remove. Press Escape if you want to return to the Grand-Totals option list without removing a Grand-Totals definition.
NOTE: If you have already deleted one or more definitions, pressing Escape does not reinstate them.


Grand-Totals Update

The Grand-Totals Update option edits an existing Grand-Totals definition. You can view all the existing breakpoints by using F3 to move to a previous break and F4 to move to the next break.

After locating the grand total you wish to edit, press Enter. The Grand Totals Options screen then appears and you can edit the previous settings. After you complete the edit, press F10. At this point you can remove, add, or change the summary options defined for this grand total. Move the highlighter if you wish to change the field the operation is done on. To remove a summary operation, position the highlighter on the field above the operations, and press R to remove an operation. If more than one operation is attached to this field, a prompter box appears around the options, and you can designate which one you want to remove by pointing to it and pressing Enter. You can edit other grand totals, or press F10 to return to the Grand Totals option list.
NOTE: If you have already modified and saved one or more grand totals, pressing Escape does not restore them to their original settings.


Grand-Totals Set-Font

With the Set-Font option you set or change the font for the result line label or the result of the summary operation you have specified for a grand total.

Set-Font Default. The Default option allows you to set the font for any new items that will be entered. As soon as you select the option, the Font Prompter appears.

Set-Font Change. The Change option allows you to set the font for one or more existing items that you specify. After you select the Change option, you must go to the grand total definition you wish to change. Use the F3 key to move to a previous definition and F4 to move to the next definition. When the proper definition number is displayed at the top of the screen, press Enter. A Font Prompter will appear. At this point you are setting the font for the result label that will be printed with this grand total.

Select the appropriate font, or press F6 to define a new one. Next you are asked to press Enter if you wish to change the font of the calculated result that will be printed with the result label. If you do, press Enter and a Font prompter will appear. If you don't want to change the font for the result, press F10.

When you have completed changing fonts for this break, press F10. You can then go to another grand total to edit the fonts, or press F10 to return to the Grand Total Options list.

For information about the Font Prompter and Font Selector, select the following related topic.

Font Prompter and Font Selector


Titles

The Titles option on the Table Definition menu is used to define headings, footings, and other miscellaneous information for the table reports.

Headings and Footings can contain Word Processor style Print Control Codes (PCC):

Table 9-16
%L | Left Justification.
%C | Center Justification.
%R | Right Justification.
%P | Is replaced by the current page number.
%D | Is replaced by the date the report was printed.
%T | Is replaced by the time the report was printed.
%F | Is replaced by the name of view that is loaded when execution occurs.

Headings and Footings can also include calculations entered by typing an equal sign (=) at the start of the line. Titles are calculated just before they are printed using current field values. (If you need a single equal sign at the beginning of the line or after a PCC, precede the character with a "%".)

When you select the Titles option, the Title Definition screen appears, offering the following settings:

     Heading

     Justification:  Left  Center
     Line 1:
     Line 2:
     Line 3:
     Blank Lines After the Heading:  0  1  2  3

You can define up to three lines to be printed at the top of the page. These titles may be left or center justified. Up to three blank lines can be printed after the title (before the data begins).

     Footing

     Line 1:
     Line 2:
     Line 3:
     Blank Lines Before the Footing:  0   1  2  3

You can define up to three lines of footings to be printed at the bottom of the page. Up to three blank lines can be printed before the footings.

     Lines to enclose report?  Yes  No

If you choose to enclose the reports with lines, the lines are printed after the title and before the footing on each page.

Press F10 to record or Escape to abandon a Titles definition. Either action returns you to the Table Definition menu.


Set-Font

You can use various fonts to improve the appearance of your table. With the Set-Font option, you can establish the characteristics of the default font, or change the existing font for items on your table.


 Set-Font Column-Headings. The Column-headings option allows you to change the existing font for all column headings in the table.


 Set-Font Heading-Titles. The Heading-Titles option changes the existing font for all Headings.


 Set-Font Footing-Titles. The Footing-Titles option changes the existing font for all Footings.

For information about the Font Prompter and Font Selector, select the following related topic.

Font Prompter and Font Selector

When the table is printed, if the contents of an item (e.g., a field) are larger than the area specified, the information is truncated. A message may appear depending on the setting of an overflow flag.

As soon as you have selected the new font, you will be returned to the Table Definition menu.


Page Definition

The first step in report definition is defining the printed page. Select the Page option from the Report Definition menu. The Page Definition Screen appears.

Settings on the Page Definition Screen are as follows:

     Paper Profile

A Paper Profile is made up of the page size and paper path you want to use to print a file. The paper path tells SmartWare where the printer will find the paper for this job, and how it will move it through the printer. For example, you can specify the use of a tractor fee, or manual printer. For example, you can specify the use of a tractor fee, or manual feed; choose between several paper trays; or specify the use of an envelope or single sheet feeder. Page size tells SmartWare whether you will be printing an 8 1/2-by-11-inch page, an envelope, or a custom page size.

This paper profile will control printing of Database reports. Non-report printing in the Database is controlled by the default paper profile on the Hardware Preferences menu.

To select a paper profile:

Step 1: With the cursor on Paper Profile, press F6. A two-column, pop-up box is displayed listing available paper paths and sizes.

Paths that are appropriate for the current printer are highlighted. As you move the arrow down the list of paths, the appropriate paper sizes for that path are highlighted.

Notice that one path and one paper size are marked by an asterisk. This indicates that these are the default paper path and size as listed in the current descriptor file which you selected on the Hardware Preferences menu.

SmartWare gets information about appropriate selections and the default path and page size from the currently selected printer descriptor file. If you wish to change the default settings, or if you know your printer supports a particular path or size that is not highlighted, you may want to edit the appropriate descriptor file.

Step 2: Use Up-Arrow or Down-Arrow to move the pointer through the path selections. When the arrow points to the appropriate path, press Enter or Right-Arrow.

To select the default path and paper size, move the arrow to the word DESCRIPTOR at the bottom of the box. To select the same settings you specified on the Hardware Preferences menu, move the arrow to PREFERENCES at the bottom of the screen. If you point to either of these words, the path and page size they represent are highlighted as a reminder.

If you set the paper profiles within each module to the PREFERENCES selection, you can change all the profiles by making changes in one place, the Hardware Preferences menu.

If you do not want to select DESCRIPTOR or PREFERENCES, select a highlighted path. The Arrow then moves to the Page Size column.

Step 3: Select one of the highlighted sizes and press Enter.

If you select Custom in the Size column, a prompt is displayed on the command line. Enter the width and length in inches. Each dimension should be separated by a space or "x". For example, 9.5 x 7.5.

You are returned to the Page Definition screen and your selections appear, separated by a comma, at the Paper Profile: prompt. If you select a size or path that is not supported by the current printer, a warning message will be generated when you execute a Print command. You can abandon printing and change to a more appropriate profile, or continue. If you continue the print job, the printer driver will select the "default" profile for your printer as specified in the current descriptor file.

     Orientation

Select Portrait to print the document across the width or horizontal side of the page. Select Landscape to print the document "sideways," across the length of the page. Landscape printing can only be accomplished if your printer supports if.

     Page numbers:  Left  Right  Center  Left-right  Right-left   No-numbers
     Start page number:

The first prompt specifies where the page number is printed. All page numbers are printed at the bottom of the page. For example, Center prints each number at the bottom middle of each page. The Left-right and Right-left options alternate page numbers on each side of the page. This is useful if the report will be in a book. The default page number placement is No-numbers.

The second prompt specifies the starting page number. The default is 1.

     Lines per inch: 6  8

This specifies the space between printed lines. You can choose six lines per inch or eight lines per inch. If you specify eight lines per inch, be sure to change the lines per page setting from 66 to 88 (assuming use of 11-inch paper).

Form Page Option. To include a form (free form layout of fields) on this page, answer Yes to the following prompt. If you are defining a report that includes only a table, answer No.

     Is There a Form on the Page:  Yes  No

If you answer Yes, the following prompts appear concerning the form definition:

     Location of the Upper Left Corner of the Form
     Line:
     Column:

     Location of the Lower Right Corner of the Form
     Line:
     Column:

Enter the line and column numbers of the form boundaries. The boundaries entered must fall within the boundaries of the page.

Table Page Option. To include a table (columnar layout of fields), answer Yes to the following prompt. If you are defining a report that includes only a form, answer No.

     Is there a Table on The Page:  Yes  No

If you answer Yes, the following prompts appear concerning the table definition.

     Location of the Upper Left Corner of the Table
     Line:
     Column:

     Location of the Lower Right Corner of the Table
     Line:
     Column:

Enter the line and column numbers of the table boundaries. These boundaries must fall within the boundaries of the page.
NOTE: When defining both a table and form on a page, special care must be given to their position in relation to each other. The table can overlap the form dimensions in anyway except to completely obscure it. Be sure to adjust the line and column positions for the table and the form.

     Double space body of table:  Yes  No

Enter Yes to double space the body of the table. Enter No if you want single spacing.


 Combination Report Option. If you specify both a Form and a Table on the page, the following prompt will appear.

     On Combination Reports:
     Start the Table Overflow at the Top of Page:  Yes  No
     Reprint the Form on Page Overflow:  Yes  No

If the table overflows the bottom of the page, you must decide where to start the overflow on the next page. The Yes option causes the overflowed portion to start at the top of the new page. The No option causes the overflowed portion to start at the first defined line of the table. You also have the option of reprinting the form on the new page if overflow occurs.

Views with View Tables. If you define a report for a view that has a view table on it, the following prompt will appear on this screen.

     Process records from View Table (leave blank for View Records):

If you want to include view table records in your report you must enter the name of the table after this prompt. To assist you, a box appears at the bottom of the screen, which lists the view tables attached to the current view. If you do not wish to include view table records in your report, leave this setting blank.

Use F2 to edit text and F3 to blank text. After finishing the page definition, press F10 to record it, or press Escape to abandon all changes. In either case, you return to the Report Definition Window.
IMPORTANT: The printer you will be using to print the report should be the current printer selected in Tools Preferences Hardware. Different types of printers have different hardcoded margins. If you create the definition with one printer and then switch to another when you print it, some of your data may be truncated. You may be able to overcome this problem by adjusting the position of forms and tables on the page.

Specifying Hardware Preferences

You can now define a Form, a Table, or both. Select the type of report you wish to define.


Edit-Fonts

To change font characteristics for one of the available fonts, use Edit-Fonts on the Report Definition menu. For example, if you use Edit-Fonts to change the characteristics of available font #4, the new characteristics apply for all instances in the report where font #4 is specified.

After you select the number of one of the available fonts, the Font Selector appears showing the current characteristics of that font. For information about the Font Selector, select the following related topic.

Font Prompter and Font Selector


Remove-Fonts

To remove a font definition, use Remove-Fonts on the Report Definition menu. The Font prompter appears listing currently available fonts, along with a prompt to enter the font number(s) to remove. You can type the font number(s), or you can use the cursor keys to point to a font number and press F6 to mark that font.

Only unused fonts can be deleted, and these are marked with an asterisk (*). If you want to mark all fonts not used in the current report, press F8. This highlights each of those fonts. To remove all fonts marked for removal, press F10.
IMPORTANT: The size of the font you have defined as Font #0 determines the character spacing the Database expects for the whole report. If you use larger or proportionally-spaced fonts your data may be truncated or may overtype other data on the report. You may be able to overcome this problem by adjusting the horizontal and vertical spacing of your report. To make a compressed report, all fonts that you use must be specified as compressed, including Font #0.


Print Report Execute

Print Report Execute allows you to output a report using an existing report definition. If you have not already done so, create a report definition using Print Report Create.
NOTE: Print Report skips deleted records, printing only those records that are active.


 When you select Print Report Execute, a prompter appears listing all existing report definition files in the current directory. Select the report definition you wish to execute by typing in the name, or selecting it from the prompter list.


Print to Disk

Select Disk to output the report to disk. You must then enter the name of the disk file to contain the report. Printing to disk only prints the text of the report. No printer control codes or font information are included in the output file. It is a text representation of the defined report in standard text file format.


Print to Printer

Select Printer to send the report to a printer. The printer currently selected in Tools Preferences Hardware is the printer the report will be sent to. This should be the same printer that was selected when the definition was created. If you use a printer other than the one you had selected when the report was defined, you may have different margins and some of your data may be truncated.


Print to Screen

Select Screen to send the report to the print previewer which allows you to view a report as it appears in the printed output.


Print to Text-Screen

Select Text-Screen to display the report on the screen. The data will scroll by on the screen. This is an excellent way to preview your report before sending it to a printer.

You can control the rate at which the information scrolls on the screen by typing a number between 1 and 10 (for which you press 0)---the higher the number, the faster it scrolls. Press Escape if you want to stop the scroll; press any other key to pause.

After deciding how to output your report, decide whether you want to print it in Detail, or Totals-Only format.


 Detail printing. If you select the Detail option, all information on the report will be output.


 Totals-Only. If you select the Totals-Only option, only the totals from breakpoints and grand totals will be printed. Each individual record will not appear. This can be useful if you only need total information and do not want the details cluttering up the report.


Then you specify at which page you want the printing to start and stop and how many copies you would like.

You can enter an integer for each of these prompts or press Enter. If you press Enter to all prompts, you will print from the first page to the last page, and make one copy of the report.

When you respond to the last prompt, the Database begins to output the report.


Print Report

Print Report allows you to output a report using an existing report definition. Use the Construct pulldown menu to create a report if required.
NOTE: Print Report skips deleted records, printing only those records that are active.

The Execute Report dialog box requests the report's file name and various print options.


Print to Printer

Select Printer to send the report to a printer. The printer currently selected in Tools Preferences Hardware is the printer the report will be sent to.


Print to Screen

Select Screen to send the report to the print previewer. This allows you to view a report as it appears in the printed output.


Report Type

Detail printing. If you select the Detail option, all information on the report will be output.

Totals-Only. If you select the Totals-Only option, only the totals from breakpoints and grand totals will be printed. Each individual record will not appear. This can be useful if you only need total information and do not want the details cluttering up the report.

Specify at which page you want the printing to start and stop and how many copies you would like. Leaving the values at zero will default to printing one copy from the first page to the last page.


Print Report Modify

Print Report Modify allows you to edit a report definition. When you select Modify, a prompt appears asking you to enter a report definition file name. A prompter is displayed showing the existing report definition file names. Select the file you wish to modify from the prompter, or type in the name.

The Report Definition Window then appears. All items within the Report Definition Menu operate the same whether you are creating or modifying a file. The only difference is that with Print Create you are creating a new definition file, and with Print Modify, you are editing an existing definition.


Print Report Remove

Print Report Remove deletes a report definition you no longer need from the disk. After you select Remove, a list of report definition names appears. Select the name of the report you wish to remove from the prompter, or type in the name. It is then removed.


Tools Commands

The Tools commands allow you to perform calculations, create and use directories, perform various file operations, set hardware and operating defaults, create and use macros, and manipulate printer fonts.

Only the Tools Preferences Database options are discussed here. Refer to the Tools command discussion in Chapter 9 of Software System Manual for detailed information regarding the other Tools commands.


Tools Preferences

The Tools Preferences commands are used to configure default settings. When you select Tools Preferences, you must specify whether you want to set Global, Database, or Hardware defaults. For information on the Global and Hardware options, refer to Chapter 9 of Software System Manual.


Tools Preferences Database

Tools Preferences Database displays a definition menu containing settings that control how SmartWare Database performs whenever it is accessed. Any changes that you make to the settings control the way the Database performs until the settings are changed again.

Table 9-18 lists the keys and corresponding actions that may be used to move through the definition menu, specify options, respond to prompts, and record selected settings:

Table 9-18
Key | Action Invoked
F1 | Display Help information.
F2 | Edit text on the prompt line. (Use arrow keys to move cursor while editing.)
F3 | Delete text currently on the prompt line.
F10 | Exit the definition menu and store the settings.
Escape | Cancel the command and restore the original settings. (SmartWare then displays the prompt Cancel without updating? (y/n). The original settings are restored only if you answer y.)
Down-Arrow | Move the pointer to the next option.
Up-Arrow | Move the pointer to the previous option.
Ctrl-Home | Move the pointer to the top of the definition menu.
Ctrl-End | Move the pointer to the bottom of the definition menu.
Page-Up | Move to the previous page of definition items.
Page-Down | Move to the next page of definition items.
Home | Move to the top of the current screen.
End | Move to the bottom of the current screen.
Spacebar or + | Move the highlighter to the right one option.
Backspace or - | Move the highlighter to the left one option.

The Database Preference settings are as follows:


Default Numeric Format

At this prompt, you can specify information such as the numeric precision and justification that will be the default for the Database. This default format is overridden by any display format you specify for a numeric field during view definition. Press F6 to see a list of format options.


Number of Key Buffers

You can specify additional key buffers to be loaded with each file. Key buffers consume memory (approximately 3K per buffer) but speed key processing and some other types of Database activities.

These buffers are allocated when the file is loaded. The memory remains allocated whether your records are in key order or not. In single user situations, increased key buffers can cause you to run out of memory prematurely.

You may want to increase this number before performing a key-intensive activity or batch file import. However, you may want to reduce this number to a minimum before loading multiple files of executing a project that consumes much memory.

In networking situations, to ensure the accuracy of the key file, it must always be read from disk. Setting more than three key buffers is unnecessary.

Unload all files before changing the number of key buffers. After you leave the Database Preferences Screen and reload your files, the number of buffers you requested will be allocated.


Default Data Path

The path name of the directory where you want your data stored can be entered at this prompt. To avoid complications in file maintenance, do not store data in the same directory in which you installed your SmartWare program files.


Macro File Load

If you want to automatically load a macro file each time you access SmartWare Database, enter the name of the macro file at this prompt.


Automatic Load of View

If you want to automatically load a view each time you access SmartWare Database, enter the name of the view at this prompt.


Project File to Run on Entry

If you want to automatically load a project file each time you enter SmartWare Database, enter the name of the project file at this prompt.


Encryption driver

You can choose to use either the standard SmartWare encryption driver or an alternative one that you have loaded yourself.
IMPORTANT: Do not select Alternate unless you are absolutely certain that an alternate encryption driver has been loaded. Otherwise, you risk losing data.


Broadcast port

SmartWare Servers can be set up to broadcast their name over a specific port. This port is 5595 by default. If you customize the SmartWare Server to use a different port, you also need to change the listening port.


Timeout for listening

SmartWare Servers can be set up to broadcast their name over a specific port every certain number of seconds. Timeout for listening is the number of seconds you want SmartWare to listen for broadcasting Servers.


Server-Transactions apply to all files from the same server

You can choose whether each server data-file has its own server-transaction support, or whether all files from the same server are transacted together.


When server is left blank, use this server name

You can specify a server name here so that whenever a server name is left blank, it will use this server name. For example, if you have a test server named TESTSERVER and a production server named PRODSERVER, you can set this value to TESTSERVER, create your data-files (leaving server name blank) and do your testing. When it is time for deployment, you can replicate your datafiles to PRODSERVER and change this value to PRODSERVER and your views will now use the data-files on the PRODSERVER.


Make server data-file requests locally

You can choose to have server data-file requests be made locally. This is useful in an offline scenario. For instance, if you need to take a laptop on the road and will not be connected to your server, you can do a FILE IMPORT to bring the data-files to a Local-Smart5 file format. Then you can set this option to Yes and specify the local directory, and all server data-file requests will be make locally to that directory.


Path to find local copies of server data-files

If make server data-file requests locally is Yes, then this is the directory that server data-file requests will be made in.


Window Commands

The Window commands can be used to manage display of one or more windows in SmartWare Database.


Window options list

Window provides the following options:

Split. Splits the current window into two or more windows.

Close. Removes the current window from the screen.

Zoom. Expands the current window of a multiple window display to fill the Data Window Area or returns it to its normal size after expansion.

Border. Toggles the window border display on or off.

Paint. Changes the colors used in selected areas of the display screen.

Link. Links the display of records in two or more windows.

Unlink. Dissolves a link that has been established between the current window and another window.


Window Split

Window Split allows you to split the Data Window Area into two or more windows. This allows you to load a number of views into different windows in order to move between them or compare them quickly and easily.

Window Split acts directly on the current window to split it into two separate windows. Each time you use Window Split, the new window is automatically numbered in sequence.


Split Horizontal

You can split a window horizontally by moving the cursor to the desired split location and then pressing Enter. If window borders are present, the current window appears within a double-line border.


Split Vertical

You can split a window vertically by moving the cursor to the desired split location and then pressing Enter. If window borders are present, the current window appears within a double-line border.
NOTE: If there is a view active in the current window when you split it, the view will appear in both windows. You can then move to the new window by using Data Goto Window and specifying the window by number, or the Quick Key Alt-F7. Once there you can execute File Load or Data Goto View to bring a different view into the new window.


Window Close

Window Close removes the current window from the screen. As the window closes, the remaining windows expand to fill the vacated area. The number of the current window is in the Status Line at the bottom of the screen.

If you close a window that contains a view, that view remains active. To access the view and its associated data-files, you can use the Data Goto View command. To remove the view from memory, use the File Unload command.
NOTE: Under some special circumstances, the Database is unable to close a particular window. Closing another window first may correct the problem.


Window Zoom

Window Zoom is a toggle command that expands the current window of a multiple window display to fill the Data Window Area. Executing Window Zoom again returns the window to its normal size.


Window Border

Window Border is a toggle command that allows you to switch the window number and border display around the current window on or off. When you first access the SmartWare Database, the window border is on. Executing Window Border the first time turns the border off. To turn the border back on, execute Window Border again.

When the window border is off, there is additional room to display data in the current window. The Database can display 25 windows with borders on a standard display screen. More windows can be displayed in the same space if their borders are turned off.


Window Paint

Window Paint can be used to change the colors displayed in selected areas of the screen for the current window.
NOTE: If colors were set for items such as fields, boxes, or notes during the view definition process, those items cannot be painted. The only way those colors can be changed is by modifying the file and changing the appropriate settings. If you accepted the default colors for those items, then they can be painted.

Any colors you change with Window Paint are in effect for the current session only. If you change colors using Window Paint, unload, and then reload the view, the colors revert to those specified in the last File Create or File Modify procedure. To change colors permanently, execute File Modify.


Paint Options

Paint provides the following options:


 Border. Changes the color of the border surrounding the current window.


 Cursor. Changes the background and foreground color of the block cursor on a standard screen, a browsed view, or a table.


 When you select one of the Paint options, a list of numbered colors appears at the bottom of your screen accompanied by a prompt to enter a color. Enter the number of a new color.

If you select Cursor or Titles, you are asked to enter a background color and a foreground color.


 Data. Changes the color of the displayed data in the current view.


 Graphics. Changes the color of any text or graphic items (boxes or lines) in the current view.


 Titles. Changes the background and/or foreground colors of the titles in the current view.


 Window-Area. Changes the color of the background in the current window.


Window Link

Window Link allows you to simultaneously display corresponding records from different views, in separate windows. This can be a fast and efficient way to find and view corresponding records in two or more views.

The following conditions must be met before a window link can be established:
*** The two views must have a "common" field for the link.
** The link field in the second view must be a key field.


 In order to link two views, you must define a pair of linked fields. Linked fields have a common data type, and they contain individual data items common to both views.

With the link established, each time you access a new record for the current window, the Database attempts to find a corresponding record in the second view by matching data items in the linked fields. If no match is found, the Database issues an audible beep (unless Beep is turned off in the Tools Preferences Global Definition Menu).
Comment: Remember, the current window is surrounded by double lines. You will be linking the current window.


 Before executing Windows Link, load the views you wish to link into separate windows. One of the windows contains what will be the "driver" view. This is the view you want to look at a record in and then have the link find the record that matches it in the second view. Make the window containing the "driver" view the current window.


 Then execute Window Link. A prompter list of available fields in the current window appears. Select the "link field", the field both views have in common. Another prompter list appears, showing all active views. Select the name of the view to which you want to link the current window.

Another prompter list appears showing the fields in the view you just selected. Select the "link field" in this view. The link should be complete. As you move the cursor throughout the current view, the records in the view in the linked window should move.
NOTE: You cannot link to a view that is in index order. An index created by a query may not have all the records available, making a link impractical.

Links are associated directly with the view. Because of this, links are maintained even if a view is placed in the "background." This would occur if File Load or Data Goto View is used to bring another view into the same window.

Cascading links are possible. You can have one view linked to a second, the second linked to a third, and so on. However, if Window 1 is linked to Window 2, then Window 2 cannot be linked to Window 1. This circularity of linking is not allowed.
NOTE: Linking is generally disabled during some batch processing operations such as transactions and relates.

Window Link can also be used to link two windows that contain the same view. Linking a view to itself is useful to view two different pages of the same view record at the same time.


Window Unlink

Selecting the Window Unlink command eliminates all links for the current window. If you have created links for several windows, you must make each one the current window before executing Window Unlink.


Help Commands

The Help commands invoke SmartWare's extensive on-line help information. For assistance in running the Tutorial, read the section that follows. For information on the other Help options, select the appropriate related topic.

Help
Help About-Help
Help Contents
Help Index
Help On-Error


Help Tutorial

Help Tutorial invokes the tutorial for the Database module. You can use the tutorial in a step-by-step process to learn the basics for the entire module, or you may use it to learn about one particular aspect of the module. If the Database tutorial was not installed on your system, use the Changes and Additions option of the Install program to add it at any time.
IMPORTANT: Because SmartWare Tutorials run within the module they describe, it is important that you unload all active files with the File Unload All command before entering the tutorial. When you execute Help Tutorial, you will prompted to unload all files before continuing.

You are then prompted to enter your name. This is optional, however if you do, the program will keep track of what lessons you have completed.

The Tutorial menu then appears. If you would like a brief lesson in how tutorials work, select Using Tutorials. If you want to select a lesson, use the cursor keys to move the prompter arrow to the lesson you want and press Enter. You can go through the lessons sequentially, or pick a lesson that interests you.

After you complete a lesson, you are returned to the Tutorial menu.


Quit Commands

The Quit commands (or Quick Key F10) allow you to leave a module to enter another module or return to the operating system. The Quit options vary depending upon which module you are leaving. Obviously, the module you are leaving does not appear among the Quit options on the screen.

If you have selected Quit and decide that you do not want to leave SmartWare Database, press Escape.

Options for Quit include the following:


 Quit. Returns to the operating system.


 Main-Menu. Returns to the Main Menu of SmartWare Software System.


 Communications. Leaves the current module and enters the SmartWare Communications module.


 Spreadsheet. Leaves the current module and enters the SmartWare Spreadsheet module.


 Wordprocessor. Leaves the current module and enters the SmartWare Word Processor module.


Main Menu

Returns to the Main Menu of SmartWare Software System.


Database Error Messages

     3003  Mandatory entry. Please enter something into this field

This is a mandatory entry field, and you cannot proceed until you enter information into it.

     3004  No fields that allow data entry

The system returns to Command Mode. You have pressed Escape or attempted to enter data into a view with no enterable fields.

     3005  Not enough room to update or enter a record

Not enough room exists in memory to update or enter this record. Free some memory (e.g., unload a file) and try again. Or, save a new or changed table record to regain memory.

     3006  Invalid data for this mask. Enter new data or press Escape to keep data.

The data in this field is incompatible with input mask restrictions established after the data had been originally entered. You can enter new data to conform to the mask restrictions, or you can press Escape to retain the existing data.

     3007  Error trying to read linked data record

A disk error has occurred, the record is locked, or the key may be corrupt. See if the record is locked, then check the key and disk.

     3008  Invalid data for this field

You tried to enter data not appropriate for the field type of the field.

     3009  Cannot assign value to field

Entry was attempted to a read-only or counter field or to a field having an Immediate or Wait calculation, or the value did not satisfy a rule on this field. Use Data Utilities Information to check field options.

     3010 Auto-calculation for [field name] overwrites the assigned value

The value that you assigned to this calculated field was overwritten by a calculated value. This situation occurs when a value is assigned to a field having an Immediate or Wait type of calculation attached, and a recalculation is executed. The situation should not occur with Manual recalculations.

     3052  Too many columns to create data-file

Your entry at Auto Column has produced more columns than the system can generate.

     3053  Field [field name] is not on current view

The specified field is not in the current view either because the Cross-Tab definition was not created for the current view or because the current view has been modified since creation of the Cross-Tab definition.

     3054  No Rows or Automatic-Rows have been defined

You must specify how to create rows, either with explicit row match equations or by selecting Row Automatic.

     3080 Cannot change key member used by link/order (%s).

The destination field cannot be a field that is a major or minor part of a key that is being used to order the view or process the transaction link. If possible, rebuild the key so that the destination field is not part of the key. Or, reorder the view so that it is not ordered by the key containing the destination field and then re-execute the transaction.

     3081  Field [field name] is not a key field

The link field for the driven file must be a key. Make it a key and try again.

     3082  Invalid destination field [field name]; field cannot be on a table

The specified destination field must not be in a repeating area of the driven view.

     3083  File position for (name) is unknown

The destination field is in a table that is not driving this link.

     3084  Link information is missing

Any of the driver field, the driven view, and/or the driven field have not yet been defined.

     3085  Driver view (name) cannot be driven

You cannot specify as the driven view what already has been specified as the driver view.

     3086  No actions defined for link

The definition is incomplete until you specify actions for the link already defined.

     3087  Invalid minors specified for (name)

Specified minor keys either do not exist or are the wrong type.

     3088  Read error on (filename)

An error occurred when the system attempted to read the specified data-file.

     3089  Transaction definition file (filename) not found

The system cannot find the specified transact definition file.

     3090  Cannot create file (name)

An error occurred when the system attempted to create the definition file.

     3091  File (filename) already exists

The audit file you specified already exists. Delete the audit file before executing transactions.

     3093  Enter only one field specification

You can enter only one field specification for the destination field.

     3094  ** Aborted **

This message is printed on the transaction log to show that no more transaction processing occurred.

     3104  Missing data-file name

You must specify a data-file name in your relate definition.

     3105  View 2 field is not a key field

The specified view 2 field must be a key field. Make it a key field or specify another field, and try again.

     3106  View 2 minor link fields are not in key

The minor keys specified for a link field in the link definition do not match the minor keys specified when the field was created. Match the minor keys and try again.

     3107  Duplicate field names

More than one field has the same name. Make each field name unique and try again.

     3109  Page file write error

You are probably out of disk space. Clear space on disk and try again.

     3110  Page file creation failure

The page file cannot be added to the data directory either because no room exists or you do not have the required permission.

     3111  Page file read error

The system can not read the page file because of a media or hardware failure.

     3112  Cannot relate a view to itself

If you need to relate a view to itself, use the standard view for one file and the custom view for the other file. If the two views use the same filename, include the appropriate extension (vw or vws) when specifying the driver and driven files.

     3131  Invalid query definition filename

You entered an invalid query definition filename.

     3132  Can not use both activate and delete replacements in a single query

You cannot use a replace activate and a replace delete in the same query.

     3133  Expression is too complex for query

One of the expressions in the query definition is too big. Break down the query into several smaller queries.

     3134  Replacement not allowed on tables

You cannot replace data in a table field.

     3135  Index file write error

A disk file error occurred during Query Execute. Delete files on the disk or re-run the query .

     3136  No output file specified

You tried to execute a project that lacks an output file specification. Enter an output file at the end of the command.

     3137 Range operator boundaries out of order

In using the ".." range operator in a query definition, you have specified a range that is invalid or meaningless (e.g., 10..5).

     3139  Query definition file not found

SmartWare cannot find the Query definition file you entered.

     3140  Query definition file already exists

Another Query definition file already has the name you entered for the new definition file. Enter a new name or change the name of the existing definition file.

     3141  Cannot create query definition file

Either too many files are open or not enough directory space is available.

     3142  Cannot write query definition file
A disk file error occurred. Re-run the query or delete files on the disk.

     3143  No matches found

A query invoked in project processing found no records.

     3144  All statistics cannot be displayed

Query summary statistics exceed the available display buffer. Eliminate some statistics to correct this.

     3145  Cannot have a table function in a table

You cannot include a Table SDb function in a calculation in a table field.

     3146  Cannot duplicate fields in a new data-file

You cannot specify the same field more than once for a data-file you are creating through Data Query Execute. Remove the duplicate entry from the list of fields.

     3151  Source and destination views must be single data-file views

You tried to append to a view with linked data or multiple data-files. You can do so only to a single data-file view.

     3152  Sequential count value must be between 1 and 2,000,000,000

You cannot assign a count value less than 1 or greater than 2,000,000,000 using Utilities Alter-Count.

     3154  View must be unloaded before executing this command

You cannot run File-Fix View on a loaded view. Unload the view and try again.

     3155  Data-file must be unloaded before executing this command

You cannot Purge or File-Fix a loaded data-file. Unload the data-file and try again.

     3157  Please make a backup copy of your data-file before purging

Do not purge data until you back up the data-file. Any failure may corrupt the data-file during execution.

     3158 No data to be moved

Utilities Append was exited without instructions for transferring data between views. Define the actual transfer of data or cancel the command.

     3159 Warning!  Only (number) out of (number) records appended

Not all records were copied in Utilities Append. You may be out of disk space. If duplicate keys are not allowed, duplicate key records are skipped.

     3160 Invalid pathname (path)

The pathname you have specified for the Data Utilities Information report is invalid. You may have specified an invalid drive or a nonexistent directory.

     3161 Error copying information

SmartWare encountered an error while attempting to copy Data Utilities Information report data into a file.

     3202  Please create link for the table

You must execute Edit-Links to establish a link to the table.

     3203  Data-file is already attached

A data-file with the same name is already attached to the view. Change the name of either the attached data-file or the data-file you wish to attach.

     3204  View has more than one data-file in it

The .vws view from which the system attempted to retrieve the data-file to attach contains more than one data-file. First use Tools File Rename to change the extension to .vw. Then use Data Utilities File-Fix View to create a standard view for the data-file you wish to attach.

     3205  Can not save a table with no fields on it

You have not yet attached a field to the table. Do so.

     3206  Invalid table name

You have entered an invalid name for the table. Enter another name.

     3207  Table too wide. Entire table must fit on screen

The table you are creating exceeds the maximum width, which is 78 characters regardless of the screen driver you are using.

     3214  Error writing pix file

A disk error may have occurred. Try again. If this error appears again, run Data Utilities File-Fix Data-File to recreate the Pix file.

     3301  Only Data-file fields can be Counter type

You cannot specify a View field or Project Variable as a Counter type.

     3302  Table area must have at least 4 lines

Your table area is too small. Include at least four lines in its area.

     3303  Field [field name] must be on table.

You cannot have fields from the same data-file both inside and outside a table area in a view.

     3304  Jump destination field not found.

The field you have specified to jump to does not exist in the current view.

     3305  Keys for data-file (filename) do not match link definition

Link definition must be defined correctly before the view can be saved. Change the keys for the specified data-file or the link definition accordingly.

     3306 Immediate and Wait calculations may not be mandatory entry fields

You can use the Mandatory-Entry field attribute with a Manual calculation type, but not with an Immediate or Wait calculation type. If you want to use the Mandatory-Entry attribute, change the calculation type to Manual. If you want to use an Immediate or Wait calculation, change the special field attribute to Read/Write or Read-Only.

     3307  Cursor is not on a box

You must locate the cursor on the box before you can move or edit it.

     3308  Cursor is not on a note

You must locate the cursor on the note before you can move or edit it.

     3309  Error in link definition field name

The field name you entered contains an error and must be changed. Or, no name has been entered in the link definition. Execute Edit Links to make the correction.

     3310  Calculation for field [field name] will be deleted from the standard screen

The calculation in the specified field of the standard view contains an error. This message is issued when an invalid calculation is encountered during the automatic update of the standard view. This message may also occur if a formula contains both a FILELOOKUP and an assignment expression, and the lookup files are not active. The calculation is deleted from the standard view.

     3311  Error in data-file link information

You tried to terminate the view definition without specifying all necessary link information. Execute Edit Links.

     3312  Unable to create view or project fields on standard view

A standard view consists of data-file fields only. View fields and project fields are valid only on custom views.

     3313  Error resetting key file

You have changed the structure of a view (e.g., added a field), and the system will not allow you to exit the view definition because it cannot make the necessary adjustments in the key file. Load the standard view of the field's data-file and use Order Key to adjust the key file.

     3314  Cannot create a table when one is active

You must return to the normal view definition by pressing F10. When the cursor reappears outside the currently active table area, you can create another table.

     3315  Numeric data types, View, and Project fields cannot exceed a single line

You attempted to edit and resize a numeric, View or Project field to wrap to a second line. Numeric data cannot wrap. This applies to all numeric fields, including counter, date, and time fields.

     3316  Link must be defined before saving view

All data-files within the view must be linked before you can save it. Use Edit Links to establish the links.

     3317  Cannot move beyond original anchor position

When editing a box, field, etc. within a specified area, you cannot change the position of the area's upper left corner.

     3318  Cannot modify a view that is in more than one window

You cannot execute File Modify to change a view unless the view is in one window only or is not loaded at all.

     3319  Input mask cannot be wider than the field.

The input mask you have specified requires more characters than allowed according to the defined field width.

     3320  Invalid input mask

One or more specifications in your input mask are invalid.

     3321  No fields defined for data-file (filename)

You are trying to quit the view definition process with a data-file in the view for which no fields have been defined. Either delete the data-file or create fields for the data-file.

     3322  Cannot change input order on standard views

You cannot execute File Modify Input-Order on a standard view (.vws). Field entry order can be changed on a custom view (.vw). Use Move Block to rearrange the fields in a table or standard view.

     3323  Invalid field order entry

You entered 0 for the entry order of a field while executing File Modify Input-Order. Change that value to another number.

     3324  Entered field order exceeds number of fields on this view

You entered a number for the entry order of a field that exceeds the number of fields on this view while executing File Modify Input-Order. Change that value to an appropriate number.

     3325  Cannot delete:  standard view must contain at least one field

A standard view reflects the data-file itself. By deleting the last remaining field, either specifically as an item or collectively as part of a block, you would be deleting the data-file.

     3326  Cannot delete data-file from the standard view

The View Definition option Delete Item Data-File is not valid for standard views.

     3327  Error in file header information

Memory has become full during execution of File Create or File Modify. Clear information from memory and try again.

     3328  Menu choices do not fit in this area

The bar menu is now so large that it no longer fits within the defined menu area. Make the menu area larger so there will be room for all of the choices.

     3329  Too many choices for menu

You cannot exceed 64 choices for a popup menu field.

     3330  Too much text for menu

You cannot exceed 500 characters for a bar menu.

     3331  Cannot delete table from a standard view

Tables can be defined for custom views but not for standard views. Therefore, the View Definition Menu option Delete Item Table is not valid for a standard view.

     3332 Deleting rule from standard view field [field name]

During the automatic update of the standard view, SmartWare has encountered an error in a rule in the specified field. The rule has been deleted.

     3333  Field already contains a menu

You have attempted to create a menu for a field that already has a menu. Either delete the existing menu and then create a new one in its place, or edit the existing menu to make the desired changes.

     3334  Data-file (filename) not found in link information

The link information within Edit Links is missing the specified filename. All data-files must be accounted for. Execute Edit Links to reinsert the data-file's name in the link information.

     3335  Link fields must be from different data-files

Within Edit Links, the "linked from" and "linked to" fields cannot be from the same data-file.

     3336  Field is already attached to the view

The field you are trying to attach to the view has already been attached.

     3337  Cannot insert here; item overlaps another item

The item you are trying to insert (e.g., text, field, table) overlaps another item on the view. Make the item smaller or move to a new location before attempting the operation.

     3338  Box overlaps another item

While resizing the table using Edit Table, you are overlapping another item. Make the table size smaller.

     3339  Error reading file dbtemplt.def

Either the system could not find the template file or it could not read the file. Copy the file from your master diskettes. This error is also issued when too many files are open.

     3340  Invalid box color

You entered a color number that is invalid. Enter a valid color number.

     3341  Invalid note color

You entered a color number that is invalid. Enter a valid color number.

     3343  Inverted fields must contain less than 100 characters

You have exceeded the maximum of 100 characters for an inverted field.

     3342  Field overlap problem with longer view title

The field title you have revised does not fit in the allotted area of the view because it overlaps an area used by another item.

     3344  Not enough room in the record for a field of this length

The field width you have entered pushes the size of the record beyond the maximum. Decrease the width of this or other fields accordingly.

     3345  Invalid table cursor color

You entered a color number that is invalid. Enter a valid color number.

     3346  Error deleting data-file field

You cannot delete a field from a data-file if the data-file is currently accessed by another user. You must have exclusive access. Wait until the other user is finished and try again.

     3347  Data-file is locked and cannot be modified

You cannot change a locked data-file. Wait until the data-file is unlocked and try again.

     3348  Invalid title color

You entered a color number that is invalid. Enter a valid color number.

     3349  Invalid data color

You entered a color number that is invalid. Enter a valid color number.

     3350  Invalid display format

You used some invalid specifications in the display format.

     3351  Cannot have an input mask on a multi-line field

You attempted to impose an input mask on a multi-line field.

     3352  Duplicate data-file field name

While creating a field, you attempted to give it a name that is already used for another field in the data-file.

     3353  Duplicate field name

The name of the field you are attempting to create or attach is already used for another field in the view.

     3354  Invalid table color

You entered a color number that is invalid. Enter a valid color number.

     3355  Invalid default equation

The default equation is invalid. Correct it.

     3356  No data-files defined

You cannot create a data-file field until you have created a data-file in which to place it.

     3357  Error trying to create new field

Someone else may be accessing the data-file, preventing the system from locking it to create the new field. Wait and try again. If the error message persists, the cause may be filled memory. Remove information from memory and try again.

     3358  Can have only one file in a table area

You attempted to create a field from a different data-file in the table or tried to attach a field from another data-file to the table. Only one data-file may be in a table.

     3359  Field will not fit on the view at this location

You attempted to create a numeric, date, time, or counter field that would wrap to a second line. Numeric data cannot wrap, and there is not enough room on the screen for you to position the field at the current location.

     3360  Invalid field name entered

The name entered for the field you are trying to attach is invalid. Enter a valid field name.

     3361  Cannot add any fields to this data-file

You cannot modify this data-file because it lacks a standard view. Use Utilities File-Fix View to make a standard view before adding fields.

     3362 Cursor is not on a table record

The Data Delete Table-Record command requires the cursor to be in a table area. Use Data Goto Table and position the cursor on the table record to be deleted.

     3363  First character of a field name must be alphabetic

The first character you entered for this field name was not alphabetic. Change it accordingly.

     3364  Invalid character in field name at position (location)

You entered an invalid character at the specified position. Change it accordingly.

     3365  Cannot delete temporary field

In the process of creating a table, the system creates a dummy field that you cannot delete.

     3366  Cannot start update

The procedure cannot proceed either because disk space is insufficient, or because the file is currently locked or otherwise inaccessible.

     3367  Error writing view file

A disk error probably has occurred. Clear information from the disk and try again.

     3368  No items selected

Nothing exists in the area you marked for a move or deletion.

     3369  Invalid move location

You cannot move the specified columns in the table area to the specified location because the marked columns and the destination overlap. Try another location.

     3370  Out of memory creating standard screen

Not enough memory remains to create the standard screen. Remove information from memory and try again.

     3371  Unable to add data-file

Not enough memory remains to add the data-file to the view. Remove information from memory and try again.

     3372  Error loading View Definition Menu

Either not enough memory exists or a disk error has occurred preventing you from accessing the View Definition Menu. Clear information from memory and try again. If the error message reappears, clear information from disk and try again.

     3373  Table not found

You entered the name of a table that does not exist.

     3374  Field [field name] attempted jump to invalid field name [field name]

You cannot leave the view, because the specified jump field name (the field to which the jump is to occur) is invalid. Use Edit Rule to change the jump field name in the rule information contained in the first field specified.

     3375  Data-file not in view

You entered a data-file name to replicate that is invalid. Enter a valid data-file name.

     3376  Error reloading original view

After you exited the view definition procedure, the system failed to load the original view. Use File Load to load the view.

     3377  Cannot save a view which has nothing attached to it

The view you tried to save has nothing attached to it.

     3378  Invalid rule on field [field name]

You cannot quit because a rule is invalid for the specified field. Use Edit Rule to modify the rule.

     3379  Error in calculation on field [field name]

You cannot quit because a calculated field equation is invalid for the specified field. Modify the calculated field equation accordingly.

     3380  Cannot have a menu and a calculation on the same field

You cannot specify a menu and a calculation for the same field.

     3381  Cannot have a calculation on a counter field

You cannot specify a calculation for a Counter field.

     3382  No calculation defined on this field

This field has no calculation to edit.

     3383  No rules defined on this field

No rules exist for you to edit or delete.

     3384 Standard view is not available

When you define a data-file menu, the standard view of the data-file referenced by the menu must be active. The problem might be a shortage of memory; if so, try to free some memory. The problem might be that the standard view for the menu's data-file does not exist; if this is the case, create a standard view.

     3385  Circular reference. Field cannot jump to itself.

You cannot specify that a field jump to itself. Enter another name for the field to jump to.

     3386  Name already used by a table

The name entered for the table you are creating is already used for another table. Enter a different table name.

     3387  Table cannot have more than 19 lines

You specified an area for the table greater than 19 lines. Decrease the specified area.

     3388  Not on a table

No table exists to edit in the area you specified.

     3389  Table is too small

You have resized the table area too small. Resize again for a larger area.

     3390 Data-file menu file cannot be the main data-file

When you define a data-file menu, the data-file referenced in the menu cannot be the main data-file. You can use the Edit Links option of the File command to change the main data-file.

     3391  No menu defined on this field

The field you specified for a menu edit procedure does not contain a menu.

     3392  Data-file name (filename) used more than once

You have entered the same name for the main and driven data-files in the Edit-Links link definition. Enter different names for the two data-files.

     3393  Field lengths do not match

The link fields you have specified are not the same widths. Specify link fields of the same widths.

     3394  Cannot run link command with less than two data-files

You must specify a main data-file and a driven data-file in Edit Links. If a view has only one data-file, link information is not necessary.

     3395  Driven data-file not found

Within Edit Links, you pressed F6 to show the fields in the driven data-file, but you had entered no name for the driven data-file.

     3396  Main data-file not found

You have not entered a main data-file name within the Edit Links link definition.

     3397  Link structure not fully defined

The driven fields are invalid or missing within the Edit Links link definition.

     3398  Field types do not match

The link fields have different types within the Edit Links link definition. Specify link fields of the same type.

     3399  Unable to execute input order at this time

You cannot execute Input-Order with only one field in the view, or with only a table in the view.

     3400 Cannot change link information at this time

The standard view was not loaded when File Modify was executed. Obtain access to the standard view or recreate using File-Fix View. Rerun File Modify.

     3401 Field must be defined as a key field

The link to (driven) field must be a key field. Make the field a key field and try again.

     3402 Driven fields do not match defined key

The minor keys specified in Edit Links do not match the defined key. Redefine the fields in Edit Links to match the previously defined key.

     3403 Unable to have one data-file in multiple tables

You may not define fields from one data-file to be in more than one table.

     3404 Invalid view/table format

A table cannot exist without referencing a data-file. A view field cannot be the only item outside the table. Redefine the view, adding another data-file, or place a data-file in the table.

     3405 A table may not link to another data-file

In Edit Links, you defined a field from a table to be the driver of a link to another data-file. This is not allowed. Pick a field that is not from a table to be the driver of the link.

     3406 Error rewriting data-file (filename): possibly out of disk space

Automatic restructure failed while writing the specified data-file. Free some disk space and try again. You can exit to DOS from File Modify by pressing Ctrl-O; then free some disk space. You can also press Escape to abandon File Modify altogether.

     3407 Renaming (filename) to (filename) failed

The system was unable to rename the specified data-file.

     3408 Error renaming pix file (filename)

The system was unable to rename the specified PIX (physical index) file.

     3409 Error renaming key file (filename)

The system was unable to rename the specified key file.

     3410 Deleting key for field (field name)

A field within the key was deleted, making the key unusable. The key will be deleted from the data-file.

     3411  Unable to modify:  Data-file in use elsewhere

You must have exclusive access to a data-file to be able to modify it. In a single-user environment, the message is issued if a custom view with a particular data-file attached is loaded, and you execute a command such as File Modify (perhaps to delete a field) on the standard view for that same data-file. Since the active view has a copy of the file in memory, modifying the data-file would make the active view's version obsolete. The message is also issued if, when you attempt to replicate a data-file, you have more than one of its views loaded. In a multi-user environment, the message may indicate that the file is in use at another workstation.

     3412  Number of fields in driven key doesn't match defined fields

The key for the driven file link field already exists and its minor key structure differs from the key structure specified for the driver file link field. The key structures must match.

     3413  Cannot attach data-files to a standard view

A standard view is a "utility" type of view created by SmartWare for each data-file. By definition then, a standard view references a single data-file. If you want to attach multiple data-files to a view, create or modify a custom view for that purpose.

     3414  Create a new data-file or attach an existing data-file first

When creating a new view, you must either create a new data-file (Create Data-File) or attach an existing data-file (Attach Data-File) before you define any data-file fields. If you are not familiar with the sequence of steps required to create a new database, read the section called "Creating a New Database" under "Important Database Concepts" listed in the on-line help Table of Contents.

     3415  Cannot replicate since (filename) is not loaded

The standard view for the data-file was not loaded; therefore, you cannot replicate it. The file may be missing or may have been corrupted. There may not be enough memory to load the file.

     3416  Field size cannot exceed 255 characters

You cannot define the width of a numeric field to be more than 255 characters. This applies to any numeric field, including counter, date, and time fields. Another point to keep in mind is that, unlike alphanumeric fields, numeric fields do not "wrap" to additional lines and therefore must fit in the available area of the view.

     3417  Unable to link from a non data-file field

Neither a view field nor a project processing variable field can be used as a link. Specify a data-file field.

     3418  You must define an error message for the rule

If you select Error Check as the rule type, you must also define a message to be displayed when the equation fails.

     3451  No view in the current window to print

You must have a view displayed in the current window in order to print it.

     3501  Table columns out of order

In your page definition, you specified a value for the left column greater than the value for the right column.

     3502  Table will not fit on page

In your page definition, you specified a size for the table too big to fit on the page.

     3503  Line overflow.  Abandon, or change column width? (a/c)

A line overflow exists. To abandon, press A. To change the width of the column, press C.

     3504  Field [field name] is not on current view

The specified field is not in the current view either because the report definition was not created for the current view or because the current view has been modified since creation of the report definition.

     3505  Three lines required below form for page numbers

In your page definition, you need three lines below the form for page numbers.

     3506  Three lines required below table for page numbers

In your page definition, you need three lines below the table for page numbers.

     3507  New table width is too short for some previously defined columns

In your page definition, you specified a table size too small to accommodate previously defined columns.

     3508  Form and table will overlap on table overflow

In your page definition, the form area is completely hidden by the table area on table overflow.

     3509  Form and table overlap

When you provide for both a form and a table on the Report Page Definition Menu, you can allow the table area to overlap (but not completely cover) the form area. The table area cannot conflict with items (such as fields or labels) on the form.

     3510  Warning: Cannot list all tables

You have defined more than the maximum 14 table areas that can be listed.

     3511  Previously defined offset break or grand total is outside new table  borders

A break or grand-total is not completely within the new (smaller) table area you have defined

     3512  Unknown command

An internal programming error has occurred. Contact Technical Support.

     3513 Invalid profile specified

The paper profile you specified is not valid. Perhaps you have entered the name incorrectly. Press F6 to display a list of available profiles.

     3514 Warning: Form and table may overlap on overflow.

You have specified that both the table and the form should reprint on overflow. If the form is above the table, both will try to print at the top of the page. In this situation, the form or the table should overflow, but not both.

     3550 View must have fields to execute report

To execute Print Report, you must have a view loaded in the current window.

     3551  No table declared for this page

You are trying to specify table data before you have entered the table location on the page definition.

     3552  Columns must be defined before breaks

You cannot define breaks before defining columns.

     3553  No breaks defined for this table

You cannot update or remove a break if no break is defined for this table.

     3554  Grand total not defined

You cannot update or remove a grand total if no grand total is defined for this table.

     3555  Maximum breaks reached

You cannot exceed the currently defined maximum of 15 breaks and/or 99 lines.

     3556  Column must be a view field

You have not specified a field from the view. Do so.

     3557  Non-numeric field

The field specified for a breakpoint summary is not numeric. Summarization cannot occur on a non-numeric field.

     3558  Equation (equation)

The equation has a syntax error.

     3559  Label (name) overlaps first break field

A breakpoint or grand total label cannot overlap a break field unless the label is an equation.

     3560  Starting (position) must be within table

Your breakpoint or grand total starting line or column is not within the table area.

     3561  Cursor is not on a report column

You cannot remove or move a column until you place the cursor in the column.

     3562  Corrupt report definition

An internal programming error has occurred. Contact Technical Support.

     3563  Error loading options

The options screen cannot be loaded because memory is full. Remove some information from memory and try again.

     3564  Move would cause line overflow

The table is not wide enough to move the item without causing a line overflow.

     3565  A heading line is longer than column width

In your column definition, the column width is smaller than a heading line.

     3566  Column width causes line overflow

The table is not wide enough to accommodate the column without a line overflow.

     3567  Title or footing lines must be used in numeric order

Blank lines are not allowed in table titles.

     3568  Title line longer than table width

Your table title line cannot exceed the width of the table.

     3569  Footing line longer than table width

Your table footing line cannot exceed the width of the table.

     3570  No form declared for this page

You cannot specify form information before entering form location/size in the page definition.

     3571  Area will not fit within form's boundary

The area you are duplicating or moving is not completely within the boundary of the form.

     3572  Cursor is not on an area

The cursor must be located in the area in which the procedure will occur before you can initiate a duplication, move, remove, or font change.

     3573  Error loading area options

Memory is full. Remove some information from memory and try again.

     3574  Warning: page number control string too big for area

Text and/or page number will be truncated.

     3575  Neither table nor form defined

You cannot execute a report until the table and/or form has been defined.

     3576  Nothing defined on table

You cannot execute the report until you enter information into the table definition.

     3577  No areas defined on form

You cannot execute the report until you enter area information into the form definition.

     3578  Cannot find table

The report could not be executed because the system could not find a table in the view.

     3579  Table length insufficient for table definition

The report could not be executed because the table as defined would exceed the specified table length.

     3580  Warning: offset break or grand total overlaps table title

To avoid overlapping the table title, move the offset break or grand total farther down the page.

     3581  Invalid report format. (Format) is a version (version) format

The specified report format is incompatible with the current version of SmartWare. Contact Technical Support.

     3582  Area overflow

You cannot execute the report because the form area data is too large, and Flag-on-overflow had been specified.

     3583  Trying to total an alpha calculation

The report cannot be executed because you have specified a total for an Alpha calculation.

     3584  Warning: Offset break or grand total too far right; adjusting

During Report Execute, the system is adjusting an offset break or grand total which is too far right.

     3585  Error reading report definition file

The file may be corrupt. Try copying the file to another name and reading the copied version. If this does not succeed, recreate the file.

     3586  Report not defined or cannot open file

You may not have defined the report whose file you are trying to open. Or perhaps the system could not find the file because you specified the wrong path. This error also occurs if no more file handles are available.

     3587  Error saving report file

Since no definition is available to the system, the report cannot be saved.

     3588  Undefined option

You specified an incorrect option. Try again.

     3589  No totals defined

The system could not run Execute Totals-Only, because it could not find totals to print.

     3590  End page precedes start page

The report could not be executed because the specified ending page number is smaller than the start page number.

     3591  No report fields found on current view

The report could not be executed because no fields specified in the report were found in the current view.

     3592  Table (name) does not exist on view (name)

The report table indicated does not exist on the specified view, making your report unexecutable. In other words, the report table references fields that are not in the data-file. Delete the report table from the report definition before printing.

     3593  Error loading report page options

Report page options could not be loaded probably because of a lack of memory. Clear some room in memory and try again.

     3594  Error unloading page options

Memory is full. Remove some information from memory and try again.

     3595  Form lines out of order

The starting line number is greater than the ending line number in the page definition.

     3596  Form columns out of order

The starting column number is greater than the ending column number in the page definition.

     3597  Form will not fit on page

The page definition cannot be processed because the page is not large enough to accommodate the form.

     3598  Previously defined form does not fit within new borders

The page definition cannot be processed because the new size specified for the form cannot accommodate the information within the form.

     3599  Table lines out of order

The starting line number is greater than the ending line number in your page definition.

     3607  Key [field name] in file (filename) no longer exists

The specified key no longer exists in the specified data-file. Redefine the key or modify the view.

     3608  Cannot use password commands; no data-file in view

You cannot use the Password commands if no data-file exists in the view.

     3609  Data-file (filename) already loaded

You may have tried to load a data-file exclusively when someone else was accessing the same data-file, or you may have tried to load a data-file while someone else had it exclusively.

This message is also issued if you try to load two views referencing data-files with the same name but different paths, or if you try to modify a view attached to a data-file having the same name (but different path) as that of another active data-file. The problem can be the result of a typographical error or the use of a relative path reference (e.g., F:\xyz\sales.db and F:sales.db have the same meaning when the data path is set to F:\xyz).

     3610  Field [field name] not found in data-file

No field in the data-file corresponds to the specified field in the view. Delete the field from the view.

     3611  Error reading view file

The file may be corrupt. Try copying the file to another name and reading the copied version. If this does not succeed, recreate the file.

     3612 Array already exists with variable name

You attempted to create a project file variable when an array already exists that uses the same name. The array must be removed before the view will be loaded.

     3613  Data-file must be restored from backup copy

An error occurred when the system tried to restructure the data-file. The file is in an unknown state, and you should delete the file and restore it from your backup.

     3614 Field type for field (field name) doesn't match data-file type

While the view was being loaded, a discrepancy was discovered in the field type of the specified field. Correct the view with File Modify to make the field type match the underlying data-file.

     3615  Error opening data-file

Perhaps the system could not find the file because you specified the wrong path. This error also occurs if no more file handles are available. Or, you may have permission to access the view exclusively, but someone else is already accessing it. You must have exclusive access to a file to perform certain operations, such as purging.

     3618  View already loaded

The view you specified to load is already loaded.

     3619  Invalid password

The password you entered is invalid. Try again.

     3620  Error saving pix file

If you are using a floppy disk, you may have removed the disk before the save operation was complete. Or you may be out of disk space. Clear space on the disk and try again.

     3624  A file with the same name is already open

The file you specified to open is already open, possibly from another path or drive. If you are using the Data Relate command, the error occurs when you specify a file as a destination but the filename you enter matches the name of a file that is already active.

     3625  Error opening pix file

The system can not find the pix file for the data-file. Regenerate the pix file by executing Data Utilities File-Fix Data-File.

     3626  Corrupt field information

Bad data was found in the data-file. Execute Data Utilities File-Fix Data-File, and if the error persists, restore the data-file from backup.

     3627  Cannot switch to a driver with a different number of bytes

You must use a driver that employs the same encryption format as employed in previous encryption procedures.

     3628  Incorrect view file version

You are trying to load a view file that is incompatible with the current version of SmartWare. The view will have to be recreated.

     3629  Link field [name] no longer exists in data-file (file)

Someone deleted the field that this view was using to link a data-file. Access the data-file through a different view, replace the field, and modify the view as necessary.

     3631  DB conversion failed

The system cannot convert the 3.1 data file.

     3632  Error opening input file

Perhaps the system could not find the file because you specified the wrong path. This error also occurs if no more file handles are available. Or you may have permission to access the view exclusively, but someone else is now accessing it.

     3633  Duplicate records skipped

Because duplicate keys are not allowed, duplicate records were skipped and will not appear in the file.

     3634  Field must be a Data-file field

You cannot import data into a View field or a Project Variable.

     3636  You may only import into a view with a single data-file

You have more than one data-file in the current view. Only a single data-file view can receive imported data.

     3637  Too many memo fields in dBase file

SmartWare converts every dBase memo field to a 4000 character alphanumeric field. SmartWare Database allows a maximum of 31,000 characters per record. The combined length of the memo fields plus the remainder of the record exceeds the 31,000 character limit.

     3638  Error opening dBase file

Perhaps the system could not find the file because you specified the wrong path. This error also occurs if no more file handles are available.

     3639  Error reading dBase file

The file may be corrupt. Try copying the file to another name and reading the copied version. If this does not succeed, recreate the file.

     3640  Error opening dBase memo file

The system can not find the dBase memo file in the same directory as the file to import. Make sure the memo file is present in that directory.

     3641  File is not a dBase file

The file you specified is not a dBase file. Specify a dBase file.

     3642  Error reading dBase memo file

The system can not read the memo data from dBase. Make sure the file is present, or copy a new file to the directory.

     3643  Error converting calculation on field [field name]

The system is unable to convert the calculations in the 3.1 data-file. Execute File Modify and create the calculation in the new file.

     3644  Error reading 3.1 data-file

The 3.1 file may be corrupt. Try copying the file to another name and reading the copied version. If this does not succeed, recreate the file.

     3645  Error writing new data-file record

The system could not save the data-file record as it was importing.

     3646  Error opening 3.1 data-file

The system cannot open the 3.1 file. Someone else may be accessing the file. Wait and try again.

     3647  File is not a 3.1 data-file

The file you are trying to import is not a 3.1 file.

     3648  Corrupt field information in 3.1 data-file

Bad data was found in the 3.1 file. Execute Utilities File-Fix in the 3.1 Database, and if the error persists, restore the file from backup.

     3649  Unexpected end of file reading 3.1 data-file

An unexpected end of file reading occurred for the 3.1 file. Execute Utilities File-Fix in the 3.1 Database, and if the error persists, restore the file from backup.

     3650  Error closing 3.1 pix file

If you are using a floppy disk, you may have pulled out the disk before the closing procedure was finished.

     3651  Error closing 3.1 data-file

If you are using a floppy disk, you may have pulled out the disk before the closing procedure was finished.

     3652  No records in 3.1 data-file

No records exist in the 3.1 file you are trying to import.

     3653  Error converting keys. Try creating on your own.

The keys in the 3.1 file were not converted, but the file conversion has succeeded. Create the keys using the new Database.

     3654  Dbase fields (field) and (field) have same names--Export of data terminated

While converting SmartWare names to Dbase field names, a duplicate name was encountered. Rename the field in SmartWare. (Any non-alphabetic character is converted to "_".)

     3655  Export of data failed

The export was unsuccessful. No output file was created.

     3701  Record number out of range

The record number you entered is out of range. Enter a record number in range.

     3702  Invalid window number

The window number you entered is invalid. Enter a valid window number.

     3703  Invalid number of records in index file

The index file is corrupt. It claims that there are more records in the index than are in the file. Recreate the index.

     3704  Table not on current view

The table area you have specified to go to is not in the current view.

     3705 Can't goto view while current view record is locked

You cannot go to another view while the current record is locked. Unlock the record (Cancel Record), or flush the locked record to disk with Goto Record Next, and then go to the view you wish.

     3711  Field must be on current view

The field you specified is not in the current view. Specify a field in the current view.

     3712  Partial finds only valid for alpha and inverted name fields

You specified a partial find for data in a field that is neither Alpha nor Inverted. If you wish to execute a partial find, the field specified must be either Alpha or Inverted.

     3713  All fields to be searched must be the same type

You have specified fields of different types to be searched. Specify only fields of the same type.

     3714  No search data entered

You have not entered any search data.

     3715  Invalid character in find options

You have entered a letter for a Find option that is invalid.

     3716  End of search without finding data. Press any key to continue.

The search concluded without finding any data. Press any key to continue.

     3717  Cannot search table fields and non-table fields in one command

You can either search multiple table fields or multiple non-table fields in one iteration of the Find command.

     3718  Cannot search multiple tables in one command

You can only search multiple fields in one table at a time.

     3719  Data not found; displaying closest match. Press any key

The optimized search concluded without finding an exact match. The record containing data the most similar to the search data is displayed. Press any key to continue.

     3721 No active records to send

All of the records to be sent are deleted records.

     3722 Field list specified contains too many characters

The character string comprising the list of fields for Data Send or File Export contains too many characters. One way to shorten the list is to use the vertical bar (|) to specify a range of consecutive fields, e.g., [Name|Zip].

     3723  Error reading sent data

The file may be corrupt. Try copying the file to another name and sending the data again. If this does not succeed, recreate the file.

     3724  Communications not available

You cannot send data to Communications, because it is not available.

     3725  Spreadsheet not available

You cannot send data to the Spreadsheet, because it is not available.

     3726  Wordprocessor not available

You cannot send data to the Wordprocessor, because it is not available.

     3727  Too many fields in data sent

The number of fields exceeds the maximum number allowed in a file (1000). Send less data.

     3731  Window too small for border

The window is too small to place a border around it.

     3732  Cannot close window

This window cannot be closed because it would be absorbed by another window. Try closing an adjacent window first.

     3734  Cannot close a single window

When only one window is open, that window cannot be closed.

     3735  Cannot zoom a single window

When only one window is open, you cannot zoom that window.

     3744  A zoomed window cannot be closed

You are trying to close a zoomed window. Unzoom the window before trying to close it.

     3745  Window too small

The window must be at least two lines by 12 columns.

     3747  Window already linked

You are trying to link a view that is already linked.

     3748  Circular reference; view cannot be linked

You tried to link a view to another view which links back to the original view. You cannot have circular linked views.

     3749  Link file not open

The file to link to has not been loaded. Load the view and try again.

     3751  Error creating key file

You may have achieved the maximum number of file handles, or not enough directory space is available. Clear some space from memory and try again.

     3752  Total key length must be under 500 characters

You have specified a key length that exceeds 500 characters.

     3753  Only fields from data-files can be used as keys

You have specified one or more items not from data-files as keys. All keys must be fields from data-files.

     3754  Major and minor keys must be from the same data-file

One or more of your specified keys is from a different data-file. All major and minor keys must be from the same data-file.

     3755  Maximum number of key fields already defined

You have exceeded the maximum of 15 key fields.

     3756  Field is already a key field

The field you are trying to make a key field is already a key field.

     3757  Key file already exists

The key file you specified already exists. Delete it and try adding the key again.

     3758  Unable to claim data-file for field (name)

You have marked one or more keys for deletion; however, SmartWare is unable to obtain exclusive access to the data-file for the field indicated in the message, and, therefore, cannot delete that key. Use the File Load Exclusive command to load the file exclusively. Then re-execute Order Key Delete.

     3759  Invalid key field entered

The field you specified as a key field is not a key field.

     3760  Key field (name) is in use.  Cannot delete the key.

You cannot delete the specified key while its key field is in use. Change the order of the view so that the key field is not in use and try again. If another view accesses the key, the other view must be unloaded before proceeding.

     3761  Invalid field length

In defining the key, you entered a field width greater than the width of the field. Try again entering a smaller width.

     3803  Invalid sort definition filename

The system can not find or create the specified filename. Try again, entering a valid path and filename.

     3804  Missing sort index filename

You tried to execute a sort that either does not exist or for which you did not enter a name for the definition file.

     3805  A view is already ordered by this index file

You tried to execute a sort using an index file that is being accessed. Try again, using a different index filename.

     3806  Error opening sort definition file

Perhaps the system could not find the file because you specified the wrong path. This error also occurs if no more file handles are available.

     3807  Error reading sort definition file

The file may be corrupt. Try copying the file to another name and reading the copied version. If this does not succeed, recreate the file.

     3808  Invalid number of keys in sort definition file

The sort definition is corrupt or you have loaded the wrong view. The number of fields in the sort definition must be fewer than the number of fields in the view. Try again, using a different view or recreate the definition.

     3809  Invalid field in sort definition file

The number of fields in the sort definition file is larger than the number of fields in the view. A field referenced in the sort definition may have been deleted from the view. Correct the sort definition, or use a different view.

     3810  Invalid length in sort definition file

The width of one field in the sort definition is specified 0 or greater than the width of the field. Recreate the definition.

     3811  Invalid ascending/descending flag in sort definition file

The definition is corrupt. Recreate the definition.

     3812  Error opening work file

The system could not create the sort temporary file on the paging path. Delete some files on the paging path to make room.

     3814  Insufficient disk space. (Number) bytes needed

Not enough disk space is available to perform the sort operation. Clear some space on the disk and try again.

     3852  Error opening index file

Perhaps the system could not find the file because you specified the wrong path. This error also occurs if the index is already being used. For example, in a single-user environment, the message is issued if another view is already ordered by the index. In a multi-user environment, the message can also be issued if another user is using the index.

     3853  Index file does not match main data-file

The name stored in the index file does not match the current name of the view or main data-file. Generate a new index for this view.

     3854 Key must be from the main data-file

You attempted to execute Order Change Key using a key field which is not in the main data-file. Specify a key field from the main data-file.

     3901  No data-files loaded

The command that you are attempting to execute (such as File Password Data-File Attach) requires you to select the name of a data-file attached to the current view. Load the view for the data-file you want to process and try again.

This message is also issued if you execute File Display-Active and no data-files are loaded.

     3902  No data-file in current window

You cannot perform this operation without a data-file in the current window. Place a view in the current window and try again.

     3903  Error writing definition file

You may be out of disk space. Clear disk space and try again. Or, if you are on a network, you may not have write permission.

     3904  Cannot lock record

Someone else is accessing the record and it cannot be locked. Wait and try again.

     3905  Data-file limited to 50 records

You cannot enter more than 50 records into a data-file using the free-ware version.

     3906  Command interrupted by user

Escape was pressed to stop command execution.

     3907  Duplicate key value exists

This message is issued if you try to enter a new record with the same key value as one already in the data-file. Change the key value if you want to save the record. The message is also issued if you try to add a key (using Order Key Add) on a field that already contains duplicate information in two or more records.

     3908  Error closing file

If you are using a floppy disk, you may have pulled out the disk before the closing procedure was finished.

     3909  No data-files attached to this view

You tried to attach a field when no data-files were attached to the view. Attach a data-file before trying to attach a field.

     3910  Invalid password entered

You failed in three attempts to enter a valid password.

     3911  No fields to display

You tried to perform an operation that displays fields, but no fields are available to display.

     3912  Changes will affect this session only

Someone at another workstation within your network group is currently using the definition files (extension ".def"). Any changes you make will affect the current session only and will not be retained after you exit SmartWare Database. Your network administrator can create separate user directories so each user can have a set of definition files that cannot be altered by any other users in your network group.

     3913  Error:

Miscellaneous calculation error.

     3914  Key file error

A key file error has occurred. Make sure the key exists. If it does, execute Order Key Rebuild.

     3915  Error opening key file

The key file may be locked, or it may be nonexistent or damaged. Wait and try again. If the file is not active, execute Data Utilities File-Fix, load the file, then execute Order Key Rebuild.

     3916  Key length too large for node size

A key error has occurred. Execute Order Key Rebuild.

     3917  View (name) is not loaded

You cannot perform this function until the specified view is loaded.

     3918  Error re-reading view file

An error occurred when the view file was re-read. Execute a File Load to load the view, and see if the view was damaged.

     3919  Assignment not allowed

You have made an invalid assignment in assigning to a read-only field, or assigning Blank to a mandatory field.

     3920  Error creating pix file

An error occurred in creation of the pix file. Try repeating the procedure within which the pix file is created.

     3921  Invalid numeric format

You have specified an invalid numeric format in the Database preferences. Correct the error.

     3922  Record must be locked before making changes

During project processing, a record must be locked in order to be changed.

     3924  Cannot delete server data file (error number %s)

The server data file could not be removed from the server.

     3925  Cannot connect with server or data file

SmartWare could not find the data file. If the data file is located on a SmartWare Server, make sure the server is running.

     3926  Your node key does not allow you to create or use server data files

You must upgrade to Client/Server SmartWare to use this feature.

     3927  Create an ActiveX control first

You must first create an ActiveX control.

     3928  No ActiveX controls loaded

There are no ActiveX controls on the current view.

     3929  Could not obtain a record lock (another user may have modified this record as part of a Server Transaction)

SmartWare could not lock the record for updating. This can happen when another user has updated this record as part of a Server Transaction. You must wait until the other user has performed a Commit or Abort.

     3930  Could not begin a transaction for this data-file

An error occurred when attempting to begin a Server Transaction.

     3931  Could not commit a transaction for this data-file (usually a duplicate key)

An error occurred when attempting to commit a Server Transaction. This can happen when the Transaction has introduced a duplicate key.

     3932  Could not abort a transaction for this data-file (usually because there was no transaction active)

An error occurred when attempting to abort a Server Transaction. This can happen when there is no tranaction active.

     3933  There are no active transactions

You must create a Server Transaction with the Begin command before executing any other Server Transaction commands.

     3934  Could not set a save point for this transaction

An error occurred when trying to set a save point for this Server Transaction.

     3935  Could not restore a save point for this transaction

An error occurred when trying to restore a save point for this Server Transaction.

     3936  Could not delete this data file. You must be in the ADMINS group to delete server data files

An error occurred when trying to delete a server data file. Ensure that your User ID is part of the ADMINS group.

     3937  The ActiveX control is not registered

There was a problem loading an ActiveX control on this view. Make sure that the ActiveX control is registered.

     3949  Key file error #:

An internal key file error has occurred.

     3950  Key value (data) for data-file (filename) already exists

The data displayed already exists in the specified data-file. You must change the record before it can be saved.

     3952  Cannot process external link; view is in index order

The view you are working within is linked to another view in index order. You can not link to a view in index order. Reorder the linked view in physical or key order.

     3953  Cross-Tab has exceeded the maximum of (size) rows; command aborted

The internal limit on number of unique rows of data in the Cross-Tab command has been exceeded. The command has been aborted and partial results are not available. You will have run a query to restrict the row-automatic field to a smaller range of values.

     3954  Error making file header

During the attempt to change the password, an error occurred as the system tried to write new heading information. The password was not changed.

     3955  Error writing db header

During the attempt to change the password, an error occurred as the system tried to write new heading information. The password was not changed.

     3958  No records in data-file

You cannot perform this function without records in the data-file.

     3960  File not found

The view was not found among the list of active views.

     3961  Invalid filename

You entered an invalid filename. A filename can contain up to 8 characters and no blank spaces. Try again.

     3962  Cannot modify file

Someone else may be accessing the file. Wait and try again later. You might also get this message if the file you have specified cannot be found.

     3963  Error reading definition file

The file may be corrupt or located at a bad spot on the disk. Try copying the file to another name and reading the copied version. If this does not succeed, recreate the file.

     3964  Error deleting file

An error occurred when the system tried to delete a file created by the system. The file, which may have become corrupted, will be left on disk. This message is also issued if the file is in use elsewhere.

     3970  Insufficient memory

Not enough memory is available to perform this operation. Clear some information from memory and try again.

     3971  Invalid field entered

You entered a field or field list that the Database is unable to recognize or interpret properly. If you typed the entry, you may have misspelled it.

     3972  Invalid field

An invalid field was referenced in the command you are trying to execute.

     3973  Error closing pix file

If you are using a floppy disk, you may have pulled out the disk before the closing procedure was finished.

     3974  Error closing data-file

If you are using a floppy disk, you may have pulled out the disk before the closing procedure was finished.

     3975  Data-file already exists

You are trying to create a new data-file whose name already is used for another data-file on the disk. Delete the old data-file or use a different name for the new data-file.

     3977  Source file not open

The system could not find the view to copy data from.

     3978  Error writing data-file

The system could not save the data-file. You may be out of disk space.

     3979  Error opening view file

Perhaps the system could not find the file because you specified the wrong path. This error also occurs if no more file handles are available. Or you may have permission to access the view exclusively, but someone else is now accessing it.

     3980  Destination file already exists

The name you specified for the file to create already is used for another file. Use a different filename for the new file or delete the old file.

     3981  Error creating file

The file may already exist, or you may have already created the maximum number of files permitted in a directory.

     3982  Error creating view screen

The view screen could not be created because of an invalid path entry, an invalid filename entry, or a lack of sufficient memory. If neither of the first two caused the error, clear some memory before trying again.

     3983  View screen already exists

In creating a view, you have specified a filename that is already used. Use a different name.

     3984  Error creating data-file

The file may already exist, or you may have already created the maximum number of files permitted in a directory.

     3985  Error opening output file

Perhaps the system could not create the file because you specified the wrong path. This error also occurs if no more file handles are available, or if an invalid filename is entered when exporting or when writing a cross-tab to a file.

     3986  Error writing file

You may be out of disk space. Clear disk space and try again. Or, if you are on a network, you may not have write permission.

     3987  Invalid color number

You have entered an invalid color number. Enter a valid color number.

     3988  Database internal error

The Database is in an indeterminate state. Quit to DOS as soon as possible.

     3989  Data-file not found in current view

You entered a data-file name that is not in the view.

     3990  No fields on view

This command must operate on an existing field.

     3991  Definition file already exists

You have entered a name for a cross-tab or relate definition file that already exists. Enter a different name, or delete the existing definition file.

     3992  Field (name) not found

The field you specified in a transaction or cross-tab definition cannot be found on the view.

     3993  Cannot repeat field in first record

You tried to repeat entry of data from the previous record. But you are on the first record and no previous record exists.

     3994  Definition file not found

The system could not find the relate or report definition file you are trying to delete or load. Check your entries of path and filename before trying again.

     3995  Error opening definition file

You may have entered the wrong path. There may not be enough handles or directory entries available.

     3996  Error creating definition file

The system could not create the query or relate definition file. Perhaps you entered a filename already used for another definition file.

     3997  File not found

The view to unload was not found among the active list of views.

     3998  Invalid data-file name

You have not specified the correct filename for the view. Try again, using the correct filename.

     3999  Error reading data-file

The file may be corrupt. Try copying the file to another name and reading the copied version. If this does not succeed, recreate the file.


SmartWare Spreadsheet Command Reference

This section of on-line help explains the purpose and format of each SmartWare Spreadsheet command. Menu keywords are presented in this section in the same order in which they appear on the SmartWare Spreadsheet keyword menu.

Four of the keywords, Tools, Help, Remember, and Quit, are applicable to all SmartWare modules. Discussions of these keywords are general, with details being limited to Spreadsheet usage. For more information on the use of these commands, refer to Software System Manual and Project Processing Manual.


Basic Concepts

Before you begin, there are several concepts and techniques with which you should be familiar. If you have not used an electronic spreadsheet before, we suggest that you read the Spreadsheet Manual and that you also use the Spreadsheet Tutorial. If you are familiar with electronic spreadsheets, the sections that follow will provide brief descriptions of SmartWare Spreadsheet concepts and techniques.


Data Entry and Command Modes

SmartWare has two operating modes. Use Data Entry mode to enter information into the worksheet. Use Command Mode to execute SmartWare commands.

Press Escape to switch from one mode to the other. From Data Entry mode, press "/" to execute one command and return immediately to Data Entry. You can also use the Quick Keys Alt-Y to access Data Entry mode, and Alt-Z to access Command mode.


 When the program is in Data Entry Mode, the Enter: prompt is displayed, signifying that the Spreadsheet is ready to accept data. You can enter text, numeric values, or formulas into the cells.

Entering Text or Numbers
Entering Formulas

If you enter Command Mode (by pressing Escape or "/"), you will see the following keyword menu:

     Sheet  Edit  File  Layout  Print  Graph  Tools  Window   Help Remember  Quit


Selecting a Graph Type

There are 21 distinct graph types. Nineteen are based on plotted worksheet data. One is composed of text only (text graph). And one is composed of existing CGM and GMF files combined to form a single image (composite graph).

The graph types are divided into six classes as follows:


 Using Commands. To execute a command, select from the keywords and the appropriate keyword options.

To cancel a command while selecting options or answering prompts, press Escape. To repeat execution of the previous command, press F9. To edit the format of the previous command, press Alt-X. The revised command will be executed when you press Enter.

Quick Keys are specially defined keys that execute certain common commands. They are function keys, such as F10, or combinations of keys, such as Alt-S, Ctrl-O, and Alt-F7. When using key combinations, hold the first key down while you press the second key. Press F2 to page through a quick reference list of keys, shown in the Control Area of the screen.


 Entering Data. While in Data Entry mode, you can enter text, numeric values or formulas into cells. If the first letter of the entry is an alphanumeric character (such as a letter, a space, or quotation marks), SmartWare considers the entry to be text. If the first character is a number or a currency symbol, the entry is considered to be a numeric value. Use "@" or "#" to enter dates. Use ":" or ";" to enter time.


 Formulas and Recalculation. If the first character of an entry is an equal sign (=), the entry is a formula. A formula can contain numbers, cell or block references, SmartWare functions, parentheses, and operators (such as +, >, or AND). Valid arithmetic operators are as follows:

Operator | Meaning
+ | Addition
- | Subtraction
* | Multiplication
/ | Division
^ | Exponentiation

Many SmartWare functions also allow the use of relational operators and logical operators. A relational operator expresses a relationship between two items. Logical operators are used to connect and evaluate pairs of expressions. Valid relational and logical operators are as follows:

Operator | Meaning
= | equal to
> | greater than
< | less than
>= | greater than or equal to
<= | less than or equal to
<> | not equal to
! | contains (text)
!! | does not contain (text)
== | compare text, ignoring case
AND | returns TRUE if both logical expressions are true
OR | returns TRUE if either logical expression is true

Refer to Formula Reference Manual for additional information on operators and for complete instructions on the use of SmartWare functions.

You can press F5 to recalculate only those formulas requiring recalculation (minimal recalculation), or Shift-F5 to force the recalculation of all formulas in the current worksheet.

Sheet Calc-Mode

You can enter a formula in a cell by typing the necessary values, operators, and cell references. You can also use the pointing technique to mark cells to be used in a formula.


Cell References

Cells are identified by their locations. For example, "r1c1" refers to the cell at the intersection of row 1 and column 1. To indicate a range of cells, use a colon to separate the start and end points. The reference "r1:5c2" means "rows 1 through 5 in column 2." "Rows 1 through 5 in columns 2 through 6" is written "r1:5c2:6."

Naming Cells. You can assign names to cells or blocks of cells. Then, while building a formula or responding to a prompt, you can simply enter the name instead of the reference.

Sheet Name


 External Worksheets. Formulas and some commands can refer to cells in active worksheets other than the current worksheet. To refer to an external worksheet, enter the filename of the worksheet, followed by a period, followed by the cell or block reference or name.

Examples:

     income.r4:18c2

     income.qtr1


Absolute and Relative References

An absolute cell reference refers to one particular cell or block of cells. Use brackets to indicate absolute references: r[1]c[1]. A relative cell reference refers to where a cell or block of cells resides in relation to a formula cell. Omit brackets to indicate relative references: r1c1. A combination reference contains both: r[1]c2.

The use of absolute or relative references in a formula has no effect on the calculation of the formula. Absolute and relative references are used only by the Edit Copy command to determine how a formula is to be copied. When you copy an absolute reference, you literally use the same reference. When you copy a relative reference, the reference is adjusted to fit the destination.

For example, if r1c1 contains a rate (15%) and r2:3c1 contain dollar amounts, a percentage formula in r2c2 could be "r[1]c[1]*r2c1." If you copy the formula down to r3c2, you still want to use the rate in r[1]c[1], but you want SmartWare to adjust the new formula to use the dollar amount from r3c1.


Editing Cells and Formulas

After data has been entered into a cell, the contents of the cell can be revised without retyping the entire entry. To access the Cell Editor and edit the contents of a cell (whether text, value, or formula), press Alt-E.

The Formula Editor is available for entering or revising formulas, especially large or complex ones. To access the Formula Editor, press Alt-F.

Edit Edit-Cell
Formula Editor


Moving the Highlighter

To move the highlighter around the worksheet, use the cursor movement keys: Up-Arrow, Down-Arrow, Left-Arrow, and Right-Arrow. To move to the top row in the current column, press Home. To move to the bottom row of the current column, press End. To move the highlighter to r1c1 (or to the first cell not part of a fixed title), use Ctrl-Home. To move the highlighter to the last row containing data in column 1 (or the first column not part of a fixed title), use Ctrl-End. You can also use Page-Up and Page-Down to move up or down a screen at a time.

To move the highlighter to a specific cell, press F4, then C, and specify the cell.


Marking Blocks

A cell or a block of cells can be specified when building a formula in Data Entry Mode or when executing a command. At the command prompt Enter name or block reference:, you can respond in one of several ways.
*** Type the block's name and press Enter.
** Select a named block from a prompter listing that will be displayed when you press F4.
** Type the block reference (i.e., r4:12c2:5) and press Enter.
** Use the "pointing technique" to mark the block. Move the cursor keys to "point" to the cells that are to be in the block. The highlighter expands, covering the included cells. Press F2 at any time to specify a new starting point for the definition; this is called "dropping anchor." Press Enter to complete the block definition.
** A block can consist of one cell. If the block to be defined is the current cell, just press Enter. Otherwise, move the highlighter to the desired cell, press F2 to drop anchor, then press Enter.

You have the same options when building a formula in Data Entry Mode. In addition, F3 is a toggle key controlling the use of absolute and relative cell references in the formula.


Marking Rows and Columns

Some commands ask you to specify rows or columns. At the prompt Enter number of rows:, you can type a number and press Enter. Or you can press Down-Arrow to expand the highlighter to cover the number of rows to be included. If you go too far, you can press Up-Arrow to decrease the number of rows, but you cannot drop anchor. Press Enter to complete the definition.

At the prompt Enter number of columns:, you can type a number and press Enter. Or you can press Right-Arrow to expand the highlighter to cover the number of columns to be included. If you go too far, you can press Left-Arrow to decrease the number of columns, but you cannot drop anchor. Press Enter to complete the definition.


Definition Menus

Some commands allow you to define settings from a list of options and prompts, called a "definition menu." Select an option by positioning the highlighter over it. Respond to a prompt by entering the information in the field next to the prompt. Several keys are available to help you define settings.
*** For help, press F1.
** To move around the menu, use the cursor movement keys.
** To move the highlighter one option to the right, press either Spacebar or "+". To move the highlighter to the left, press Backspace or "-".
** To edit the contents of a field without retyping the entire entry, press F2. You can move the cursor within the field and make necessary changes. Insert Mode can be toggled on or off by pressing Insert. Press Enter to complete the entry.
** To blank the contents of a field, press F3.
** To specify an area of the worksheet, enter a name or a block reference. If you prefer to point to a block or block name, press F6. The worksheet appears, allowing you to mark the block or select a block name. Pressing F2 while marking a block drops a new anchor. When you press Enter, the definition menu returns; your selection has been recorded in the field.
** In some cases, pressing F6 provides a list of available options from which to select.
** To record the settings and leave the definition menu, press F10. Press Escape to abandon the definition.


Prompter Listings

Many commands provide prompter lists of available files. Select a file by positioning the pointer next to its name and pressing Enter. You can also type the name in response to the prompt.

Prompter listings provide other information and options. Refer to Software System Manual for additional instructions.


Layout Commands

The Layout commands control the presentation of values and text on your worksheets. The height and width of cells can be changed as necessary. Data can be centered in a cell or aligned to the right or left. Values can be displayed with or without currency symbols and commas. They can be displayed as numbers, dates, time, bar symbols, percents, or in scientific notation. A coded map showing the location of the various cell-types in your worksheet can be produced.

In addition, you can define and use up to 64 fonts in your worksheet.

Options for the Layout keyword include the following:

Alter-Shading. Control shading of cells
Cell-size. Controls the height and width of one or more cells.
Default. Controls the format for new entries.
Format. Changes format of existing value data and presets format for new value entries.
Justify. Controls the alignment of existing text and value entries.
Lines. Control lines border of cells.
Set-Font. Controls the use of fonts in a worksheet.
Worksheet-Options. Provides a definition menu for setting the format for new entries in the current worksheet or future worksheets. Also allows specification of print settings.


Layout Alter-Shading

The Layout Alter-Shading command, as well as the Layout Lines command, can enhance the design and appearance of printed worksheets and reports.

Shading in your worksheet is not visible on the screen. To actually view shading, print the file to the screen or send it to the printer. However, information about the current cell's attributes is displayed on the status line following the word Shade. The characters codes used to represent shade attributes are described in the following list:

L - Light shading
M - Medium shading
D - Dark shading


Edit

The EDIT command opens a screen that displays existing shade attributes in your worksheet. This screen consists of a pointer and two columns: the first column indicates the shade level and the second shows its position in standard spreadsheet coordinates.

You can change the position of any shade level by pointing to it and entering in new coordinates. As an alternative, select the F6 Button, or key, to block mark cells. Block marking is completed when enter is pressed (mouse users can click on the ENTER message in the menu area). When you are satisfied with the modifications made, select F10.

Note: Shade levels themselves cannot be altered only repositioned.


Clear

The CLEAR command will remove shading from cells in a selected area. This can be done by blocking an area or, by selecting ALL, you can remove all shading from your worksheet.


Shade

First, select one of the three available levels of shading: Light, Medium, or Dark. Following this, select the cells that you wish to shade by either block marking or choosing the ALL option.

Note: When editing ALL attributes, the displayed row and column values will be r9999c999, even though the printed output only shows the shading in the actual worksheet. This feature allows the shaded area to expand or contract when the worksheet's size is changed.


Layout Cell-Size

The Layout Cell-Size command sets the width and height of cells. The default width for cells is 10 characters (72 points). The default height for cells is 12 points. Adjusting cell width or height can produce a more readable worksheet.

Cell width is measured in characters, points, or inches. Cell height is measured in points or inches. The unit of measure for each dimension is controlled by the Cell Size settings on the Layout Worksheet-Options menus.


Layout Cell-Size Width

Layout Width

The Width command is used to change the column width of columns in a worksheet. The width of a column is determined by the number of character positions in the column, the number of points, or number of inches. If cell-size is measured in characters, width is the maximum number of characters that will be displayed in the column. You can specify a column width from 0 to 80 characters. A negative width is not allowed, nor is a width wider than your screen.

When you change the width of a column, the data in the cells remains intact. The width of the cell affects only the display of the contents of the cell. If you enter text that requires more characters than the cell width allows, SmartWare uses the cell to the right to fully display the "long-text" string. However, if the cell to the right of the current cell contains data, display of the long-text string is truncated.

When values requiring more characters than the cell width allows are entered, the value is displayed as a series of asterisks across the width of the cell.

Designating a column width of 0 is another way of "hiding" a column. A column having 0 width is neither displayed on your screen nor printed when the worksheet data is printed. Unlike the Edit Hide command, setting column width to 0 with the Layout Cell-Size Width command "hides" both the column and the column number.

The cell highlighter does not enter columns having 0 width. To make a 0 width cell the current cell, use the Sheet Goto Cell command to go directly to the "hidden" cell.
NOTE: You cannot define all columns in the worksheet as 0 width columns.

The pulldown menu version of this command only allows for block mark editing.


 Before you select either the Columns or the All option, SmartWare prompts you to Enter width:(unit of measure). Type a value representing the number of characters, points, or inches to be used as the cell width.


 Columns. If you select the Columns option, SmartWare prompts you to enter the number of columns to be changed. Press Enter to select the current column only. If you enter a value greater than 1, the current column and columns to the right of the current column are changed to reflect the width you entered.

Row-Column Marking


 All. The Layout Cell-Size Width All command changes the width of all worksheet columns to the size specified.


Layout Cell-Size Height

Layout Height

The Height command adjusts the height of cells to the point or inch setting you specify. Controlling cell height allows you to space rows for better readability when the worksheet is printed using the Enhanced option of the Print command. Changing cell height will not affect the way cells are printed when using any other option of the Print command, nor will it affect how cells are displayed on your screen.

The pulldown menu version of this command only allows for block mark editing.


 At the prompt, specify the height to use. Cell height can range from 1 to 300 points, in one-point increments, or any inch measurement up to four inches. A cell height of 0 is not valid.


 Rows. To change the height of particular rows, select the Rows option. You are asked to enter the number of rows. Type the number, or press Down-Arrow or Page-Down to mark the rows.


 All. To change the height of all rows in the worksheet, select the All option.

Row-Column Marking


Layout Default

The Layout Default command controls the default display of all new entries in a particular worksheet. You can specify text and value settings prior to beginning a new worksheet so that all entries in the worksheet conform to those settings.

By executing the Layout Default command, you preset formats for the current worksheet only, leaving intact for future worksheets the standard formats you routinely use.


Compared to Worksheet-Options

The Layout Default command offers many of the same settings as the Layout Worksheet-Options menu. The Layout Worksheet-Options New-Sheet menu defines settings that will affect all future worksheets. Use either the Layout Default command or the settings in the Layout Worksheet-Options Current-Sheet definition menu to override the New-Sheet settings for new entries on the current worksheet.

When you select Layout Default, SmartWare prompts you to specify whether you want to format text or values.


Layout Default Text

The Layout Default Text command sets the default format for new text entries in the current worksheet. You can format text to be left-aligned, centered, or right-aligned. With Layout Default Text, the new alignment format that you specified will not be evident until you enter new text into your worksheet.


Layout Default Values

Layout Numeric Default

This command (both are the same) sets the default format for new value entries. A value can be displayed as a bar representation of a number, as a date, as time, as scientific notation, as currency, as a numeric value, or as a percent.


 Many of the Layout Default Values options allow you to specify the following format settings.
** Display of numbers with or without commas, or "thousand separators."
** Presentation of negatives: with a minus sign; enclosed in parentheses; followed by "cr"; or followed by "cr" with positive numbers followed by "db".
** Display of cells containing only zeros: show the zeros or show blank cells.
** Decimal precision from 0 to 15 decimal places.


 In addition, the Layout Default Values commands allow you to define the default alignment for value cells. Select Left, Right, or Center.

The Layout Default Value options are as follows:


 Bar. The Bar format displays numeric entries as a series of symbols representing the value. Positive numbers are represented by "+" symbols. Negative numbers are represented by "-" symbols. A value of 0 is displayed as a period. If the cell is not wide enough to display the bar, it is filled with asterisks. Bar cells can be centered, or aligned to the right or left.

Table 9-5
Value | Displayed As
5 | +++++
-7 | ----------
0 | .
100 | **********


 Date. The Date format enables you to define all new value entries in the current worksheet as dates to be presented in a particular date format. The date formats are those you defined in Tools Preferences Global. You will also specify alignment for dates.


 When you select the Date option, choose either Date1, Date2, or Date3. The formats represented by these selections are controlled by settings on the Global Preferences menu, accessed with the Tools Preferences Global command. Positive integers will be converted to dates in and after 1900. Negative integers will be converted to dates before 1900.


 Time. The Layout Default Values Time option allows you to define all new value entries as time entries in AM/PM or 24 hour time format. You will also specify alignment for time entries. The fractional portion of any value will be converted to and displayed as time.


 E-Notation. If you select the Layout Default Values E-Notation command, all new numeric entries you make will be displayed in scientific notation (i.e., 256 is displayed as 2.56 E+02). Although a numeric entry is displayed in scientific notation within the cell, it is represented as a numeric value in the Control Area.


 Currency. The Layout Default Values Currency command allows you to display all new value entries with a currency symbol. The currency symbol used, and its location is determined by settings in Tools Preferences Global. A currency entry is represented as a numeric value in the Control Area when you highlight its cell.


 Numeric. The Layout Default Values Numeric command enables you to display all new values as numbers.


 Percent. The Layout Default Values Percent command allows you to display all new value entries as percents. For example, the entry ".22" would be displayed as "22%," and ".221" with one decimal place selected would be displayed as "22.1%."


 General. The Layout Default Values General command allows you to display all new value entries in a general numeric format. Nonsignificant trailing zeros are suppressed. A value with a large number of positions to the left or right of the decimal is converted to E-Notation, as is a number too large to fit within the cell width.


Layout Format

The Layout Format command changes the display of existing value entries. You can set your Layout Default preferences prior to beginning a new worksheet so that all new entries in that worksheet conform to your format. But to change the appearance of specific cells once data has been entered, you must reformat the cells using the Layout Format command. Layout Format affects values only. Use Layout Justify to reformat text entries.

The Quick Key for the Layout Format command is Alt-Q.


Preformatting

Value cells are defined for the entire worksheet before any entries are made by executing the Layout Default command. There are times, however, when you know you do not want every cell to be formatted the same way. For example, a worksheet might be formatted as numeric, but the entries on the first row and the total lines should be formatted as currency, displaying the dollar sign.

Specific cells that are to contain value entries (not text entries) can be preformatted before you enter data by selecting Layout Format Block. A block can be one cell or many cells. Preformatting blocks of value cells allows you to set individual formats for specific areas of the worksheet when a single format for the entire worksheet is not adequate.
Comment: Only the Block option can be used for preformatting.

The command is entered exactly the same as when reformatting existing value blocks.


Layout Format Options

When you select the Layout Format command, SmartWare asks you to indicate the section of your worksheet you want to reformat: Block, Columns, Rows, or All. After selecting an area type, specify the area to be affected. You can then select the type of formatting to be done.

Block Marking
Row-Column Marking


 Many of the Layout Format options allow you to specify the following format settings.
** Display of numbers with or without commas, or "thousand separators."
** Presentation of negative numbers: with a minus sign; enclosed in parentheses; followed by "cr"; or followed by "cr" with positive numbers followed by "db".
** Display of cells containing only zeros: show the zeros or show blank cells.
** Decimal precision from 0 to 15 decimal places.

The available formatting (and preformatting) options are as follows:


 Bar. The Bar format displays numeric entries as a series of symbols representing the value. Positive numbers are represented by "+" symbols. Negative numbers are represented by "-" symbols. A value of 0 is displayed as a period. If the cell is not wide enough to display the bar, it is filled with asterisks.

Table 9-6
Value | Displayed As
5 | +++++
-7 | ----------
0 | .
100 | **********


 Date. The Date option of Layout Format enables you to reformat an area for date entries. Select Date1, Date2, or Date3. The formats represented by these selections are those specified in the Global Preferences menu, accessed by Tools Preferences Global. The integer portion of a numeric entry will be displayed as a date. The value 0 is shown as December 31, 1899. Positive integers are shown as dates after December 31, 1899. Negative integers are shown as dates prior to December 31, 1899.
NOTE: A date entry can be reformatted to display the actual number it represents by selecting the Layout Format command with the Numeric option. The numeric value of a date is based upon its relationship to "Day 0," December 31, 1899.

To enter a date (instead of a number to be converted to a date), begin the entry with "@" or "#". Even though the entry is displayed as a date in the cell and in the Control Area, it can be used as a value in calculations.


 Time. The Time option of the Layout Format command allows you to format an area for time entries. Specify either AM/PM or 24 hour time format. The fractional portion of a number will be represented as time.


 E-Notation. If you select the E-Notation option of the Layout Format command, you are changing the display format of specified cells to scientific notation (i.e., 256 is displayed as 2.56 E+02). Although a numeric entry is displayed in scientific notation within the cell, it is represented as a numeric value in the Control Area when you highlight that cell.


 Currency. Selecting the Currency option allows you to display values with a currency symbol. The currency symbol used and the location of the symbol with the number are determined by settings in Tools Preferences Global.


 Numeric. Selecting the Numeric option enables you to display values as numbers.


 Percent. Choosing the Percent format allows you to display values as percents. For example, ".22" would be displayed as "22%," and ".221" with one decimal place selected would be displayed as "22.1%."


 Reset. The Reset option of the Layout Format command enables you to reset cells that are currently displayed in one format to the default value format for the worksheet. This allows you to quickly reestablish the default format, including decimal precision and commas.


 General. The General option of the Layout Format command allows you to assign a general numeric format to the designated cells. Nonsignificant trailing zeros are suppressed. A value with a large number of positions to the left or right of the decimal is converted to E-Notation, as is a number too large to fit within the cell width.


Layout Format Formula-Display

When you select the Layout Format Formula-Display command, SmartWare prompts you to indicate whether you want to display the formulas in Map format, in Text format, or in Values format. The Values format is the normal worksheet display format, and is used to return Map or Text format to normal.


 Map. Selecting the Map option of the Layout Format Formula-Display command instructs SmartWare to display the cell entries in your worksheet as two-character codes, indicating the cell types in your worksheet. The first position of the code describes the formula. The second position refers to the formatting of the cell. Codes are defined with the Tools Preferences Spreadsheet command. See the discussion of assigning map codes in the Tools Preferences Spreadsheet section of Spreadsheet Manual.

Print Map
Tools Preferences Spreadsheet


 Text. Selecting the Text option of the Layout Format Formula-Display command instructs SmartWare to display a text version of any formula entries (i.e., r1c1+r10c3) contained in the specified area of your worksheet . If the formula is too long to display in its own cell, it will spill over into the adjacent cell as long as the adjacent cell is empty. If the adjacent cell is not empty, the display of the formula will be truncated.


 Values. Selecting the Values option of the Layout Format Formula-Display command instructs SmartWare to display the calculated results of any formula entries contained in the specified area of the worksheet. After viewing your worksheet in Map or Text format, select the Values option to return to normal worksheet display.


Layout Justify

The Layout Justify command changes the justification (alignment) of existing data only, both text and values. To specify the alignment of data not yet entered, use the Layout Default command.

The Quick Key for the Layout Justify command is Alt-J.


 Once you specify the type of alignment to be performed, you must determine the area to be justified. You can choose from the following options. Select Block to align data in a specified cell or block of cells. Select Rows or Columns to align data in specified rows or columns, respectively. Select All to define the alignment of all data in the worksheet.

Block Marking
Row-Column Marking

The types of alignment are as follows:


 Left. Use the Left option to align entries to the left.


 Right. Use the Right option to align entries to the right.


 Center. Use the Center option to center entries in the cell.


Layout Lines

The Layout Lines command, as well as the Layout Alter-Shading command, can enhance the design and appearance of printed worksheets and reports.

Lines in your worksheet are not visible on the screen. To actually view lines, print the file to the screen or send it to the printer. However, information about the current cell's attributes is displayed on the status line following the word Lines. The characters codes used to represent line attributes are described in the following list:

O - Outline
T - Line on top of cell
B - Line on bottom of cell
L - Line on left of cell
R - Line on right of cell
G - Grid lines around a cell


Edit

The EDIT command opens a screen that displays existing line attributes in your worksheet. This screen consists of a pointer and two columns: the first column indicates the line type and the second shows its position in standard spreadsheet coordinates.

You can change the position of any line type by pointing to it and entering in new coordinates. As an alternative, select the F6 Button, or key, to block mark cells. Block marking is completed when enter is pressed (mouse users can click on the ENTER message in the menu area). When you are satisfied with the modifications made, select F10.

Note: Line types themselves cannot be altered only repositioned.


Clear

The CLEAR command removes lines from your worksheet. This can be done in two ways: you can clear line attributes from a specified area by block marking or, you can remove all lines from your worksheet.


Outline

The OUTLINE command will place a box around a selected area of your worksheet. This can be achieved by either block marking the cells that you wish to outline or by selecting the ALL option to enclose your entire worksheet.

Note: When editing ALL attributes, the displayed row and column values will be r9999c999, even though the printed output only shows the outline around the actual worksheet. This feature allows the outlined area to expand or contract when the worksheet's size is changed.


Top

This command will create a line across the top of selected cells in your worksheet. Note that a line across the top of a row of cells and a line along the bottom of the cells above will only produce a single line.


Bottom

This command will create a line along the bottom of selected cells in your worksheet. Note that a line along the bottom of a row of cells and a line across the top of the cells below will only produce a single line.


Left

This command will create a line along the left side of selected cells in your worksheet. Note that a line along the right and left of adjacent cells will only produce a single line.


Right

This command will create a line along the right side of selected cells in your worksheet. Note that a line along the right and left of adjacent cells will only produce a single line.


Grid

The GRID command completely surrounds selected cells with lines so that it creates a box around each of the cells.

Note: When editing ALL attributes, the displayed row and column values will be r9999c999, even though the printed output only shows the grid on the actual worksheet. This feature allows the grid area to expand or contract when the worksheet's size is changed.


Layout Set-Font

Layout Font

A font is a complete set of characters in a single style and size, such as serif, 12 point. A font can also be a set of boldfaced, underscored, or italicized characters.

You can define and use as many as 64 fonts, numbered from 0 to 63, in a worksheet. Font numbers and definitions are saved with each worksheet; the fonts defined for one worksheet need not be the same as those defined for another worksheet. This feature allows you almost unlimited flexibility in font definition.

These commands allow you to control the use of fonts in your worksheets. The Select option allows you to choose the default font for the current worksheet. Once selected, the default font is the font that will be used for all new entries. The Change option allows you to use fonts other than the default for existing data in specific areas of the current worksheet. The Edit options allow you to assign a number to a specific font description (which you can define) for use in the current worksheet or in all future worksheets. The Remove options allow you to delete font descriptions that are not being used.

Font Prompter. The Font Prompter menu, shows the current list of fonts with their assigned numbers. Refer to the specific command instructions for information on using the Font Prompter.

Font Selector. The second menu, the Font Selector, appears when you indicate that you want to add or change a font description.

Font family, size, and color have submenus that list available options. Press F6 to view the submenus; select the desired options and press Enter. If no submenu appears when you press F6, no additional options are available.

Items highlighted in the Font Selector menu are the current settings. Items enclosed in parentheses are not supported by the current printer.

Select Slant, Weight, Modifications, and Baseline Shift settings by highlighting the desired option.

You can also specify foreground and background colors for fonts with the Colors option. You can either type the color numbers in the field, or use F6 to select from a palette.

F10 completes the definition.


Layout Set-Font Select

Layout Font Select

This command allows you to select a font as the default font for the current worksheet. The Font Prompter shows the font numbers and descriptions that have been defined for the current worksheet. The arrow points to the current default font when the Font Prompter first appears.


 Point to the font you want to use as the default and press Enter. The font number selected will be the font number used for all new entries in the current worksheet until you specify otherwise. The default font is displayed next to the word "Font:" on the Status Line of the screen.

To add a new font number and description and make it the default font for the current worksheet, point to a font on the list (normally, the one most similar to the desired new font) and press F6 to invoke the Font Selector menu. To view options for font family, characters set, size, or color, position the arrow next to the appropriate item and press F6 again. Select the other attributes and characteristics wanted. When you press F10, the newly defined font will be attached to the current worksheet as the default font, and will be assigned the next available number.
NOTE: If a newly defined font exactly matches an existing font, no new font number will be assigned.

The Quick Key for Layout Set-Font Select is F6.


Layout Set-Font Change

Layout Font Change

The Change command allows you to change the font for existing entries in a specified area of the current worksheet.


 When you select Change, you are asked to identify the type of area to be affected by choosing the Block, Columns, Rows, or All option. You are then prompted to define the area.

Block Marking
Row-Column Marking


 After you have specified the area to be changed, the Font Prompter is displayed. The Font Prompter lists the numbers and descriptions of the fonts that have been defined for the current worksheet. The arrow points to the font used by the cell in the upper-left corner of the area. If no data is in the upper-left corner, the default font is indicated. Position the arrow next to the desired font and press Enter. The font setting for the area is changed to the font you select.

To add a new font number and description for the current worksheet, point to one of the fonts on the list (normally, the one most similar to the desired new font) and press F6. The Font Selector screen will be displayed. Select the appropriate characteristics. When you press F10, the font for the specified area will be changed to the newly defined font. It will be assigned the next available number unless it matches an existing font. SmartWare will not assign a new number for an exact duplicate.


Layout Set-Font Edit

Layout Font Edit

The Font Edit commands allow you to assign specific numbers to the font descriptions of your choice. The Current-Sheet option allows you to modify the fonts for the current worksheet only. The New-Sheet option allows you to redefine the Font Prompter list for new worksheets. In either case, you can define a completely new font number and description, or change the description of an existing font.


 Current-Sheet. If you select the Font Edit Current-Sheet command, the Font Prompter, showing fonts attached to the current worksheet, is displayed. Changing a font number's description automatically changes the font used in the worksheet.


 New-Sheet. The New-Sheet option allows you to define font numbers and descriptions that are to be displayed on the Font Prompter menu for all new worksheets.

"New" worksheets are future worksheets, not worksheets existing at the time the New-Sheet option is used. Thus, the worksheet in the current window at the time the command is executed is not a new worksheet, even if it is blank. After revising the New-Sheet fonts, execute File Unload to obtain a "new" worksheet.

Font 0 is always the default font for new worksheets. To revise the font to be used as the default, select Font 0 and revise its description. You can also revise the definition of any other font on the menu by selecting its number and revising the description.


 To edit an existing font with either the Current-Sheet or New-Sheet option, point to the desired font, or enter the font number or description. When the Font Selector screen appears, you can revise the description as necessary. Press F10 to complete the change. To add a new font, point to an existing font and type an unused number. When the Font Selector screen appears, you can select the appropriate characteristics.


Layout Set-Font Remove

The Layout Set-Font Remove commands allow you to delete unused fonts.


 After you select either Current-Sheet or New-Sheet, the Font Prompter menu appears. Positioning the arrow next to a font and pressing Enter deletes just one font. You can also delete multiple fonts. Enter the font numbers to be deleted, or press F6 to mark fonts to be deleted. F6 is a toggle key that marks and unmarks fonts for deletion. Press F8 to mark all unused fonts for deletion. Press F10 to complete the command.


 Current-Sheet. The Current-Sheet option removes unused fonts from the Font Prompter menu of current worksheet. When you select the Current-Sheet option, the Font Prompter screen is displayed. The screen shows all the fonts defined for the current worksheet. Unused fonts are marked with an asterisk.

You cannot delete a font currently in use in the worksheet nor can you delete Font 0.


 New-Sheet. The New-Sheet option removes fonts from the list of fonts for new worksheets. When you select the New-Sheet option, the Font Prompter menu is displayed. The menu shows all fonts available for new worksheets. Since future worksheets do not yet exist, all fonts except Font 0 are marked with an asterisk and are eligible to be deleted.


Layout Worksheet-Options

The Layout Worksheet-Options commands display and define formatting and printing options for future entries. You can view and define settings for the current worksheet or for all future worksheets.

The format settings available through Layout Worksheet-Options are the same options available through the Layout Default command but are displayed on a menu. The print settings available through Layout Worksheet-Options allow you to specify basic print definitions for the worksheet as well. Overriding options are available through the Print Report command if you wish to produce your worksheet in a report format.

After selecting Layout Worksheet-Options, choose either the Current-Sheet option or the New-Sheet option. The current sheet is the worksheet in the current window, even if it has no entries. New sheets are all other future worksheets.


Layout Worksheet-Options Current-Sheet

The Current-Sheet option displays the Current Worksheet Parameters menu, which allows you to view and change the settings for the current worksheet. If the current worksheet is new or has had no changes to its format settings, the settings will be the same as shown in the Layout Worksheet-Options New-Sheet menu.

The Layout Default command is equivalent to the format options of the Layout Worksheet-Options Current-Sheet menu. Settings for the current worksheet can be defined through either command. However, the menu method allows you to change specific settings without inadvertently changing others.

When the current worksheet is saved, the format settings are saved with it.


Recalculation Order

Select the order of recalculation for the current worksheet. Natural Order means that formulas are calculated in the order that they are needed, not in the order of placement in the worksheet. For example, if r1c1 contains a formula that references r4c3, the value of r4c3 will be calculated first. The formula in r1c1 will use the new value of r4c3 in its calculation.

Row order means that the worksheet is calculated from left to right, by rows. Column order means that the worksheet is calculated by columns, beginning in column one, then moving to column two, and so on.

To change the recalculation order for the current sheet only, use the Sheet Calc-Mode Calc-Order command.

Sheet Calc-Mode Calc-Order


Default value format

The following format settings will be applied to all new values you enter into your worksheet. You can specify whether value entries will be treated as numeric, currency, general, date, time, E-Notation, percent, or bar.

Numeric. If you specify numeric format, you must also specify:
** whether or not commas will be used
** how negative numbers will be displayed
** whether or not zeros will be blanked
** whether the entry will be left, right or center justified
** to what precision the value will be displayed

Currency. If you specify currency format, you must also specify:
** whether or not commas will be used
** how negative numbers will be displayed
** whether or not zeros will be blanked
** whether the entry will be left, right or center justified
** to what precision the value will be displayed

General. If you specify general format, you must also specify whether the entry will be left, right or center justified.

Date. If you specify date format, you must also specify:
** whether the date will be displayed in Date1, Date2, or Date3 format
** whether the entry will be left, right or center justified
NOTE: What formats are actually represented by Date1, Date2, and Date3 are controlled by settings on the Tools Preferences Global definition menu.

Time. If you specify time format, you must also specify:
** whether the entry will be left, right or center justified
** whether the time will be displayed in AM/PM or 24-hour format

E-notation. If you specify E-notation format, you must also specify:
** whether or not zeros will be blanked
** whether the entry will be left, right or center justified
** to what precision the value will be displayed

Percent. If you specify percent format, you must also specify:
** whether or not commas will be used
** how negative numbers will be displayed
** whether or not zeros will be blanked
** whether the entry will be left, right or center justified
** to what precision the value will be displayed

Bar. If you specify bar format, you must also specify whether the entry will be left, right or center justified.

Layout Default Values

Default text format. You can specify left, center, or right justification for new text entries.

Layout Default Text


Cell Size

Cell Size settings allow you to control what type of units is used to measure the size of cells.

Width units. Cell width can be measured in characters, inches or points. Each character is the size of a monospaced 10 cpi character.
NOTE: The default width of 10 characters in the standard font of most printers uses approximately 72 points. However, when converting the measure from characters to points, SmartWare uses 7 points for one character ( or only 70 points for 10 characters.) This can cause unexpected results in printing. Review your worksheet for possible problem areas, and if necessary, print the worksheet using the Enhanced option instead of the Draft option of the Print command.

Height units. Specify the number of points or inches. Changes to row height will be reflected when the worksheet is printed using the Enhanced option of the Print command, but not on the screen display or in any other kind of printing.


Layout Worksheet Options New-Sheet

The New-Sheet option displays the New Worksheet Parameters menu, which allows you to establish a common format for your worksheets. All new worksheets will be formatted according to the Layout Worksheet-Options New-Sheet menu settings until they are reset through the Layout Default or Layout Worksheet-Options Current-Sheet commands.

Settings on the New-Sheet menu are identical to the Current-Sheet menu with two exceptions. Layout Worksheet-Options New-Sheet also has settings for Default Column Width and Default Column Height.

Default column width. Enter the number of units wide each cell in a new worksheet will be. Whether these units are characters, inches, or points is controlled by the previously discussed Cell Size prompts.

Layout Cell-Size Width

Default row height. Enter the number of units high each cell in a new worksheet will be. Whether these units are inches or points is controlled by the previously discussed Cell Size prompts.

Layout Cell-Size Height


Print Dialog Box

The pulldown menu Print command allows you to print information from designated areas of your worksheet or to print the entire worksheet, and print formula and map versions of your worksheet.


Print Options

Options for the Print command dialog box include:

Worksheet. Prints the worksheet, showing calculated results rather than formula definitions. This is the "normal" worksheet printing option.
Formulas. Prints the formulas of a worksheet, rather than the results.
Map. Prints a coded map of the worksheet, showing the types of data in each cell.

If you select Block, mark the part of the worksheet you want to print or enter the block name.

Draft printing produces worksheet data using internal printer fonts and is the fastest method of printing a worksheet. Boldfaced or underscored font attributes can be used.

Enhanced printing allows the production of various fonts, including SmartWare-generated, filled-area fonts and more complex printing capabilities. Adjusted cell height, for example, is apparent only when you print with the Enhanced option. Because of its complexity, enhanced printing can be a great deal slower than draft printing.


Print Commands

The Print commands allow you to print information from designated areas of your worksheet or to print the entire worksheet, send the output to a file rather than to a printer, produce reports from your worksheet, and print formula and map versions of your worksheet.


Print Options

Options for the Print command include:

Worksheet. Prints the worksheet, showing calculated results rather than formula definitions. This is the "normal" worksheet printing option.
Formulas. Prints the formulas of a worksheet, rather than the results.
Map. Prints a coded map of the worksheet, showing the types of data in each cell.
Report. Produces data from one or more worksheets in a report format, with optional page headings and footings.
Print Options. Controls the formatting options for printing the current worksheet.
Print Preset. Controls the default formatting options for printing new worksheets.


Print Worksheet

The Print Worksheet command produces a printout of all or part of a worksheet. Headings and labels, numeric entries, and the calculated results of formulas are shown as they appear in the Worksheet Window. The following steps describe how to print data from the current worksheet.

Step 1: Select Print Worksheet.


 Step 2: Select All to print the entire worksheet, or Block to print only part of the worksheet.

If you select Block, you will then be prompted to mark the part of the worksheet you want to print or enter the block name.


 Step 3: Select Draft or Enhanced printing.

Draft printing produces worksheet data using internal printer fonts and is the fastest method of printing a worksheet. Boldfaced or underscored font attributes can be used. Any SmartWare-generated filled-area fonts you have designated in your worksheet will be replaced by the standard font.

Enhanced printing allows the production of various fonts, including SmartWare-generated, filled-area fonts and more complex printing capabilities. Adjusted cell height, for example, is apparent only when you print with the Enhanced option. Because of its complexity, enhanced printing can be a great deal slower than draft printing.


 Step 4: Enter the number of copies you want printed.


 5. Select Printer to send the data to the current printer, select Disk to send the data to a disk file, or select screen to preview the data.

If you specify Disk, you are prompted to enter a name for the disk file to be created. The file will be assigned the extension .prn unless you specify otherwise.
NOTE: A file that is written to disk will contain printer control codes. These codes allow the file to be printed outside of SmartWare. At the DOS level, you can print the file by copying it to your printer and it will look just like it was printed from within SmartWare. However, printer control codes make it difficult to view or edit this file. To create a file containing no printer control codes, select the generic printer descriptor on the Hardware Preferences menu before printing the file disk.

Selecting Screen sends the data to the print previewer which allows you to view the data as it appears in the printed output.


Print Formulas

The Print Formulas command prints a listing, by row and column number, of the formulas in a worksheet. The Print Formulas command differs slightly from the Layout Format Formula-Display Text command which actually shows the formulas in their cells rather than listing them. The following steps illustrate how to print a map of the formulas in the current worksheet.

Step 1: Select Print Formulas.


 Step 2: Select All to print all formulas in the entire worksheet, or Block to print only formulas in part of the worksheet.

If you select Block, you will then be prompted to mark the part of the worksheet you want to print or enter the block name.

Step 3: Select Printer to send the data to the current printer, select Disk to send the data to a disk file, or select Screen to send the data to the print previewer.

If you specify Disk, you are prompted to enter a name for the disk file to be created. The file will be assigned the extension .prn unless you specify otherwise.


Print Map

The Print Map command prints the worksheet in a coded format showing the types of data in each cell. The following steps illustrate this process.

Step 1: Select Print Map.


 Step 2: Select All to print the entire worksheet, or Block to print only part of the worksheet.

If you select Block, you will then be prompted to mark the part of the worksheet you want to print or enter the block name.

Step 3: Select Draft or Enhanced printing.

Draft printing produces worksheet data without special fonts. It uses only the default internal font for your printer and is the fastest method of printing a worksheet. Boldfaced or underscored font attributes can be used.

Enhanced printing allows the production of various fonts, including SmartWare-generated filled-area fonts, and more complex printing capabilities. Adjusted cell height, for example, is apparent only when you print with the Enhanced option. Because of its complexity, enhanced printing can be a great deal slower than draft printing.

Step 4: Enter the number of copies you want printed.

Step 5: Select Printer to send the data to the current printer, select Disk to send the data to a disk file, or select Screen to send the data to the print previewer.

If you specify Disk, you are prompted to enter a name for the disk file to be created. The file will be assigned the extension .prn unless you specify otherwise.


Print Report

The Report commands allow you to produce a professional looking report from your worksheet. In addition to the worksheet information, the report can have headings, footings, and page numbering. You can also include information from more than one worksheet on a report.


Print Report Create

To generate a worksheet report, you must first create a report definition file. Once this definition file is set up, it can be executed at any time.

The following steps explain how to define and execute a report.

Step 1: Take a moment to study your worksheet data and determine how you want it presented.

Step 2: Select Print Report Create.


 Step 3: Enter a name for the report definition you are about to create.

A report definition filename can consist of up to 8 characters and is assigned the extension .rdf.


 Step 4: Select New or Similar.

Selecting New brings up an empty definition menu and you can start your definition from scratch. Select Similar to use an existing report definition as a template. When prompted, enter the name of the file to be used as a template.

The Report Definition menu is then displayed. There are four categories of information you will have to specify in this definition:
** Print groups
** Headings
** Footings
** Print options

Print Groups

Print Groups, the major sections of a report, define column headings, labels and worksheet data to be printed as a unit in a report. A print group is comprised of a report body block (normally, numeric or calculated worksheet data) and optional horizontal and vertical title blocks. Horizontal title blocks correspond to column headings on the worksheet. Vertical title blocks correspond to row labels.

If data from one print group cannot fit on a single page, overflow pages will be produced. The appropriate headings and labels will be repeated on additional pages. Each print group you define will begin at the top of a new page.

A report definition must have at least one print group, consisting of at least one body block. The title blocks are optional. If the data and titles from your worksheet will fit well on one report page, cells containing column headings and row labels can simply be included in the body block definition.

Sometimes, however, the information needs to be arranged differently from the way it appears in the worksheet. Or sometimes the information from a body block will not fit on one report page. Title blocks provide headings and labels for rearranged information, or for body blocks that overflow to additional pages.


Specifying Print Groups

For each of the three prompts in a Print Group, Horizontal Title:, Vertical Title:, and Body Block:, you have the option of typing in information or using F6 to go to the worksheet and mark references.

Horizontal and Vertical Titles. For titles, enter a cell reference, use F6 to mark a block containing the text from the worksheet, or enter a text string for the titles. References must be either cell references, or text entries; they cannot be a combination of the two.

To line up properly on the report, the width of a horizontal title block must match the width of the body block. The length of the vertical title block must also match the length of the body block.

Title blocks can consist of more than one block reference. Use of multiple block references is discussed later in this section.

Body Blocks. For body blocks, enter a cell reference, or use F6 to mark a block on the worksheet. Body blocks can consist of more than one block reference. Use of multiple block references is discussed later in this section.


Using Multiple Block References

Multiple block references can be specified for body blocks and title blocks. References to more than one block of worksheet data must be separated by either commas or semicolons. The use of a comma or semicolon determines how the blocks are positioned on the report.

Comma | Blocks are placed one below the other, on the same page if possible.
Semicolon | Blocks are placed side by side, on the same page if possible.

For examples of how using commas or semicolons affects report layout, refer to Using Multiple Block References in the Spreadsheet Manual. The following steps explain how multiple references are done.

Step 1: Press F6.

Step 2: Mark the first block.

Enter a comma or a semicolon, depending on how you want the block positioned. Continue marking blocks in this manner until all necessary blocks are referenced.

Step 3: Immediately after that cell reference, type a comma or a semicolon, depending on how you want the blocks positioned.

Step 4: Press F6 again to return to the worksheet.

Step 5: Continue marking blocks in this manner until all necessary references are included.


Referencing Multiple Worksheets

To use more than one worksheet in a single report definition, precede a block reference with the worksheet name and a period

Example:
     qtr1.r1:9c2:4,qtr2.r1:9c2:4

The example shown would print a block from the worksheet qtr1 above a block from the worksheet qtr2.


Adding Print Groups

By default, prompts appear to allow three print groups to be specified. The print groups will be printed in the order in which they appear on the definition menu. The report will start with Print Group 1 and print as many pages as necessary to print the data you have specified. Then Print Group 2 will start at the top of a new page and print as many pages as necessary. Then Print Group 3 will be printed.

Additional Print Groups can be defined by adding them with F7.

Step 1: Move the prompter arrow to the Print Group you want the new group to follow.

Remember, the Print Groups will be printed in order, so if you want to insert a new print group between Print Group 1 and 2, position the prompter arrow on Print Group 1. If you want the new group to come at the end of the repot, position the prompter arrow on the last Print Group.

Step 2: Press F7.

A new Print Group will be added directly below the Print Group you were pointing to and all Print Groups will be renumbered accordingly. Any settings in the Print Group were pointing to will be copied into the new print group. You can edit those settings as necessary.


Deleting Print Groups

To remove a Print Group from the Report Definition menu, point to it and press F8. The Print Group will be deleted and all other Print Groups will renumber accordingly.


Report Headings and Footings

The report heading, which is optional, is information to be printed at the top of each page of the report. The report footing, which is also optional, is printed at the bottom of each page.


Headings and Footings

You can specify headings or footings to be printed on some or all pages of your report. The first group of settings on the Print Option menu specifies heading information and the second group specifies footing information. The settings used to specify headers and footers are very similar, so they are discussed together here.


Print Heading/Footing On

Specify which pages will have printed headings or footings. You can choose to have the headings or footings printed on:
** all pages
** only the first page
** on all pages except the first page.


Blank Lines after Heading/Footing

Enter a number from 0 to 3 to specify the number of blank lines that separate the heading from the first line of report data or the footing from the last line of data.


Use Secondary Heading/Footing

Two types of headings or footings are available: primary and secondary. If you select No, the primary heading or footing is printed on all pages. If you specify Yes, primary headings or footings are printed on odd-numbered pages, and secondary headings or footings are printed on even-numbered pages.


Primary and Secondary Headings/Footings

A maximum of five lines can be specified for each type of heading or footing. Enter up to 255 characters (including control codes and printable characters) for each line. If the text you want for a heading or footing is on your worksheet, you can press F6 to mark the cell reference. Heading and Footing entries must be cell references or text, not both. If text and cell references are found on the same line, only the text will be printed.

A line is printed if it contains characters or is followed by a line that contains characters. If you leave lines one and two blank, and enter heading information on line three, your heading will consist of two blank lines and one line of text.


Print Control Codes

Print control codes are special character sequences that can be specified in headings or footings. The codes are used to control the alignment of information, or are replaced by current data, such as date, time, or page number. The following table lists the print control codes.

NOTE: Since the percent sign (%) is part of all control codes, you must enter %% if you want a percent sign to print in a header or footer.
Control Code | Description
%L | Left aligns the text immediately following the control code until a different print control code is encountered, or until the end of the current line.
%C | Centers the text immediately following the control code until a different print control code is encountered, or until the end of the current line.
%R | Right aligns the text immediately following the control code until a different print control code is encountered, or until the end of the current line.
%P | Replaces the control code with the page number.
%D | Replaces the control code with the current date.
%T | Replaces the control code with the current time.
%F | Replaces the control code with the name of the file being printed.
%[#] | Specifies a font for the text immediately following the control code.(# must be a valid font number.) The font number must be surrounded by brackets and can be followed by B or U to boldface or underscore text.
%S | Replaces the control code with a section number (where "S" is the section number).

Control codes can be used in any combination, with more than one control code appearing on a line. Control codes do not appear in the printed report. Do not separate the control codes from literal information with blank spaces unless you want the blank space printed on the report.

Following are examples of two print control code strings that could be entered as headers or footers and an illustration of the results they would achieve.

Example:
     5F%C-%P-2D

     filename.ext               -10-                   11-14-90

5F causes the name of the current file to be printed at the left margin. %C-%P- causes the current page number to be centered on the line between two dashes. 2D causes the current date to be printed at the right margin.

Example:
     %LQuarterly Report%CACME Shoes%R3rd Quarter

     Quarterly Report          ACME Shoes             3rd Quarter

%LQuarterly Report causes the text "Quarterly Report" to be printed at the left margin. %CACME Shoes causes the text ACME Shoes to be centered on the line. %R3rd Quarter causes the text 3rd Quarter to be printed at the right margin.

Primary and secondary headings or footings are allocated equal space on the printed page, even when they are not the same length. The heading or footing requiring the greater number of lines determines the space allocated for both.


Example

The following steps show how to print a heading on every other page.

Step 1: Select All-pages for the Print Heading On: option.

Step 2: Specify Yes for the Use secondary heading: option.

Step 3: Leave either the primary or the secondary heading blank.

Depending on the heading you have left blank, headings will be printed on all even pages or all odd pages only.


Date Style

If you use the %D print control code to insert the current date in a header or footer, you must specify the format in which you want that date printed. Select one of the available date styles. The formats represented by Date1, Date2, and Date3 are set on the Global Preferences menu, accessed with the Tools Preferences Global command.


Page Number Style

If you use the %P print control code to insert the current page number in a header or footer you must specify how you want that number printed. Select Arabic, Roman-Small (lowercase Roman numerals), or Roman-Caps (uppercase Roman numerals.)


Lines to Enclose Report

Select None to have no lines enclose report data. Single or Double will place a single or double line below the heading and above the footing, enclosing the data.


Start Page Number

If you use the %P print control code to insert the current page number in a header or footer, you must enter the page number the report will start with.


Spacing

Specify how you want the body of a report printed. Select Single to single space data, or Double to double space data.


Lines Per Inch

Select 6 or 8 to determine the number of lines per inch that will be printed when you select the Draft option of the Print command.


Draft mode

Select 10, 12, Compressed, or Internal-Fonts to determine which font will be used to print your worksheet when you select the Draft option of the Print Report Execute command. If you select 10-cpi, the worksheet will be printed with your printer's internal 10-cpi font. Selecting 12-cpi will use the printer's internal 12-cpi font. The compressed setting will print the worksheet in the internal compressed font. A compressed font's cpi varies between 15 and 20, depending on the printer.
NOTE: Not all printers will support all three of these options.

If you wish to use any other internal printer font, you must select the Internal-Fonts setting. Then SmartWare picks up the internal fonts you have requested from the worksheet.


Paper Profile

A paper profile is made up of the page size and paper path you want to use to print a file. The paper path tells SmartWare where the printer will find the paper for this job, and how it will move it through the printer. For example, you can specify the use of a tractor feed, or manual feed; choose between several paper trays; or specify the use of an envelope or single sheet feeder. Page size tells SmartWare whether you will be printing an 8-1/2 by 11 inch page, an envelope or a custom page size.

This paper profile will control printing of Spreadsheet Reports only. Other Spreadsheet printing features will be controlled by the Paper Profile setting on the Current Print Options menu. Printing in the Word Processor and Database Reports are controlled by Paper Profile settings within each module. Printing from editors, such as the Text-Editor, non-report Database printing, and printing through Project Processing are controlled by the default paper profile on the Hardware Preferences menu.

Detailed information about selecting a page profile is provided in the Spreadsheet Manual.


Orientation

Select Portrait to print the report across the short side of the page. Select Landscape to print the report "sideways," across the long side of the page. Landscape printing can only be accomplished if your printer supports it.


Print on Both Sides of the Form

Select Yes to print on both sides of the page. This process is sometimes called duplex printing. Select No to print on only one side of the page. Duplex printing can only be accomplished if your printer supports it.


Use Secondary Borders

Select Yes to be able to set different borders, or margins for even numbered report pages. The size of secondary borders is controlled by settings at the Page Border option. Select No if you want odd and even pages to have the same borders.


Page Borders

The Page Border is the margin or amount of white space between the edge of the page and the report data. Some printers, particularly laser printers, have preset "hard margins." Your printer manual should tell you if your printer has "hard margins." Your margins must be at least as wide as the printer's hard margins.

Specify a top and bottom margin in inches. Under the Primary option, specify left and right margins in inches. These boundaries will apply to all pages if you have specified no secondary boundaries, or odd numbered pages if you have specified secondary boundaries.

If you selected Yes for the Use of secondary pages you must also specify left and right margins for even pages.

When you have made all necessary changes, press F10 to leave the Report Definition screen.


Report Modify

Report Modify allows you to edit a previously defined Report Definition. After executing the command, type in the name of the file you want to edit, or select it from the file prompter. The Report Definition menu is then displayed. Make any necessary changes and select F10 to save the new definition.

Detailed information about each setting on the Report Definition menu is presented in the previous discussion of the Print Report Create command.


Print Report Remove

Print Report Remove deletes a report definition. Enter the name of the report definition file to be deleted. Include the path, if necessary.


Print Report Execute

Print Report Execute prints a report from a report definition file. All worksheets referenced in the report must be active. The following steps explain the process.

Step 1: Select Print Report Execute.


 Step 2: Enter the name of the report to be executed.


 Step 3: Select Draft or Enhanced printing.

Draft printing produces worksheet data without special fonts. It uses only internal printer fonts for your printer and is the fastest method of printing a worksheet. Boldfaced or underscored fonts can be used.

Enhanced printing allows the production of various fonts and more complex printing capabilities. Adjusted cell height, for example, is apparent only when you print with the Enhanced option. Because of its complexity, enhanced printing can be a great deal slower than draft printing.


 Step 5: Select Printer to send the data to the current printer,select Disk to send the data to a disk file, or select Screen to send the data to the print previewer.

If you specify Disk, you are prompted to enter a name for the disk file to be created. The file will be assigned the extension .prn unless you specify otherwise.
NOTE: A file that is written to disk will contain printer control codes. These codes allow the file to be printed outside of SmartWare. At the DOS level, you can print the file by copying to your printer and it will look just like it was printed from within SmartWare. However, printer control codes make it difficult to view or edit this file. To create a file that contains no printer control codes, select the generic before printing the file to disk.

Selecting Screen sends the report to the print previewer which allows you to view a report as it appears in the printed output.


Print Options

Print Options is used to specify the print option settings for the current section of the current document. Selection of the Print Options command invokes the display of a definition menu containing specification items that control:
** the content and placement of worksheet headings and footings,
** date and page number styles,
** page size and paper path.

Each definition item is discussed in detail below.


Printing Row and Column Numbers

Select Yes at each prompt to have column or row numbers printed on your worksheet. Select No to have no row or column numbers printed.


Lines per inch in draft mode

Specify whether you want your document printed 6 or 8 lines to the inch when you print your worksheet in draft mode. Selecting 8 lines per inch makes the space between each line smaller, allowing more information to be printed in the same space.


Characters per inch in draft mode

Select 10, 12, or Compressed to determine which font will be used to print your worksheet when you select the Draft option of the Print Report Execute command. If you select 10-cpi, the worksheet will be printed with your printer's internal 10-cpi font. Selecting 12-cpi will use the printer's internal 12-cpi font. The compressed setting will print the worksheet in the internal compressed font. A compressed font's cpi varies between 15 and 20, depending on the printer.
NOTE: Not all printers will support all three of these options.


Paper Profile

A paper profile is made up of the page size and paper path you want to use to print a file. The paper path tells SmartWare where the printer will find the paper for this job, and how it will move it through the printer. For example, you can specify the use of a tractor feed, or manual feed; choose between several paper trays; or specify the use of an envelope or single sheet feeder. Page size tells SmartWare whether you will be printing an 8-1/2 by 11 inch page, an envelope or a custom page size.

This paper profile will control all Spreadsheet printing, except reports. The Report Definition menu contains a setting for controlling paper profile selection. Printing in the Word Processor and Database Reports are controlled by Paper Profile settings within each module. Printing from editors, such as the Text-Editor, non-report Database printing, and printing through Project Processing are controlled by the default paper profile on the Hardware Preferences menu.

Detailed information about selecting a paper profile is provided in the Spreadsheet Manual.


Orientation

Select Portrait to print the report across the width or horizontal side of the page. Select Landscape to print the report "sideways," across the length or vertical side of the page. Landscape printing can only be accomplished if your printer supports it.


Page Borders

The Page Border is the margin or amount of white space between the edge of the page and the report data. Some printers, particularly laser printers, have preset "hard margins." Your printer manual should tell you if your printer has "hard margins." Your margins must be at least as wide as the printer's hard margins.

Specify a top, bottom, left and right margin in inches.

When you have made all necessary changes, press F10 to leave the Report Definition screen.


Print Preset

Print Options New-Worksheets

Print Preset is used to specify the print option settings for all new worksheets. The same definition screen displayed with Print Options is also displayed with Print Preset. See previous discussion of Print Options for detailed information about each setting.


Edit Commands

The Edit commands allow you to alter your worksheets in a variety of ways. You can copy or move data, insert or delete areas of a worksheet, sort data, or hide certain information in a worksheet. You can also edit a cell's contents or a formula.

The Edit keyword provides the following command options:

Blank. Removes data from specified areas of your worksheet, leaving blank cells.
Copy. Duplicates the contents (including formulas) of specified rows, columns, or blocks of cells.
Delete. Deletes rows, columns, or a block of cells.
Edit-Cell. Allows changes to the contents of one cell.
Fill. Fills designated area of cells with values incremented or decremented by a specified amount.
Hide. Allows areas of the worksheet to be temporarily blocked from view.
Unhide. Restores hidden areas to an unhidden status.
Insert. Inserts blank columns, rows, or blocks.
Move. Relocates data to another area of the worksheet.
Sort. Sorts worksheet data.
Value-Copy. Copies text, values, or the results of formulas from one cell or block to another location.


Edit Blank

The Edit Blank command erases text, values, and formulas from a designated portion of the worksheet. Unlike the Edit Delete command which actually deletes the block, columns, or rows from the worksheet, the Edit Blank command works without collapsing the remaining cells into the blanked area.

Besides removing data from cells, Edit Blank restores the default format and default font to the blanked area.

The Quick Key for Edit Blank is Alt-B.
IMPORTANT: Edit Blank will not blank any cells in an area containing locked cells.

Edit Delete


 Block. The Edit Blank Block command erases data from a specified group of cells. Enter the name or block reference of the cells you want blanked.

Block Marking


 Columns. The Edit Blank Columns command blanks a specified number of columns. You are prompted to enter the number of columns you want blanked. The current column plus the appropriate number of additional columns will be blanked when you press Enter.

Row-Col Marking


 Rows. The Edit Blank Rows command blanks a specified number of rows. You are prompted to enter the number of rows to be blanked. The total number of specified rows (which includes the current row) will be erased when you press Enter.

Row-Col Marking


 All. Selecting the Edit Blank All command immediately blanks all the data in the worksheet.


Edit Copy

The Edit Copy command duplicates the contents of a single cell or a group of cells to a destination in the same worksheet, or in a different worksheet. You can use Edit Copy to copy text, values, or formulas.

The Quick Key for the Edit Copy command is Alt-C.

Before copying a formula, determine which, if any, cell references should be copied as absolute references, and which cell references should be copied as relative references. Use the Edit Edit-Cell command, Alt-E, or Alt-F to edit the formula and insert brackets around the absolute references. Then execute the Edit Copy command.

Edit Copy provides several options for defining the area to be copied. You can copy adjacently in two directions (down a number of rows or right a number of columns), or you can copy from one area of a worksheet to any other area.

Absolute and Relative References
Edit Move


Edit Value-Copy

The Edit Value-Copy command copies text and values from one location to another location in the same worksheet or a different worksheet. Edit Value-Copy and Edit Copy are similar in that they both copy data from one location to another. The difference is that the Value-Copy command copies the result of a formula from the copied cell, while the Copy command copies the formula itself.

The source and the destination used for Edit Value-Copy From can be the same cell, providing an easy way to convert a formula to a value.

The Edit Value-Copy command provides several options for defining the area to be copied. You can copy in two directions (down a number of rows or right a number of columns), or you can elect to copy from a block of cells. The pulldown menu dialog box provides only the block copy option.

Edit Move

The Edit Copy and Edit Value-Copy command options are Down, Right, and From.


Edit Copy Down or Edit Value-Copy Down

The Down option copies either a single cell or multiple cells to the area immediately beneath the cells being copied. Select either Single-Cell or Row.


 Row. The Row option copies multiple cells. You are prompted to specify row length, which is the number of cells to the right that are to be copied.

Row-Column Marking


 Single-Cell. The Single-Cell option copies the contents of one cell.


Edit Copy Right or Edit Value-Copy Right

The Right option copies either a single cell or multiple cells to the immediate right of the cells being copied. Select either Single-Cell or Column.


 Column. The Column option copies multiple cells. You are asked to enter column length, which is the number of cells down that are to be copied.

Row-Column Marking


Edit Copy From or Edit Value-Copy From

The From option copies a block of cells from the current location to any location in the same or a different worksheet. The "copy to" location does not need to be adjacent to the "copy from" location.


 For either Edit Copy or Edit Value-Copy, you are asked to specify the number of copies, which is the number of times the cells in the designated area are to be duplicated.


 You are prompted to enter the name or block reference of the source block, the area you want to copy. The source block, which can consist of many cells or just one cell, can be copied once or replicated many times. When copying one cell to multiple cells, you can make the destination block as large as you wish.

Block Marking


 SmartWare then asks you for the name or the location of the destination. Enter a block name, cell or block address in the same worksheet, or a block name, cell or block address from an active, external worksheet (i.e., sales.r1:10c2:3, or sales.westregn). When the command is executed, the copied data appears in the designated location.

Block Marking

The source and destination blocks can overlap as long as the upper left corners of both coincide.
IMPORTANT: When you copy data, be certain that the destination cells are empty or contain only data that you no longer need. Edit Copy and Edit Value-Copy will overwrite data in the designated destination block.


Edit Delete

The Edit Delete command actually removes cells from your worksheet, rather than just blanking the contents. Remaining cells collapse into the deleted area.

Formula references in the remaining cells are automatically adjusted to reflect the changes produced by the deletion. When Edit Delete Columns or Edit Delete Rows is selected, the current column or row is included in the deletion.

The Quick Key for the Edit Delete command is Alt-D.

The Edit Delete options are Block, Columns, and Rows.


 Block. The Edit Delete Block command deletes a block of cells. Pressing Enter without specifying additional cells deletes the current cell only. The cells to the right of the block move to fill the vacant space.


 Columns. The Edit Delete Columns command deletes one or more columns, beginning at the current column. Pressing Enter without specifying additional columns deletes the current column only. The columns to the right of the deleted column are pulled into the vacated space.


 Rows. The Edit Delete Rows command deletes one or more rows, beginning at the current row. Pressing Enter without specifying additional rows deletes just the current row. The rows below the deleted row are pulled up into the vacated space.


Edit Insert

The Edit Insert command inserts blank rows, columns, or blocks into the current worksheet at the current highlighter position. Cell and block references within formulas are automatically adjusted when new blocks, columns, or rows are inserted.

The Quick Key for Edit Insert is Alt-I.

The Edit Insert options are Block, Columns, Rows.


 Block. Inserting a block opens up blank cells in the specified block and moves to the right any information that previously occupied that space.


 Columns. When columns are inserted, information in and to the right of the current column is moved right to accommodate the new columns.


 Rows. When rows are inserted, information in and below the current row is moved down to accommodate the new rows.

Defining Insert or Delete Areas


 When you select the Block option, you are prompted to enter a block name or reference for the area to insert or delete.

Block Marking


 When you select the Columns option, you are prompted to enter the number of columns to insert or delete.


 When you select the Rows option, you are prompted to enter the number of rows to insert or delete.

Row-Column Marking


Edit Edit-Cell

The Edit Edit-Cell command is used to revise formulas, text, or values in the current cell without re-keying the whole entry. When you select Edit Edit-Cell, the SmartWare Cell Editor is activated. The Cell Editor can edit a cell containing text, values, or formulas up to 240 characters long.

The contents of the cell are displayed on a line in the Control Area of the screen. If the cell contains text, your changes are reflected in the cell as you type. If the cell contains a value or a formula, changes are not reflected in the cell until you press Enter.

Alt-E is the Quick Key for accessing the SmartWare Cell Editor.

Table 9-2 lists keys to use in the Cell Editor to change the contents of a cell.

Table 9-2 Cell Editor Keys.
Key | Action
Delete | Deletes character at current cursor position.
Backspace | Moves cursor left one character, deleting character.
Left-Arrow | Moves cursor left one character.
Right-Arrow | Moves cursor right one character.
Tab | Moves cursor right five characters.
Shift Tab | Moves cursor left five characters.
Ctrl-Left-Arrow | Moves cursor to beginning of edit line.
Ctrl-Right-Arrow | Moves cursor to right end of edit line.
Insert | Toggles on or off Insert Mode.
Enter | Completes editing and records new contents in cell.
Escape | Cancels editing without retaining changes.
Alt-F | Invokes the Formula Editor.


Making Entries on a Graph Definition Menu

Graph Definition menus provide you with detailed control over almost every part of a SmartWare graph. By making entries on a Graph Definition menu, you can change the background of the title, center the lines in the footnote, hide the legend, or change the color used to draw a specific axis. The list of items you can change is so extensive, in fact, that the menus normally are collapsed into a sort of index that reflects the structure of the graphs themselves.

To expand a section of the menu for editing, move the cursor to the line containing the title of the section (e.g., 3d Settings) and press Spacebar until the word Edit appears at the end of the line. To collapse the menu after editing (which is optional), return to the same title line and press Spacebar until the word Hide appears at the end of the line.
NOTE: Collapsing sections is simply a means of organizing a long Graph Definition menu and reducing screen clutter. It has no effect on whether settings remain in effect or whether they are stored in the graph definition file.

After the filename and graph type entries, all settings are grouped according to the five areas on a SmartWare graph. The first group of entries is for the plot area, followed by those for the legend, title, footnote, and background areas.

Components of a Graph

Business, high-low, scientific, and elevations graphs are all based on numerical worksheet data and have similar Graph Definition menus. Only the settings for the plot area vary from one class to the next. Text and composite graphs are not based on numerical data and have their own unique menus.

Graph Definition menus are accessed by selecting Graph Define on the Spreadsheet menu. When you select Graph Define, six options appear representing the six classes of graphs. Select a class and the Graph Definition menu for that class appears. When you are finished editing your definition, press F10 to exit the menu and save the graph definition file. Press Escape to abandon editing.

The extension of a graph definition file indicates the class of the graph it contains. Following is a list of the extensions associated with graph definition files.

NOTE: The .gdq extension is used only with quick.gdq, which is not a graph definition file per se. It contains only the cell reference used to create the most recent quick graph.
Extension | Graph Class
.gdb | Business
.gdh | High-Low
.gds | Scientific
.gde | Elevation
.gdt | Text
.gdc | Composite


Edit Fill

The Edit Fill command automatically fills a portion of your worksheet with data that is incremented by a number you specify, relieving you of typing the entries manually. You can fill a block of cells or designated columns or rows.


 After you define the area to be filled, you are prompted to enter a starting value, and a number by which to increment your starting value. If you want to fill an area with decreasing values, precede the increment value with a minus sign (-).
IMPORTANT: The Edit Fill command does not proceed if there are locked cells in the area designated to be filled.


 Block. This specifies the block of cells with values. Cells are filled sequentially, beginning in the upper left corner of the block, moving vertically, top to bottom, until all cells in the block are filled.

Block Marking


 Columns. The Edit Fill Columns command enters values into a specified number of columns across the current row. You are prompted to enter the number of columns to be filled. Not available from pulldown menus.

Row-Column Marking


 Rows. The Edit Fill Rows command enters values into a specified number of rows down the current column. You are prompted to enter the number of rows to be filled. Not available from pulldown menus.

Row-Column Marking


Edit Hide

The Edit Hide command conceals the contents of a cell or group of cells in a worksheet. Hidden areas of the worksheet simply appear to be blank. Once you execute the Edit Hide command, the Hide instruction is attached to the worksheet. It can be temporarily disabled, but to remove it completely, you must use Unhide.

Hide status applies only to nonblank cells in the specified area. If you enter data into formerly blank cells in a hidden area, the new entries will not be hidden.
IMPORTANT: When SmartWare Spreadsheet is in Data Entry Mode, and the cell highlighter is moved to a hidden cell, the contents of the cell are displayed in the Control Area of the screen.

The Edit Hide options are Block, Columns, Rows, All, Disable, and Enable.


 Block. The Edit Hide Block command hides a specified block of cells.


 Columns. The Edit Hide Columns command hides specified columns of cells.


 Rows. The Edit Hide Rows command hides specified rows of cells.


 All. The Edit Hide All command hides all the cells in the worksheet.


 Disable. You can temporarily suspend the Hide instruction and display the hidden data on the screen by executing the Edit Hide Disable command.


 Enable. Data hidden before the Edit Hide Disable command was executed can be concealed again by executing the Edit Hide Enable command.


Edit Unhide

Edit Unhide permanently removes a Hide instruction inserted by the Edit Hide command. The Edit Hide command conceals the contents of specified cells.

If you just want to suspend the Hide instruction temporarily but not remove it, use the Edit Hide Disable command. To reactivate a disabled Hide instruction, use the Edit Hide Enable option.

The Edit Unhide options are Block, Columns, Rows, and All.


 Block. The Edit Unhide Block command removes the Hide instruction from a worksheet block.


 Columns. The Edit Unhide Columns command removes the Hide instructions from specific hidden columns, beginning with the current column and counting to the right.


 Rows. The Edit Unhide Rows command removes the Hide instruction from specific hidden rows, beginning with the current row and counting down.


 All. The Edit Unhide All command removes the Hide instruction for the whole worksheet.

Defining Hide or Unhide Areas


 For either Edit Hide or Edit Unhide, you are prompted to enter the name or block reference of the cells you want to hide or unhide.

Block Marking


 For either Edit Hide or Edit Unhide, you are prompted to enter the number of columns to hide or unhide.


 For either Edit Hide or Edit Unhide, you are prompted to enter the number of rows to hide or unhide.

Row-Column Marking


Edit Move

The Edit Move command relocates data in specified cells from the current position in the worksheet to a new position. You can move data contained in a block, in one or more columns, or in one or more rows.

When Edit Move Block is executed, data in the destination block will be overwritten by the moved data unless the destination cells are locked.

When Edit Move Columns or Rows is executed, the columns or rows from which the data is moved are deleted. The moved data is inserted in new columns or rows at the designated location, without overwriting existing data.

The Quick Key for the Edit Move command is Alt-M.

Edit Copy


 Block. Enter a name or block reference for the data block you want to move.

Block Marking


 You must enter a name or block reference for the destination location. When the source block consists of multiple cells, it is only necessary to indicate the upper left corner of the destination block. SmartWare Spreadsheet automatically positions the data in the specified area.

Block Marking


 Columns. Enter the number of columns you want to move (beginning with the current column and counting right), and then the column number where you want the columns of data to appear.

Row-Column Marking


 Rows. Enter the number of rows you want to move (beginning with the current row and counting down); then enter the row number where you want the rows of data to appear.

Row-Column Marking


Edit Sort

The Edit Sort command sorts data in designated areas of your worksheet into ascending or descending order, by rows or by columns. You can specify up to 15 sort levels, including the primary sort key.
IMPORTANT: Accented or "double" foreign language characters may not sort properly unless you select the character comparison table for that language. To select a character comparison table, select Tools Preferences Global and move the cursor to the Character Comparison Table: prompt. Press F6 to display a list of languages for which character comparison tables have been installed. Select the language you will be sorting.


 Sort Area. When executing the Edit Sort command, you are prompted to enter the name or block reference of the area containing the data to be sorted.

Block Marking


 Ascending or Descending. SmartWare asks you to specify either an ascending or descending sort, which will be the default order unless you specify additional sort orders. Basically, an ascending sort of text organizes the alphabetic data A through Z. A descending sort would be Z through A. An ascending sort of values begins with the lowest value. A descending sort of values begins with the highest value.
NOTE: Rather than being determined by a dictionary-type sort, the actual ordering of characters is based upon the SmartWare character set. Therefore, foreign characters may appear to be out of sequence.


 Row or Column. Select either Row or Column, depending upon how the sort key information is arranged. The sort key is the area containing the rows or columns upon which the sort is based. To sort by data in specified rows, select the Row option. To sort by data in specified columns, select the Column option.


 Sort Key. You are then prompted to define the sort key by entering the row or column number(s).

To specify multiple levels of sorts, separate the sort key row or column numbers with spaces. Enter the primary sort key first, followed by the second level, the third level, and so on.

To specify a different order than the default for any sort key, type an "a" (ascending) or "d" (descending) after the row or column number.

Example:

     Edit Sort r2:20c1:30 ascending using column "1 3 4d"

The block, consisting of rows 2 through 20, columns 1 through 30, is sorted, using column 1 (ascending order) as the primary sort key and column 3 (also ascending order) as the secondary sort key. The next level of sorting is based upon column 4 in descending order.

Formulas in the sorted block are automatically adjusted to reflect the correct cell addresses.


File Commands

The File commands allow you to perform direct file and file accessing operations. These commands provide storage, security, access, and retrieval capabilities for managing and maintaining your worksheet files.

The File keyword provides the following command options:

Load. Copies a worksheet into memory and displays it in the current window.
Save. Records the current worksheet in a file.
Unload. Deactivates a worksheet and removes it from the current window.
Activate. Loads a worksheet into memory but does not display it in a window.
Newname. Allows you to change the name of your current worksheet.
Display-Active. Displays the files currently loaded in memory.
Combine. Joins two worksheets by adding, subtracting, or copying data from an external worksheet to the current worksheet.
Import. Allows you to read various file formats into your current SmartWare worksheet and to interface with other popular program file formats.
Export. Allows you to write worksheets to files and to convert your files to popular program file formats.
Password. Attaches or removes a password from a file to restrict access to it.


File Load

File Open

This command copies a worksheet into memory and displays the worksheet. With pulldown menus this command is called Open while on command lists it is load. In both cases it is accessed from the File menu.


 When selected, SmartWare displays a file promptor or Windows dialog box requesting the name of the worksheet to load.

You can select a worksheet from the displayed listing, or, if the worksheet you want is not in the directory, you can type the name of the worksheet you want, including the device and path specifications.

The remaining instructions refer to the SmartWare file prompter.

Searching for Specific Files

When you need to search for a specific file but you don't know its path, press F4 and enter its name at the prompt Enter the file specification. If you do not specify a path, SmartWare first looks for the file in the current directory and then searches its subdirectories. If you specify a path, SmartWare looks first in that directory and then searches through its subdirectories until the file is found or there are no more subdirectories to search.

When the file is found, the message File was found in <location> - Continue searching? (y/n) is displayed. Enter n if you do not want to search other directories. The name of the file will appear on the command line. You can press Enter to execute the current command on the file, or press F8 to clear the command line.

Enter y if you want to continue searching other directories for the file. When the filename is not located in any other directory, the message End of search, press any key is displayed.


Displaying Directories Within a File List

In addition to listing files, file prompters also display subdirectories of the current directory. Directories are listed after files and are identified by the path symbol (\). For example files\ indicates a subdirectory of the current directory named files.

If you point to a directory and press Enter, the prompter displays files and subdirectories in the newly selected directory. The current path is identified on the Status Line. Continue selecting directories until you find the file you want.

You will be prompted to enter the password if one has been assigned to the selected worksheet. If you respond with the correct password, the worksheet is loaded into memory. If you enter the wrong password, the message Incorrect password will be displayed.

The Quick Key for the File Load command is Alt-L.

File Activate
File Unload
Sheet Goto Sheet
File Password


File Save

The File Save command copies a specified worksheet (including all changes) to a file, without removing it from memory. Saving the current worksheet does not remove it from the current window. If the worksheet already exists as a file, the new version replaces the old version.


 After you select the File Save command, SmartWare prompts you to enter the name of the worksheet you want to save. If the worksheet is new and you have not yet assigned a name to it, SmartWare prompts you to enter a name for the unnamed worksheet. You can enter a maximum of 8 characters, consisting of letters, numbers, or underscore characters (_); we recommend that you begin all names with a letter. A worksheet name can contain no blank spaces.
NOTE: Beginning a name with a number could cause an error if the name is used as an external worksheet reference in a formula.

When you save a new worksheet for the first time, the worksheet in the current window is stored under the indicated name, and the status line changes from "none" to reflect the name of the worksheet.

A new worksheet is automatically saved in the current or default directory. An existing worksheet is saved in the directory from which it was loaded, unless you specify otherwise.

Once you have named a worksheet, you do not have to enter the name again when you save it. Pressing Enter in response to the prompt for the name saves the worksheet under the same name in the appropriate directory.

You can create a copy of the worksheet by typing a different name in response to the name prompt. If you attempt to save a worksheet under a name already assigned to another worksheet, SmartWare responds with the message, Worksheet already exists. Continue? (y/n):. Answer y to overwrite the existing file. Answer n to abandon the command.

If you modify a worksheet, you must save it to retain your changes. If you unload the worksheet without saving, your revisions will be lost. SmartWare retains only the last version saved. If you make modifications to a worksheet and want to keep both the modified version and the original, save the new worksheet under a different name.

The Quick Key for the File Save command is Alt-S.

Sheet Lock Protect
File Newname


File Unload

File Close

This command removes a worksheet from memory.


 With multiple worksheets activated, SmartWare prompts you to enter the name of the worksheet you want to unload. You can unload the current worksheet by simply pressing Enter. Or, you can enter the name of any worksheet currently on the active status list. If other files are active, the one most recently loaded will be displayed on the screen.

If you want to deactivate all active worksheets, type all when SmartWare asks for the name of the worksheet. Before the worksheets are unloaded, SmartWare asks Unload all files without saving? (y/n). If you answer y, all active worksheets are unloaded. If you answer n, the command is abandoned.

If you have modified the worksheet you want to unload, SmartWare gives you the option of saving the changes by prompting: Worksheet has been modified. Save before unloading (y/n). If you answer y, the revised worksheet is stored, using its current name. If you answer n, the revised worksheet is not saved and any changes you have made to it since you loaded or activated it are lost. If you change your mind about unloading, you can press Escape to cancel the command.

The Quick Key for the File Unload command is Alt-U.

File Load
File Save


File Activate

The File Activate command loads a worksheet into memory, without displaying it in the current window.


 When you select File Activate, you are prompted to enter the name of the worksheet to be activated. Worksheets stored in your data directory are displayed in a prompter listing. You can select a worksheet from the displayed listing or, if the worksheet you want is not on the directory, you can enter the name of the worksheet you want, including the device and path specifications.

You can also press F5 and specify a new directory path, or press F4 to instruct SmartWare to search all directories for a file.

You will be prompted to enter the password if one has been assigned to the worksheet being activated. The worksheet will not be loaded into memory unless you enter the correct password.

File Activate allows you to put as many worksheets into memory as your operating system will allow. Once a worksheet has been activated, you can reference that worksheet in formulas in other worksheets.

A worksheet loaded into memory via the File Activate command can be displayed in the current window at any time by selecting the Sheet Goto command or pressing F4, selecting the Sheet option, and entering the name of the worksheet to be displayed.

Prompter Listings
File Display-Active
File Load
File Password


File Newname

The File Newname command allows you to change the name of the current worksheet.


 When you select File Newname, SmartWare prompts you to enter the new name you want to assign to the worksheet. You can enter a maximum of eight characters, in any combination of letters, numbers, or other characters which are considered legal by your operating system. We recommend that you always begin a name with a letter. No blank spaces are allowed in a worksheet name, but you can use an underscore (_) to join characters.

If you enter the name of an existing worksheet for the new name, the following message appears:

     Worksheet already exists. Continue?  (y/n)

If you answer y the name is assigned to the worksheet. If you answer n the command is cancelled. Assigning a new name to an active worksheet changes the name of the worksheet in memory but does not store the worksheet under the new name. Execute the File Save command to save the worksheet using the new name.

The Quick Key for the File Newname command is Alt-N.


File Display-Active

The File Display-Active command displays a list of all your currently active worksheets. A worksheet is activated by executing either the File Load or File Activate command to place the worksheet in memory.

Index of Active Worksheets. After File Display-Active is executed, an alphabetical list of all currently active worksheets appears over the current worksheet window. This list, called the Index of Active Worksheets, contains the names of all your active worksheets, the number of entries and formulas contained in each active worksheet, and the status of each worksheet. The status information indicates whether the worksheet has "save permission" and whether the worksheet has been modified since it was last saved.

The Index of Active Worksheets also shows the path for each worksheet not in the default directory. If the path is too long to fit in the allotted area, the path description is truncated, beginning at the left. An ellipsis indicates that truncation has occurred.

Press any key to remove the active worksheet list from your screen and return to your SmartWare worksheet.

The Quick Key for the File Display-Active command is Alt-A.

File Activate


File Combine

The File Combine command merges the numeric data from an external worksheet with numeric data in the current worksheet by calculating the combined value of specified cells from both worksheets. The resulting values are placed in the current worksheet, beginning at the current position of the highlighter. The external worksheet need not be active.


 The File Combine command allows you to select either the Add, Copy, or Subtract option. SmartWare prompts you to enter the name of the external worksheet, which you can choose from a prompter listing.


 SmartWare then asks you to specify either that the entire external worksheet (by selecting Worksheet) or a block of cells from the worksheet (by selecting Block) be combined with the current worksheet. If you elect to use a block, SmartWare prompts you to specify the name or block reference. Because you are referring to an external worksheet, you must type the name or reference to be used; blockmarking is not allowed.

If cells in the destination worksheet are locked, the message Some cells are locked. Continue?(y/n) If you specify Y the command continues, avoiding locked cells. If you specify N the command is aborted.

The options for the File Combine command are as follows:


 File Combine Add. The File Combine Add command adds the values contained in a specified worksheet (or block of the worksheet) to values in the current worksheet. The addition calculations are done cell-by-cell, based upon the position of the highlighter in the current worksheet at the time the command is executed.


 File Combine Copy. The File Combine Copy command replaces values in the current worksheet with values from the specified worksheet, rather than adding or subtracting them. File Combine Copy also copies formulas and text. The data from the external worksheet is copied into the current worksheet, beginning at the current cell.


 File Combine Subtract. The File Combine Subtract command subtracts the values contained in the specified worksheet (or worksheet block) from values in the current worksheet. The subtraction calculations are done cell-by-cell, and are based upon the position of the highlighter in the current worksheet at the time the command is executed.


File Import

The File Import command lets you read three types of ASCII text files, a Lotus 1-2-3 Release 1A or 2 worksheet file, a SYLK (Symbolic Link) format file, or a DIF (Data Interchange Format) file into the current window. This command provides a powerful interface with many popular program file formats and converts the data received from those files into SmartWare worksheet files.

File Import reads DIF, SYLK, Text, and 123 files into your worksheet window. The File Import Text command can be used to read a file saved by another SmartWare module. However, if you simply want to copy one SmartWare worksheet into another, use the Edit Copy command.


 DIF. If you select DIF, enter a complete file specification, including the file extension, if there is one. SmartWare will then display, in your current worksheet window, the Data Interchange Format (DIF) file you specified.


 SYLK. If you select SYLK, enter a complete file specification, including the file extension, if there is one. SmartWare will then display, in your current worksheet window, the SYLK (Symbolic Link) Format file you specified.
IMPORTANT: The following SYLK functions are not supported by SmartWare Spreadsheet: WEEKDAY, DELTA, FV, ISREF, ITERANT, LOOKUP, MIRR, NAME, NPER, PMT, PV, RATE, SIGN, and IRR. If formulas containing these functions are encountered by SmartWare while importing a SYLK file, SmartWare displays the following message in the Control Area of your screen:

     Unable to convert formula at (r#c#) - Continue?  y/n

Answer y to continue importing the SYLK file. The specified cell in the SmartWare worksheet will contain the result of the formula that was stored in the SYLK file, not the formula itself. Answer n to abandon importing the SYLK file beyond the cell that contained the unsupported function.

Several of the unsupported functions can be replaced with similar SmartWare functions.


 Text. If you select the Text option, enter a complete file specification, including file extension. After the command is completed, the window will contain a worksheet generated from a flat text file, a standard ASCII text file, or a Smart format file.

"Flat text" is the output commonly derived from "print to disk" options in many software packages. Normally .txt is the default extension for text. "Standard ASCII text" is a popular comma-delimited output format. The extension .asc is the normal default for ASCII text. "Smart format" is a space delimited output format. A Smart format file is usually created by another SmartWare module, utilizing the originating module's File Export command. The extension .dat is the normal default for Smart format files.

Normally, when a text file is imported into your SmartWare worksheet window, each line of text is placed in a separate row and each word of text (character string) is placed in a separate cell.


 123, R2-123. Select the 123 or R2-123 option to read a Lotus 1-2-3 Release 1A or 2 worksheet file, respectively, into the current worksheet window. You are prompted to enter the worksheet name. Once the Lotus worksheet is displayed in your SmartWare worksheet window, you can edit the file and save it as a SmartWare worksheet file.

SmartWare automatically converts formulas, functions, and worksheet formats as it reads a Lotus worksheet file. SmartWare also checks for names that might be interpreted within the SmartWare environment as keywords. When a conflicting name is encountered, SmartWare displays the message Invalid username (name). Enter a replacement name.


File Export

The File Export command enables you to write all or part of a worksheet to a file in a format that can be read by another SmartWare module. In addition, by selecting a format designed to interface with other program file formats, this command allows you to convert your SmartWare worksheet files to other formats, establishing a powerful and effective interface with many popular programs.


 When you select File Export, SmartWare asks you to indicate whether you want to export the entire worksheet or only a block of cells to a file. Selecting Worksheet exports the entire worksheet based on the widest row. If you select Block, enter the block name or reference.

Block Marking


 Format options include ASCII, DIF, WP-Doc, Smart, Text, Lotus 1-2-3 (Release 1A), and Lotus 1-2-3 (Release 2). Once you have chosen a format, enter the filename of the file to be created. SmartWare automatically assigns a default extension based upon the file type. You can override the default by entering an extension with the filename. Include device and path specifications if necessary.
IMPORTANT: When a SmartWare worksheet is written into either of the Lotus 1-2-3 formats, formulas are converted to the proper format for calculation in 1-2-3. However, a number of functions available in SmartWare Spreadsheet are not supported in Lotus 1-2-3. Formulas containing these unsupported functions are converted to text entries. Also, because the maximum formula length in Lotus 1-2-3 is 240 characters, any SmartWare formulas over 240 characters in length are truncated and written as label entries in the 1-2-3 file.

The options are as follows:


 ASCII. If you select the ASCII option, SmartWare writes out The file in a standard ASCII, comma-delimited format suitable for exporting to Microsoft or MicroPro products. The suffix .asc is the default extension for ASCII files.


 DIF. If you select the DIF option, SmartWare writes out the file in Data Interchange Format (DIF). DIF files can be shared by many unrelated programs, so worksheet files written in DIF format can be accessed by many other spreadsheet programs. The suffix .dif is the default extension for DIF files.


 WP-Doc. If you select the WP-Doc option, SmartWare writes out the file in a format that can be read by the SmartWare Word Processor. Any special fonts defined for cells are retained in WP-Doc format. The extension .doc is the default for SmartWare Word Processing documents.


 Smart. If you select the Smart option, SmartWare writes out the file in a Smart, spaced-delimited format, compatible with other SmartWare modules. The extension .dat is the default extension for Smart format files.


 Text. If you select the Text option, SmartWare creates a standard flat text file (rather than an ASCII file or a Smart text file). The Text format is basically a screen image format, padded with spaces and not delimited. Special fonts are not retained in Text format. The extension .txt is the default extension for text format files.


 123. If you select the 123 option, SmartWare creates a file in a format that can be accessed by Lotus 1-2-3, Release 1A. SmartWare automatically assigns the extension .wks to the new file.


 R2-123. If you select the R2-123 option, SmartWare creates a file in a format that can be accessed by Lotus 1-2-3, Release 2. SmartWare automatically assigns the extension .wk1 to the new file.


File Password

The File Password command provides worksheet protection by allowing you to assign a password to a worksheet.
Comment: The encryption driver is specified in the Tools Preferences Spreadsheet definition menu.

When you attach a password to a worksheet file, the data contained in your worksheet becomes encrypted, preventing people without the required password from reading your worksheet files. In addition, unauthorized users are prevented from seeing your files through other debugging tools.

Options for File Password include Attach and Remove.


File Password Attach

Attach a password to a SmartWare worksheet by selecting the File Password Attach command. SmartWare prompts you to enter the password you want. The password will not be displayed as you type it. SmartWare then asks you to enter the password again. This is to verify that you typed the word correctly the first time.

Passwords can contain from one to sixteen characters, and may contain imbedded spaces.
IMPORTANT: Passwords are case sensitive. For example, if you assign "Test" as a password, you cannot load the worksheet by entering "TEST" or "test."

After executing the File Password Attach command, you must then execute the File Save command to save the worksheet and retain the new password.


File Password Remove

Remove a password from a SmartWare worksheet file by loading the worksheet and selecting the File Password Remove command. The password is removed immediately but you must then save the worksheet to retain the "no password" status. The worksheet will no longer be encrypted.


Graph Commands

The Graph commands allow you to generate a variety of useful graphs based on data in a SmartWare worksheet. In all, 21 distinct types of graphs can be generated, customized, printed, plotted, and exported to other applications.

The Quick Key for the Graph command is Alt-G.

Options for the Graph command include the following:

Convert. Convert files between CGM and BMP graphic formats.

Quick. Provides a shortcut method of generating a graph based on default settings and a special block of worksheet data.

Define. Creates a graph definition file, which allows you to specify the graph type, the worksheet data, and any titles, footnotes, colors, fonts, patterns, etc. to be used on the graph.

View. Displays a selected graph or CGM/GMF file on the screen.

Metafile. Generates a CGM file (computer graphics metafile) based on a specified graph definition file.

Print. Prints a specified graph or CGM/GMF file to the currently selected printer.

Xy-Plot. Plots a specified graph or CGM/GMF file to the currently selected plotter.

Erase. Deletes a specified graph definition file or metafile from the current data directory.

Set-Default. Changes default settings for new graph definition files, including those created with the Quick option.


Convert

The Graph Convert Bmp-To-Cgm and Cgm-To-Bmp commands convert graphic files to and from bitmap and CGM formats.

When you select one of these commands, a prompter containing the possible source filenames in the current path is displayed. Select a file or enter a name at the prompt. Following this you are prompted for the destination filename.

Converting from CGM to BMP format also requests a bitmap width and height; 640x480 is a common screen size. Note that the value for height is an optional entry since it can be calculated by ANGOSS.


Quick

The Graph Quick command allows you to generate a special graph definition file and view the resulting graph without making entries on a Graph Definition menu. To do this SmartWare combines the defaults established using the Graph Set-Defaults command with a specially arranged block of worksheet cells.

When you select Graph Quick, five options appear on the menu: Business, High-Low, Scientific, Elevation, and Text. These are the five classes of graphs that reference worksheet data. The sixth class, composite graphs, is based on existing CGM/GMF files.

Three of the five classes, Business, Scientific, and Elevation, have multiple graph types within the class. If you select one of these, you must also select a graph type. When graph class and type are selected, you are prompted to mark the data block to be used in the graph. Mark the block and press Enter. The graph appears on the screen. When you are finished viewing the graph, press any key to continue.


Data Blocks for Quick Graphs

The Graph Quick command assumes that your worksheet data is arranged in a specific manner. The section titled Creating Quick Graphs in your spreadsheet manual contains a series of figures that illustrate this arrangement.
NOTE: If any part of your data block is missing, SmartWare interprets the block as best it can, usually substituting numbers for missing components.

Business graphs have up to four parts to their data blocks. The title goes in the top left corner of the block. If series are arranged in rows (row order), series names are in a column under the title and division names are in a row to the right of the title. If series are arranged in columns (column order), these two positions are reversed. The rest of the block contains the data values.

High-low graphs have separate plots for each individual index or security. Divisions (stocks) have three values per series (interval): the high price, the low price, and the closing price for the covered interval. For a row order block, the title is in the upper left corner with division (stock) names to the right and series (interval) names below. For a column order block, division and series names are reversed.

There must be two blank cells following each series name on a high-low graph. These allow space for the three series values per division. The series name must be in the first cell for the series, aligned with the "high" values. In each division, the second series cell must contain the "low" value, and the third series cell, the "closing" value.

Scientific graphs have two values per series. On Xy graphs, these are the X and Y coordinates for each series item. On polar graphs, they are the item's radial and angular components. For row order blocks, the title is in the upper left corner with series names below it. For column order blocks, the title is in the upper left corner with series names to the right. Because division names do not appear on scientific graphs, the cells that normally contain them are left blank.

A blank cell must follow each series name to allow space for the two values associated with each series. Within each division, the first value for a series must be the X or radial coordinate and the second value, the Y or angular coordinate.
IMPORTANT: Angular coordinates on polar graphs must be expressed in radians.

Elevation graphs have a single two-dimensional matrix of values rather than a group of individual series. As a result, you do not have to specify row or column order for an elevation graph block. The labels down the left side of the block are called row names. Those across the top are called column names.

Text graphs have simple data blocks consisting of one-dimensional cell arrays. Each cell represents a line of text and can include embedded text control characters. Cells containing values are converted to text strings and displayed using the cell's numeric formatting.


Generating a Graph Definition File from a Quick Graph

Each time you generate a quick graph, a new version of a file named quick.gdq is created. This file records the cell reference last used to create a quick graph. While quick.gdq itself cannot be viewed or printed, by editing it on a Graph Definition menu, you can combine the reference it contains with the current default settings to create a complete graph definition file. If you do not create a graph definition file from quick.gdq, the information it contains is overwritten the next time the Graph Quick command is used.

To create a graph definition file based on quick.gdq, select Graph Define from the Spreadsheet menu. Then select the graph class that corresponds with the last quick graph you generated. When the file prompter appears, select quick.gdq and press Enter. A definition menu appears, complete with default settings established with the Graph Set-Default command and cell references from quick.gdq.

Edit the settings, if necessary, using the techniques described in this section, then press F10 to exit and save. If you changed the entry in the Filename field (recommended), the file is saved under that name. Otherwise, it is saved as "quick," with the extension for the graph class you selected.
IMPORTANT: While quick.gdq can be used to create a definition file for a class of graph other than the one for which it was created, the result is usually meaningless. It is important therefore to remember the class of graph for which quick.gdq was last updated and use it to create a definition file for that class only.


Define

The Graph Define command allows you to create or edit graph definition files, which contain the settings and worksheet references necessary to generate a specific graph. When you select Graph Define, a list of options appears representing the six classes of SmartWare graphs. Select a class, then enter the name of the file you want to create or edit.

To edit an existing definition, select a filename and press Enter. To create a new definition, type a filename at the prompt and press Enter. In either case, a Graph Definition menu for the selected class appears. Edit the definition then press F10 to save the changes or Escape to abandon them.

Graph Terminology
Components of a Graph
Making Entries on a Graph Definition Menu
Moving the Cursor on a Graph Definition Menu
Entering the Filename and Graph Type
Defining the Plot
Data Settings for Business Graphs
Data Settings for High-Low Graphs
Data Settings for Scientific Graphs
Data Settings for Elevation Graphs
Text Settings
General Settings
3d Settings
Axis Settings
Plot Interior Settings
Defining the Legend
Defining Titles and Footnotes
Defining Text Graphs
Defining Composite Graphs
Defining Areas
Common Definition Items
Worksheet References
Colors
Line and Fill Patterns
Border Types
Symbols
Fonts
Character and Line Sizes
Text Control Characters


Components of a Graph

Each business, high-low, scientific, and elevation graph is divided into five distinct areas: the plot area, the title area, the legend area, the footnote area, and the background area. The plot and background areas are always present. Use of the others is optional. Each of the five areas has its own border and fill settings.


Plot Area

The plot area is the part of a SmartWare graph where values from your worksheet are depicted graphically. On non-pie graphs, it consists of a backdrop called the plot interior, two or three axes, and a group of objects used to represent worksheet values. On pie graphs, it consists only of a series of pies representing the divisions in your worksheet data. Pie graphs have no plot interior and no axes.

The plot interior is a rectangle or circle that serves as a backdrop for the plotted data. It has border and fill characteristics separate from those of the plot area itself. On non-pie 2d graphs except polar graphs, the plot interior is a rectangle. On polar graphs, it is a circle. On all 3d graphs, including surface and wireframe graphs, it is the pair of rectangles that form the "walls" at the back of the plot.

The axes can have up to five components each: a line, a set of tics, a set of grid lines extending across the plot interior, a series of labels, and a title. Each component is definable on the Graph Definition menu. Depending on the type of graph you are defining, different axes are available. On most 2d business graphs, for example, there is a horizontal axis, a vertical axis, and an optional auxiliary axis. On most 3d graphs, there is a horizontal axis, a vertical axis, and a depth axis.
NOTE: The numeric formatting of labels on a measurement axis is taken from the values referenced on the worksheet. For example, if values plotted on a bar graph are formatted as currency with two-place precision, the labels on the vertical axis will have the same formatting.

Plot Interior Settings
Axis Settings


Legend Area

The legend area, when used, appears above, below, or to one side of the plot area. On business, high-low, and scientific graphs, the legend lists the name of each data series and a swatch of color, line pattern, symbol, etc. used to depict each series in the plot. On elevation graphs, it shows the colors used to represent values in the plot.
NOTE: On elevation graphs, the numeric formatting of legend labels is taken from the values on the worksheet. For example, if values plotted on an elevation graph are formatted with three-place precision, the labels in the legend will have the same formatting.

Text Settings
Defining Areas


Title Area

The title area, when used, appears at the top of a SmartWare graph. It can contain up to three 254-character lines either entered directly on the Graph Definition menu or referenced in the current worksheet. For each line of text, a default color, size, and font can be specified. Within a line, any of the SmartWare text control characters can be used.

The lines in the title can be justified within the title area either left, right, or centered. The entire title area can be aligned left, right, or centered on the graph background.

Defining Titles and Footnotes
Text Control Characters
Defining Areas


Footnote Area

The footnote area, when used, appears at the bottom of a SmartWare graph. Other than its position and the fact that text for it cannot be specified using the Graph Quick command, its characteristics are identical to those of the title area.

Title Area
Defining Titles and Footnotes
Text Control Characters
Defining Areas


Background Area

The background area is the large rectangular area that serves as a background for the other four areas on most SmartWare graphs. As with the plot, legend, title, and footnote areas, it has its own independent border and fill settings. The only other setting available for the background area is the margin setting.

The margin setting establishes the distance between all major components on a SmartWare graph. This includes the distance between area borders and between area borders and contents.
IMPORTANT: When both border and fill are turned off for either the plot area or the legend area, the margins inside that area are set to zero and the contents are expanded to fill the empty space. This feature usually facilitates alignment of graph components.

Defining Areas


Moving the Cursor on a Graph Definition Menu

Moving around and making entries on a Graph Definition menu is accomplished using specific keys and key combinations. The following tables list these keys, grouped according to activity.

Keys for moving among fields:

Key | Action
Tab or Enter | Move to the next menu field
Shift-Tab | Move to the previous menu field
Down | Move to the next menu line
Up | Move to the previous menu line
Home | Move to the top of the menu window
End | Move to the bottom of the menu window
PgUp | Scroll up one page on the menu
PgDn | Scroll down one page on the menu
Ctrl-Home | Move to the top of the menu (useful for Project Processing)
Ctrl-End | Move to the bottom of the menu (useful for Project Processing)

Keys for editing tables:

Key | Action
F7 | Add a new line to the current table
F8 | Delete a line from the current table

Keys for setting the graph type:

Key | Action
Spacebar or Right | Move highlighter to next graph type
Backspace or Left | Move highlighter to previous graph type
Ctrl-Left | Move highlighter to first graph type (useful for Project Processing)
Ctrl-Right | Move highlighter to last graph type (useful for Project Processing)

Keys for working with character entry fields:

Key | Action
Right | Move cursor to next character position
Left | Move cursor to previous character position
Ctrl-Right | Move cursor to last character position
Ctrl-Left | Move cursor to first character position
Backspace | Delete the character to the left of the cursor
Delete | Delete the character at the cursor
Insert | Toggle character insert mode on/off
F2 | Edit the current entry
F3 | Clear the current character entry field
F5 | Mark a worksheet block and retrieve the cell contents as text
F6 (when avail.) | Mark a worksheet block or display a list of choices for the current field

Keys for working with multiple choice fields:

Key | Action
Spacebar or Right | Change to next choice
Backspace or Left | Change to previous choice
Ctrl-Left | Change to first choice (useful for Project Processing)
Ctrl-Right | Change to last choice (useful for Project Processing)


Entering the Filename and Graph Type

The first setting on all Graph Definition menus is Filename. If you are defining a business, scientific, or elevation graph, the second setting is Graph Type.

By default the filename setting contains the name you specified with the Graph Define command. Changing the setting allows you to save the definition under a new name. To change the filename and save the definition under a new name, type any legal DOS filename and press Enter.

The graph type setting contains options for each of the graph types available with the selected class. When you select a graph type, groups of settings are added or deleted to configure the menu for that type of graph. To select a graph type, press Spacebar until the desired graph type is highlighted.


 Options for Quit include the following:

Quit. Returns to the operating system.
Main-Menu. Returns to the Main Menu of SmartWare Software System.
Communications. Leaves the Spreadsheet module and enters SmartWare Communications module.
Database. Leaves the Spreadsheet module and enters SmartWare Database module.
Wordprocessor. Leaves the Spreadsheet module and enters SmartWare Wordprocessor module.


Defining the Plot

The plot area is where the numeric information from your worksheet is represented. There are seven types of settings for the plot area: data settings, text settings, general settings, 3d settings, axis settings, plot interior settings, and area settings. All but the area settings are unique to plot area of a business, high-low, scientific, or elevation graph.

Not all settings are available for all graph types. Pie graphs, for instance, have no axis or plot interior settings. And 2d graphs, such as bar, high-low, and contour, have no 3d settings.

Defining Areas


 After you select either Report or No-Report, you are prompted to enter a cell or vector to receive the computed regression coefficients. This vector will be as large as the number of independent variables + 1, because the number of coefficients resulting from a multiple linear regression includes an intercept coefficient plus one coefficient for each independent variable. If you specify a single cell, that cell defines the upper left cell of the column vectors receiving the computed regression coefficients.

Block Marking


Text Graphs

A text graph is one made up entirely of filled-area text. It can contain up to 40 lines employing the full range of SmartWare colors, filled-area fonts, and text control characters. Lines can be entered directly on a Text Graph Definition menu or referenced on the current worksheet.


Text Settings

The text settings control the content and appearance of all text in the plot and legend areas of a business, high-low, or scientific graph.

Series Names, Division Names, Row Names, and Column Names. There are four settings for each group of names. The first is a reference to the names in the current worksheet. The second, third, and fourth specify font, color, and point size, respectively. The settings apply regardless of where the names appear on a graph.

Worksheet References
Fonts
Colors
Character and Line Sizes

Numeric Text. These settings control all labels that are generated automatically by SmartWare, including measurement axis labels and labels supplied to replace missing series and division names. There are three settings for numeric text: font, color, and size.
NOTE: The numeric formatting of labels on a measurement axis is taken from the values referenced on the worksheet. For example, if values plotted on a bar graph are formatted as currency with two-place precision, the labels on the vertical axis will have the same formatting.

Fonts
Colors
Character and Line Sizes


General Settings

General settings are settings that apply to the plot as a whole, rather than to individual series, divisions, or value ranges. The necessary settings vary widely from one graph type to the next. Only those settings that are applicable for the current graph type appear on the definition menu.

Series Width, 2d Series Width, and 3d Series Width. These settings determine the width of objects used to represent series values. On 2d bar graphs, 2d series width specifies the width of bars as a percent of available space. A setting of 100% causes them to touch. On 3d business graphs except pie graphs, 3d series width determines the width of all objects in the plot. On high-low graphs, series width specifies the length of the bars that mark closing prices.

Series Line Width. This setting appears on menus for 2d line, 2d combination, high-low, Xy, and polar graphs. It establishes the width of lines used to plot all series on the graph.

Character and Line Sizes

Contour Line Width. This setting appears only on menus for elevation graphs. It specifies the width of contour lines.

Character and Line Sizes

2d Edges and 3d Edges. These settings appear on menus for business graphs. The 2d edge setting determines the width of outlines around bars, areas, steps, and pies on a 2d graph. The 3d edge setting serves the same function for objects on a 3d graph. (Edge color is always black.)

Character and Line Sizes

Starting Angle. This setting determines placement of the first slice on a pie graph. Legal values are integers from 0 to 360. A value of zero puts the edge of the first slice on a horizontal line extending from the center of the pie to the right edge. As the value increases, this line rotates counterclockwise until at 360 it is again at the zero position. To specify the starting angle, type a value and press Enter.

Slice Sorting. This setting determines the sequence of slices on a pie graph. There are three options: Off, Ascending, and Descending. If Off is selected, the sequence of slices is determined by the order in which series are entered on the Graph Definition menu. If Ascending or Descending are selected, slices are arranged according to ascending or descending size. To specify slice sorting, press Spacebar until the desired option is displayed.

Weighting. There are two settings for weighting: a multiple choice setting and a cell reference. Together they determine the relative size of each pie (division) on a pie graph.

The multiple choice setting specifies the type of weighting and has three options: Off, By Sum, and By Reference. Off causes all pies to be the same size. By Sum causes them to be sized according to the values they represent, with larger pies representing larger total values. By Reference causes pies to be sized according to a series of worksheet values, with larger values resulting in larger pies. To specify weighting, press Spacebar until the desired option is displayed.

If By Reference is selected, you must specify a cell reference for weighting. This should be a block of cells containing one value for each division on your graph.

Worksheet References

Smoothing. These two settings appear on menus for elevation graphs and together determine the smoothness of contour lines and bands. The first is an on/off toggle. To set it, press Spacebar until the desired option is visible. The second specifies the smoothing factor. To enter a smoothing factor, type an integer from 0 to 15 and press Enter. Higher numbers result in smoother contours and slower rendering. Lower numbers result in more jagged contours and faster rendering. Entering a smoothing factor of zero is the same as using the toggle to turn smoothing off.

Display. This setting determines which parts of an elevation graph are displayed and which are hidden. It has four options: Normal, Sides Off, Axes Off, and Surface Only. If Normal is selected, all components are displayed, including the sides. This means the base and any contours projected onto it are hidden from view.

If Sides Off is selected, the sides of the graph are hidden so the base and its contours are visible. If Axes Off is selected, the axes and plot interior are hidden, leaving only the surface and sides. If Surface Only is selected, all components except the surface and its contours are hidden, leaving the surface "floating" in space. To set the display type for an elevation graph, press Spacebar until the desired option is visible.

Surface. These four settings specify the three-dimensional "surface" for a surface or wireframe graph. The first determines the color of the surface itself and affects only surface graphs.

The second setting specifies how surface contouring is accomplished. There are three options: Bands, Lines, and Off. If Bands is selected, contours are drawn as solid bands of color. If Lines is selected, they are drawn as lines. If Off is selected, no contours are drawn on the surface. To set contouring, press Spacebar until the desired option is displayed.

The third and fourth settings determine the color and size of grid lines on the surface.

Colors
Character and Line Sizes

Base. These six settings specify the base for an elevation graph. The first determines the color of the base itself.

The second setting specifies how base contouring is accomplished. There are three options: Bands, Lines, and Off. If Bands is selected, contours are drawn as solid bands of color. If Lines is selected, they are drawn as lines. If Off is selected, no contours are drawn on the surface. To set contouring, press Spacebar until the desired option is displayed.

The third and fourth settings, Edge Color and Edge Size, determine the characteristics of the base outline.

The last two base settings determine how far below the rest of the graph the base is located. Offset Mode has two settings: Auto and Manual. Auto causes SmartWare to determine the offset for you. Manual allows you to do it yourself. If you select Manual, you must also specify a manual offset distance expressed as a percent of the vertical axis. To specify manual offset, type an integer from 0 to 99 and press Enter.

Colors
Character and Line Sizes


3d Settings

The 3d settings allow you to "shape" the three-dimensional aspects of elevation and 3d business graphs.

Object Shading. This setting determines whether certain faces of three-dimensional objects are darkened to enhance the illusion of depth. There are two options: On and Off. To set object shading, press Spacebar until the desired option is displayed.

Elevation Angle. This setting appears on menus for surface, wireframe, and non-pie 3d business graphs. It determines the height from which the 3d plot is "viewed." To specify the elevation angle, type an integer from 0 to 90 and press Enter.

Pie Elevation. This settings appears on menus for 3d pie graphs. It specifies the height from which each 3d pie is "viewed." To specify the pie elevation, type an integer from 0 to 90 and press Enter.

Rotation Angle. This setting determines the angle about the base from which a surface, wireframe, or non-pie 3d business graph is "viewed." To specify the rotation angle, type an integer from 0 to 360 and press Enter.

Viewpoint. These settings determine the point from which a surface, wireframe, or non-pie 3d business graph is "viewed." There are three settings for establishing the viewpoint: X, Y, and Distance.

X and Y determine the point inside the bounding rectangle of the plot that is in the viewer's direct line of sight. To specify either X or Y, type an integer from 0 to 100 and press Enter.

The viewing distance is the distance, as a percent of front-to-back plot size, from which the plot is viewed. To specify the viewing distance, type an integer from 50 to 1001 and press Enter. Shorter distances result in a stronger perspective effect. Longer distances result in a weaker perspective effect. A distance of 1001% disables perspective entirely.

Proportions. These two settings determine the shape of the three-dimensional plot. The first, Horizontal/Vertical, allows you to specify the length of the horizontal axis as a percent of the vertical axis. The second, Depth/Vertical, performs the same function for the depth axis. To change either setting, type an integer from 50 to 1000 and press Enter.

Base. The base settings allow you to specify the appearance and shape of the base on a non-pie 3d business graph. There are four base settings: Side Color, Top Color, Offset Mode, and Manual Offset.

Offset Mode establishes how the "thickness" of the base is determined. There are two options: Auto (automatic) and Manual. If you select Auto, SmartWare establishes the thickness for you. If you select Manual, you determine the thickness yourself with the Manual Offset setting. To specify the offset mode, press Spacebar until the desired option is visible. To specify manual offset, type an integer from 0 to 100 and press Enter.

Colors


Axis Settings

The axis settings allow you to configure the axes on non-pie business graphs and on high-low, scientific, and elevation graphs.
NOTE: The numeric formatting of labels on a measurement axis is taken from the values referenced on the worksheet. For example, if values plotted on a bar graph are formatted as currency with two-place precision, the labels on the vertical axis will have the same formatting.

Display (axis display). There are four settings for determining the basic display characteristics of an axis. The first sets the display mode; the second, the color; the third, the size; and the fourth, the position of tics.

The setting for display mode has three options: Normal, Line-Only, and Off. Normal displays a line, tics, and an axis title. Line-Only displays a straight line and title, but no tics. Off displays no line, no tics, and no title. To set the axis display mode, press Spacebar until the desired option is visible.

There are four options for tic position: Inside, Centered, Outside, and Off. Inside places the tics inside the plot interior. Outside places them outside the plot interior. Centered puts them centered directly over the axis. Off disables tics completely. To set the tic position, press Spacebar until the desired option is displayed.

Colors

Scale Type. This setting is available for any axis used for measurement. This includes vertical, auxiliary, and radial axes, as well as all axes on elevation graphs.

There are three options for scale type: Linear, Log, and Percent. They result in linear, logarithmic, and percent scales, respectively. To select a scale type, press Spacebar until the desired option appears. If Log is selected, you must enter a log base. To do this type a positive number up to 1000.00. and press Enter.

Scale Dimensions. There are five settings for controlling the dimensions of an axis scale. The first is dimensioning mode, for which there are two options: Automatic and Manual. If you select Automatic, SmartWare configures the scale for you, based on the data. If you select Manual, you must specify scale minimum and maximum and the number of major and minor tics.

Scale minimum and maximum are the numeric labels that mark the lower and upper ends of an axis used for measurement. To specify these, type a number from -999,999,999.00 to 999,999,999.00 and press Enter.
NOTE: The value entered for scale minimum must be less than that for scale maximum.

Major tics normally appear at each division, marked value, or series. Minor tics normally appear only at unmarked, intermediate values on axes used for measurement. To specify the number of major or minor tics, type a number from 0 to 99 and press Enter.

Title. There are five settings for the axis title: text string, Font, Color, Size, and Rotation. To specify the text string to be used in the title, type the text and press Enter. Your string can be up to 64 characters long, and can include any of SmartWare's text control characters.

The rotation setting determines whether the axis title is oriented vertically or horizontally. It has two settings: Off and On. If you select Off, the title is oriented horizontally in relation to the graph. If you select On, it is oriented vertically.

Text Control Characters
Fonts
Colors
Character and Line Sizes

Grids. The grid settings allow you to specify attributes of lines that extend from tics through the plot interior. There are three settings each for major and minor grid lines: Pat (pattern), Color, and Size.

Line and Fill Patterns
Colors
Character and Line Sizes


Plot Interior Settings

The plot interior settings control the backdrop behind the plotted data for many graph types. They should not be confused with the area settings, which control the background of the plot area as a whole.

Components of a Graph

Fill. There are four settings that control the fill for the plot interior: an on/off toggle, a setting for fill pattern, a setting for foreground color, and a setting for background color.

Colors
Line and Fill Patterns

Border. Border settings control the lines that mark edges of the plot interior not covered by axes. There are three border settings: an on/off toggle, a color setting, and a point size.

Colors
Character and Line Sizes


Defining the Legend

Colors and symbols displayed in the legend are controlled by plot area settings. Colors and symbols for business, high-low, and scientific graphs are specified in the series information table. Colors for elevation graphs are specified in the contour color table.

Legend labels are controlled by the Text Settings portion of a Graph Definition menu. Attributes for text in business, high-low, and scientific legends are those specified for series names. Attributes for text in elevation legends are those specified for numeric text.
NOTE: The numeric formatting of labels in the legend of an elevation graph is taken from the values referenced on the worksheet. For example, if values plotted on an elevation graph are formatted with three-place precision, the labels in the legend will have the same formatting.

Defining Areas


Defining Titles and Footnotes

The title and footnote areas each display up to three lines of text. The text can be entered directly in the Text Settings table on the Graph Definition menu or referenced on the worksheet. The Text Settings table has space for defining three 128-character lines. Blank lines at the end of the title or footnote are ignored.

Defining Areas

Text. This setting specifies the actual text for a specific line in the title or footnote. It can contain up to 128 characters or, if you prefer, a reference to a cell containing up to 128 characters. In either case, the entire set of SmartWare text control characters is available for bolding, underlining, changing fonts, etc.

Worksheet References
Text Control Characters

Font, Color, and Size. These settings determine the attributes of the line.

Fonts
Colors
Character and Line Sizes

Justification. This settings specifies the horizontal position of the line with respect to the longest line in the title or footnote. There are three options: Left, Right, and Center. If you select Left, the line is aligned flush left with the longest of the three lines. If you select Right, it is aligned flush right. And if you select Center, it is centered in relation to the longest line. Justification has no effect on a single line title or footnote or on the longest line in a title or footnote.
IMPORTANT: The justification setting should not be confused with the alignment setting. Justification controls the position of lines within the title or footnote area while alignment controls the position of the area itself without regard to how lines are justified. Thus, to create a footnote in which all lines are left aligned in a block in the lower right corner of the graph, justification is set to Left and alignment is set to Right.

Defining Areas


Defining the Background

The background of a graph serves as a backdrop for all other graph components. All settings for the background are included in the area settings.

Defining Areas


Defining Text Graphs

The settings for text graphs are identical to those for titles and footnotes with the exception that justification can be specified separately for each line. Up to 40 254-character lines can be included.

To add a line to the text settings table after the current line, press F7. To delete the current line, press F8.
NOTE: Blank lines at the beginning or end of the table are ignored. Blank lines in the middle of the table result in a blank line in the last point size used on the graph.

Defining Titles and Footnotes
Fonts
Colors
Character and Line Sizes
Defining Areas


Defining Composite Graphs

Composite graphs allow you to combine up to eight metafiles with a CGM background to produce a single composite image.

Metafile Name. This setting specifies a metafile to be included in the composite. To enter a metafile name, type the name, including path and .cgm or .gmf extension, and press Enter. Up to 80 characters can be included in the metafile name.
NOTE: Metafiles are rendered in the order they are listed in the table. Thus, if a metafile is to appear "behind" another metafile, it must be listed ahead of it in the table.

Location. This setting determines the location and size of the metafile. There are nine options: Full, Left, Right, Top, Bottom, Top Left, Top Right, Bottom Left, and Bottom Right. Full renders the metafile as large as possible, disregarding the margins setting. Left, Right, Top, and Bottom render the metafile as large as possible in the specified half of the screen or printable area. The last four options render it as large as possible in the specified quadrant. To specify the location, press Spacebar until the desired option is visible.

CGM Bg (CGM background). This setting specifies whether the CGM background is to be rendered. There are two options: Normal and Transp (transparent). If you select Normal, the background is rendered. If you select Transp, it is omitted and objects behind it are visible. To specify the background, press Spacebar until the desired option is displayed.
NOTE: The CGM background should not be confused with the normal background on non-composite graphs. The CGM background is a special background included in composite graph metafiles and some metafiles imported from other applications. It differs from the normal SmartWare background in that it has no specific size or shape, it cannot include a fill pattern, and it can be disabled when the metafile containing it is used in a SmartWare composite graph. You can add a CGM background to a SmartWare metafile by specifying a hollow fill pattern (pattern 0) for the background then making it the only metafile on a composite graph.

Margins. This setting specifies the distance that separates most metafiles from each other and from the edge of the CGM background. Metafiles for which Full is specified as the location are not affected by this setting. Margins are measured in even points. To set the margins, type a number from 0 to 99 and press Enter.

Fill. This setting toggles the CGM background on and off. There are two options: On and Off. On causes a CGM background of the specified color to be included in the graph. Off disables the CGM background. To specify the fill, press Spacebar until the desired option is visible.

Color. This setting determines the color of the CGM background.

Colors


Defining Areas

The five rectangular areas on most SmartWare graphs (plot area, legend area, title area, footnote area, and background area) share certain characteristics that are independent of area content. All can have fill, all can have a bounding border, and all can have a shadow.

Position. The position setting appears only in the area settings for the legend. It determines the position of the legend in relation to the plot area. There are five options: Left, Right, Top, Bottom, and Off. The first four position the legend left, right, above, or below the plot area, respectively. Off disables the legend entirely. To specify the position of the legend, press Spacebar until the desired option is visible.

Alignment. The alignment setting appears only in the title and footnote background settings. It determines the horizontal position of the title or footnote area on the background. There are four options: Left, Right, Center, and Off. The first three align the area at the left, right, or center of the graph, respectively. Off disables the title or footnote entirely. To specify alignment, press Spacebar until the desired option is visible.

Margins. The margins setting appears only in the background area settings. It establishes the distance that separates components on a graph. On text graphs, margins provide a frame around the edge of the graph where no text is printed. On composite graphs, they separate CGM/GMF files from each other and from the edge of the CGM background. On all other graphs, margins separate the areas from each other and the components within areas from the area border.

Margins are measured in even points. To set the margins, type a number from 0 to 99 and press Enter.

Fill. There are four settings that control the fill for an area. The first is a simple on/off toggle. The second establishes the fill pattern, the third the foreground color, and the fourth the background color.

The relationship between the fill pattern, the foreground color, and the background color is a simple one. The foreground color is the color applied to the fill pattern. Therefore, when you select solid fill (pattern 1), only the foreground color is visible. When you select non-solid fill (patterns 2-13), the background color shows through the "holes" in the pattern. When you select hollow fill (pattern 0), the area is transparent and neither the foreground color nor the background color is visible.

Colors
Line and Fill Patterns

Border. There are four border settings for an area. The first is an on/off toggle. The second establishes the type of border; the third, its color; and the fourth, its size (width).

Colors
Border Types
Character and Line Sizes

Shadow. There are three settings for specifying an area's shadow: an on/off toggle, an X offset, and a Y offset. X offset determines how far in the horizontal direction the shadow is displaced from the area border. Y offset determines displacement in the vertical direction.

X and Y offset are measured in points (72nds of an inch). Legal values are integers from -99 to 99. Negative values for X offset cause displacement to the left; positive values cause displacement to the right. Negative values for Y offset cause displacement upward; positive values cause displacement downward. To specify X or Y offset, type an integer value from -99 to 99 and press Enter.


Common Definition Items

In the process of defining graphs, you are asked by SmartWare to make certain choices over and over. Text, for instance, whether in the title area or on an axis must be specified in the same way. This section serves to identify these common definition items and help you understand the choices they present.


Worksheet References

Most of the text and numerical data used on a SmartWare graph is taken from cells in the current worksheet. When you define a graph using the Graph Quick command, the references to these cells are entered for you automatically. Often, however, you will encounter situations that require you to enter them manually.

There are two ways to enter worksheet references from a Graph Definition menu. If you already know the name or address of the block, you can type it in manually. In most cases, however, it is easier to mark the block.

To define a block by marking, place the Definition Menu cursor in the field where the reference is needed and press F6. When your worksheet appears, move the highlighter to one corner of the block and press F2 to drop anchor. Then move the highlighter to the cell at the opposite corner of the block and press Enter. (If the block is for a series information table, you are asked to specify row-order or column order.) The Graph Definition menu reappears and the marked block is entered in the selected field.
NOTE: Sometimes, such as in the series information table, you are required to enter multiple worksheet references. If the blocks to be marked are arranged in a single contiguous group on the worksheet, just place the Graph Definition menu cursor in the first field of the table, press F6, and mark the cells for the entire table. SmartWare will fill in the whole table for you.


Colors

Color is one of the choices you must make throughout the Graph Definition menus. The 16 colors available in SmartWare are listed in the following table. To specify a color on a Graph Definition menu, type its number and press Enter. If you have a color display and do not remember the number of the color you want, press F6. The numbers 0-15 are displayed across the bottom of the screen, each in the color it represents.

No. | Color | No. | Color
0 | Black | 8 | Dark Gray
1 | Dark Blue | 9 | Blue
2 | Dark Green | 10 | Green
3 | Dark Cyan | 11 | Cyan
4 | Dark Red | 12 | Red
5 | Dark Magenta | 13 | Magenta
6 | Brown | 14 | Yellow
7 | Gray | 15 | White


Line and Fill Patterns

Many of the lines and filled areas on a graph can have patterns applied to them. It is often clearer, for example, to differentiate series on a line graph with patterns rather than with colors, especially when using a black-and-white printer.

To specify a line or fill pattern on a Graph Definition menu, type its number and press Enter. If you do not remember the number of the pattern, press F6. A prompter appears listing the patterns by name and number. Move the pointer to the pattern you want and press Enter. The number of the pattern is then copied to the selected field.


Border Types

The five areas on most SmartWare graphs (plot, legend, title, footnote, and background), along with the plot interior, have optional borders and shadows that can be placed around them. These are useful for adding dimension to a graph or for drawing attention to one or more areas of a graph.

To specify a border type, type its number and press Enter. If you do not remember the number of the border, press F6. A prompter appears listing the border types by name and number. Move the pointer to the border you want and press Enter. The number is copied to the selected field.


Symbols

On Xy, polar, and 2d line graphs you can use symbols to mark data points. This is useful when data points must be marked precisely or when special attention must be drawn to them.
NOTE: When symbols are used to mark the data points on a line graph and the line pattern for all series is set to zero (invisible), the result is what is sometimes called a scatter graph.

To specify a symbol, type its number and press Enter. If you do not remember the number, press F6. A prompter appears listing the symbols by name and number. Move the pointer to the symbol you want and press Enter. The number is copied to the selected field.


Fonts

When you specify text in the plot area, title area, or footnote area you must choose one of SmartWare's filled-area fonts. To specify a font, type its number and press Enter. If you do not remember the number, press F6 to display a prompter listing the fonts by name and number. Move the pointer to the font you want and press Enter. SmartWare copies the number to the selected field. For a complete listing of all the characters in SmartWare's filled-area fonts, refer to Appendix B in Software System Manual.


Character and Line Sizes

Text height and line width on Graph Definition menus are expressed in points. A point is a unit of typographical measurement approximately equal to 1/72 of an inch. A two-point line, therefore, is one that is 2/72 or .028 inches wide.

Measurement of text is a little more complicated. Parts of characters in every font extend below the baseline of the font and above the tops of most capital letters. These are called "descenders" and "ascenders," respectively. The point size you specify is the measurement from the top of the ascender to the bottom of the descender plus a small amount of space above and below to prevent lines from touching each other.
NOTE: Because ascenders, descenders, and built-in blank space vary with the design of a font, point size alone is a poor predictor of the size of actual printed characters.

Text is restricted to even point sizes. Line widths can be expressed fractionally, to the hundredth of a point. To specify a point size, type the size, including decimal point, if any, and press Enter.
IMPORTANT: Line and character sizes are based on full-size landscape printouts. When the entire graph is printed at other sizes, point sizes are scaled proportionately.


Text Control Characters

SmartWare text control characters allow you to change certain attributes in the middle of a text string. Using text control characters you might underline a certain word, insert a bullet, or cause part of a line to appear in italics. The following line, for example, causes the word "not" to be underlined:

     All that glitters is %_not%N gold!

Text control characters can be used in any worksheet cell or Graph Definition menu field that contains text that appears on a graph. This includes titles, footnotes, series names, and division names. Their effect is limited to the current line only. They do not carry over into succeeding lines of a title, footnote, text graph, etc. The following is a list of the text control characters available on SmartWare graphs.

Text Control Characters | Effect
%- or %_ | Turns on underline
%= | Turns on double underline
%s | Turns on subscript
%S | Turns on superscript
%N or %n | Cancels the previous underline, double underline, subscript, or superscript
%C[n] or %c[n] | Changes the color of text to n, where n is the number of a SmartWare color 0 - 15. This color will be used until you enter another color change code.
%F[n] or %f[n] | Changes to font n where n is a Font letter A - T. Or, n can be the number of a SmartWare filled-area font currently defined in the Spreadsheet.
%B[n] or %b[n] | Inserts bullet represented by the ASCII value n in SmartWare's Dingbat 1 font. For a complete list of the characters in this font refer to Appendix B in Software System Manual.
%% | Inserts percent sign


View, Print, and Xy-Plot

These commands allow you to render graphs and metafiles on the screen or on the currently selected printer or plotter. The process is similar with each command. To view a graph or metafile on the screen, select Graph View.


 A prompter appears listing all the graph definition files, CGM files, and GMF (SmartWare II version 1.00-1.02) files in the current directory. Select a filename and press Enter.

When you are finished viewing the file, press Escape to return to the Spreadsheet menu.


 To print a graph or metafile, select Graph Print. A prompter appears listing all the graph definition files, CGM files, and GMF (SmartWare II version 1.00-1.02) files in the current directory. Select a filename and press Enter. You are asked whether the file is to be printed in landscape or portrait mode. Select Portrait to print the file as large as possible with the paper oriented normally. Select Landscape to print it as large as possible with the paper turned sideways.

To plot a graph or metafile, select Graph Xy-Plot. A prompter appears listing all the graph definition files, CGM files, and GMF (SmartWare II version 1.00-1.02) files in the current directory. Select a filename and press Enter.
NOTE: You can interrupt the rendering of a complex image by pressing Escape. If the image is being rendered on screen, the interruption is immediate. If the image is being rendered to a printer or plotter, you are first asked to confirm the interruption.


Metafile

The Graph Metafile command allows you to generate a CGM file (computer graphics metafile) based on a graph definition file. CGM files can be used in composite graphs or Word Processor documents, or by other applications that are CGM-compatible.

When you select Graph Metafile, a prompter appears listing the graph definition files in the current data directory. When you select a file and press Enter, you are asked whether you want to convert the text into polygons. If you press Y, a CGM file is created in which each string of text is converted to a series of character-shaped polygons. If you answer N, a CGM file is created in which text prints in the fonts resident in the printer.

CGM files with text converted to polygons print more slowly but look the same on all printers. Those without converted text print faster but the text in them varies in appearance from one printer to the next.


Erase

The Graph Erase command provides a convenient way to erase individual graph definition files and CGM/GMF files. When you select it, a prompter appears listing the definition files, CGM files, and GMF (SmartWare II version 1.00-1.02) files in the current data directory. Select the file to be deleted and press Enter.
NOTE: Graph definition files and metafiles can also be erased using the Tools File Erase command. However, the filenames must be selected from a prompter containing the names of all files in the current directory.


Set-Default

The Graph Set-Default command allows you to choose the initial settings for newly created graph definition files. When you select it, a menu appears listing the six graph classes: Business, High-Low, Scientific, Elevation, Text, and Composite. Default settings apply to all future definition files of the specified class.

When you select a class, a definition menu similar to the normal one for that class appears. Make entries as you would for a graph definition file, then press F10 to save and exit the menu. The new settings will be reflected on all new graph definition files for the class.

Define


Bar Graphs

A bar graph is the most basic type of business graph. It depicts worksheet values as vertical or horizontal bars. The bars vary in length according to the values they represent. Shorter bars represent lower values. Longer bars represent higher values. Bar graphs are versatile and very easy to understand. Because of this they are perhaps the most commonly used graphs, suitable for all presentations that compare discrete values. There are three types of bar graph: normal (2d), 3d, and horizontal.

Bar graphs have either two or three axes. The horizontal axis is the one along which individual bars are arranged, grouped by division. The vertical axis contains the scale against which bars are plotted. (Horizontal bar graphs reverse these two axes.) The depth axis appears only on 3d graphs and serves to separate individual series in "space." The auxiliary axis is an option on 2d bar graphs. It provides a second scale of measurement for selected series and is useful when a single scale is not practical.

The legend of a bar graph contains the names of the series plotted on the graph. Beside each series name is a sample of the shade or color used to represent the values in the series. Use of a legend is optional.

When stacking is enabled on a bar graph, values within each division are represented by bars that are "stacked" on top of each other. Stacking is not available on 3d bar graphs.


Line Graphs

A line graph depicts a block of worksheet values as a group of polylines. Each series in the block results in a polyline with separate color, width, and line pattern. The values within a division are plotted along a line that extends vertically from the division name below the horizontal axis.

Like bar graphs, line graphs lend themselves to a variety of situations. A line graph is most useful when the point of the graph is to demonstrate trends or when the number of divisions makes a bar graph impractical. There are two types of line graph: normal (2d) and 3d.

Line graphs have the same axis and legend characteristics as bar graphs. Two-dimensional line graphs can be stacked, but normally are not. When a stacked graph is needed, an area or step graph is usually a better alternative.


Pie Graphs

A pie graph is the basic graph type for representing a group of worksheet values as parts of a whole. In a pie graph, each pie slice represents a single series value. Each division results in a separate pie labeled with the division name. Pie graphs have legends like those found on other business graphs, but have no axes. There are two types of pie graph: normal (2d) and 3d.


Step Graphs

A step graph is almost identical to a stacked bar graph when bar width is set to 200%. The most noticeable difference is the lack of a line separating series values. Step plots are commonly used as backgrounds for other plot types on combination graphs. There are two types of step graph: normal (2d), and 3d.

Step graphs have the same axis and legend characteristics as bar graphs. Two-dimensional step graphs can be either stacked or unstacked, but are normally stacked. When an unstacked graph is needed, a line or bar graph is often a better choice.


Area Graphs

An area graph (sometimes called a layer graph) is similar to a stacked line graph, but is much more dramatic. Instead of representing each series with a polyline, an area graph uses the filled area between two polylines.

In general, an area graph is a good choice when you must demonstrate a trend and at the same time convey the idea of accumulated mass or volume. There are two types of area graph: normal (2d), and 3d.

Area graphs have the same axis and legend characteristics as bar graphs. Two-dimensional area graphs can be either stacked or unstacked, but are normally stacked. When an unstacked graph is needed, a line or bar graph is often a better choice.


Contour, Surface, and Wireframe Graphs

Contour, surface, and wireframe graphs depict values within a rectangular field. Contour graphs represent the values as color variations. Surface and wireframe graphs show them three-dimensionally. All are appropriate for any situation that involves physical elevation, such as topography and geology, or other "levels," such as rainfall over a given area or noise levels over a factory floor.


 Business Graphs (13 types): Bar, Line, Area, Step, Combination, Pie, Horizontal Bar, 3d Bar, 3d Line, 3d Area, 3d Step, 3d Combination, and 3d Pie


 High-Low Graphs (1 type): High-Low


 Scientific Graphs (2 types): Xy and Polar


 Elevation Graphs (3 types): Contour, Surface, and Wireframe


 Text Graphs (1 type): Text


 Composite Graphs (1 type): Composite


Combination Graphs

A combination graph allows you to plot each series on a graph using a separate graph type. Any combination of bar, line, area, and step graphs can be used. Combination graphs are most useful when a distinction must be made between different types of data that must be shown on the same graph. There are two types of combination graph: normal (2d) and 3d.

Combination graphs have the same axis and legend characteristics as bar graphs. Two-dimensional combination graphs can be either stacked or unstacked.


High-Low Graphs

A high-low graph is used exclusively to present information on stock prices, usually over time. Each series on a high-low graph represents a single security or financial index and results in a separate plot. Divisions are normally time intervals such as days, weeks, months, or years. Legends are available on high-low graphs but are usually unnecessary because series names are already displayed above the individual plots.

There are two axes on high-low graphs: horizontal and vertical. Division names (time intervals) are displayed along the horizontal axis. Prices are displayed along the vertical axis. All plots share the same axis settings. Scaling on all vertical axes is automatic, but the scale range is customized for each plot.


Xy Graphs

An Xy graph is a line graph in which the vertical and horizontal axes are both used for measurement. Series on Xy graphs are composed of multiple Xy coordinate pairs. There are no divisions. An Xy graph is the basic graph type for scientific analysis.


Polar Graphs

A polar graph displays pairs of values within a circular field. One value in each pair represents an angle, expressed in radians. The other represents a distance from the center of the plot. Polar graphs are used in any type of scientific analysis when one value in the coordinate pair is an angle.


Composite Graphs

A composite graph allows you to combine up to eight existing CGM or GMF files to form a single image. Composite graphs are used primarily for combining multiple graphs to form a single image, for adding titles (text graphs) to graphs, and for adding CGM files from other applications to SmartWare graphs.


Graph Terminology

The following is a list of terms that have special meaning in the context of graphs and Graph Definition menus.

Alignment refers to the horizontal positioning of title and footnote areas. There are four types of alignment: left, right, center, and off. Off disables the title or footnote entirely.

Areas are the five rectangular regions that comprise a SmartWare graph. The five areas are the title area, the plot area, the legend area, the footnote area, and the background area.

Area settings are the settings that define the border, fill, and shadow for each of the five areas that comprise a SmartWare graph.

Auxiliary axis refers to a second measurement axis that can be added to the plot on some types of graphs. It is used when plotting all series on the same scale would be misleading or impractical. On bar, line, area, step, combination, horizontal bar, and Xy graphs, the auxiliary axis appears on the right side of the plot opposite the vertical axis. On horizontal bar graphs, the auxiliary axis appears at the top of the plot.

Axis display mode determines how much information is included on an axis. There are three axis display modes: normal, line-only, and off. Normal is the most common. It displays a line, tics, and an axis title, all of which are user-definable. Line-only displays a straight line and a title, but no tics. Off displays no line, no tics, and no title.

Axis titles can be placed next to an axis on a SmartWare graph. They can be entered on the Graph Definition menu itself or in a referenced worksheet cell.

Background area refers to the large rectangular area that encloses title, plot, legend, and footnote areas of most graphs. (See also CGM background.)

Background color is the color that shows through the "holes" in a non-solid fill pattern. (The foreground color is applied to the pattern itself.) When pattern 0 (hollow) is selected as the fill pattern, neither the foreground color nor the background color is visible.

Base refers to the three-dimensional "platform" on which bars, lines, etc. normally rest in most 3d graphs. On surface and wireframe graphs, base refers to the two-dimensional rectangle that appears at the bottom of a plot when the graph sides are disabled by setting Display (general setting) to Sides Off.

Borders are the rectangular outlines that surround the five areas on a SmartWare graph. Borders have three attributes: type (single, double, inside thick, or outside thick), color, and size (expressed in points).

Border type defines how the edge of an area is displayed and printed. There are five border types: none, single, double, inside thick, and outside thick.

Business graphs are the graphs normally used in business. SmartWare can create 13 types of business graphs: bar, line, area, step, combination, pie, horizontal bar, 3d bar, 3d line, 3d area, 3d step, 3d combination, and 3d pie.

CGM background, refers to the special background included in composite graph metafiles and some metafiles imported from other applications. The CGM background differs from the normal SmartWare background in that it has no specific size or shape, it cannot include a fill pattern, and it can be disabled when the metafile containing it is used in another SmartWare composite graph. You can add a CGM background to a SmartWare metafile by specifying a hollow fill pattern (pattern 0) for the background then making it the only metafile on a composite graph.

CGM files (See metafiles.)

Class (See graph class.)

Column names label one side of the data matrix for an elevation graph. In a worksheet block arranged for use with the Graph Quick command, they appear across the top, to the right of the title.

Column order is a method of interpreting a block of worksheet data for use in a graph. When column order is specified, data series are assumed to be arranged in columns.

Combination graphs are business graphs that allow each data series to be displayed using a separate graph type. The graph types allowed in a combination graph are bar, line, area, and step.

Composite graphs are a special class of graphs that allow you to combine the contents of up to eight CGM or GMF files to form a single displayed or printed image.

Contour bands (when shown) depict values as variations in color rather than variations in position along an axis. On a contour graph, each band represents a distinct range of values. Contour bands or lines always appear on a contour graph and can be projected onto the base of surface and wireframe graphs.

Contour color table refers to the table in the Plot Area portion of an Elevation Graph Definition menu where the colors for contour bands and contour lines are specified.

Contour lines (when shown) mark specific values (elevations) on an elevation graph. Contour lines or bands always appear on a contour graph and can be projected onto the base of surface and wireframe graphs.

Data labels (See series data labels.)

Data matrix refers to the block of worksheet cells that contains the data values used in an elevation graph. (Unlike business, high-low, and scientific graphs, the data for elevation graphs is not divided into series but is entered as a single one- or two-dimensional block of cells.)

Data series (See series.)

Depth axis refers to the back-to-front axis on a 3d graph. Normally, individual data series are arranged along the depth axis. (Some rotation angles cause the depth axis to appear in other than a back-to-front orientation.)

Divisions contain one value from each series in a graph. The first division, for instance, contains the first value in each series. When row order is specified during block marking, divisions are assumed to be arranged in columns on the worksheet, with division names (if present) in a row across the top. When column order is specified, divisions are assumed to be in rows, with division names in a column on the left. On most graphs, series values are plotted by division along the horizontal axis, with division names below.

Division names normally appear along the horizontal axis of a graph.

Elevation angle is the vertical angle from which a 3d plot is viewed. It must be an integer from 0 to 90.

Elevation graphs are a special class of graphs that interpret data as height or elevation on a surface. In SmartWare, there are three graph types in the elevation class: contour, surface, and wireframe.

Exploded pie pieces are separated from the rest of a pie for emphasis.

Fill patterns determine how color is applied to the five areas of a graph. When a solid pattern is selected for an area, only the foreground color shows. When a non-solid pattern is selected, the background color shows through the "holes" in the pattern. When a hollow pattern (pattern 0) is selected, the area is transparent and neither the foreground color nor the background color is visible.

Fonts are distinct lettering styles. There are two types of fonts available in SmartWare: internal fonts and filled-area fonts. Internal fonts are defined inside your printer and vary from one printer to the next. Filled-area fonts are special fonts included with SmartWare that can be printed on any printer SmartWare supports. Internal fonts print relatively quickly. Filled-area fonts offer more flexibility, but take longer to print. Graphs use filled-area fonts exclusively.

Footnote area refers to the rectangular area at the bottom of a graph where a one to three line footnote can be displayed. The text for a footnote can be entered directly or referenced in the worksheet and can be justified flush left, flush right, or centered. The footnote area as a whole can be aligned left, right, or centered within the background area.

Foreground color is the color applied to the fill pattern in the five areas that make up a graph (title area, plot area, etc.) When a non-solid fill pattern is selected, the background color shows through the "holes" in the pattern.

GMF files are graphics metafiles created by versions of SmartWare II prior to version 1.5.

Graphs are graphic displays of worksheet data. There are 21 graph types divided into six classes: business (13 types), high-low (one type), scientific (two types), elevation (three types), text (one type), and composite (one type). All except text and composite have five major components: a title area, a plot area, a legend area, a footnote area, and a background area.

Graph classes are the categories into which individual graph types are divided according to data type. There are six graph classes: business, high-low, scientific, elevation, text, and composite.

Graph definition files are created in SmartWare Spreadsheet from a Graph Definition menu. Each contains specifications and worksheet references on which a SmartWare graph is to be based. Graph definition files have extensions that identify them by class: .gdb for business, .gdh for high-low, .gds for scientific, .gde for elevation, .gdt for text, and .gdc for composite.

Graph Definition menus are the six full-screen menus in SmartWare Spreadsheet that allow you to create graph definition files.

Graph sides are the vertical surfaces on the sides of a surface graph that make the graph appear solid. The base of a surface graph is visible only when the sides are disabled.

Graph type describes the specific way in which worksheet data is depicted graphically. In SmartWare, there are 21 graph types: bar, line, area, step, combination, pie, horizontal bar, 3d bar, 3d line, 3d area, 3d step, 3d combination, 3d pie, high-low, Xy, polar, contour, surface, wireframe, text, and composite.

Grids are parallel lines extending from the tics on an axis through the plot interior area. Major grid lines extend from major tics. Minor grid lines extend from minor tics. Width, color, and line pattern can be set individually for each grid type on each axis. (See also surface grid.)

Hiding a series prevents it from being displayed on a graph. A blank space remains in the plot area when a series is hidden. The components of the legend area are repositioned to fill the space left by a hidden series.

High-Low graphs are a special class of graphs used by stock analysts to present the high, low, and closing prices of individual stocks.

Horizontal axis refers to the axis along the bottom of a plot, where divisions are normally marked.

Inside thick is a double border type with an outer border in the width you specify and an inner border twice as thick.

Justification refers to the horizontal positioning of individual lines of text within the title and footnote areas of most graphs. There are three types of justification: flush left, flush right, and centered.

Legend area refers to the part of a graph that shows the color, line pattern, symbol, etc. used to depict each series on a graph. It can be positioned above, below, or on either side of the plot area. Use of the legend area is optional.

Line pattern describes the type of line used to depict a series on a line graph. There are seven line patterns: invisible, solid, dot, dash, dash-dot, dash-dot-dot, and dash-dash-dot.

Location, on a Composite Graph Definition menu, specifies where and how large a CGM or GMF file is to be rendered. On a Business Graph Definition menu, it determines the horizontal position of the title or footnote area.

Manual offset refers to the thickness of the base on a non-pie 3d business graph. It can be established manually as a percent of the vertical axis or automatically by SmartWare.

Margins are blank bands that separate components on a graph. On text graphs, they provide a blank area around the edge of the graph in which no text is printed. On composite graphs, they separate CGM/GMF files from each other and from the edge of the graph. On all other graphs, margins separate the areas from each other and the components within areas from the area border.

Metafiles are the files used to store SmartWare graphs as pictures rather than as definitions. Metafiles generated by SmartWare conform to industry standards and can be used by most programs compatible with the CGM (computer graphic metafile) format. The extension used on CGM metafiles is .cgm. Metafiles with the .gmf extension, which were created in versions of SmartWare II earlier than 1.5, are also recognized by SmartWare.

Multiple choice settings are settings on a Graph Definition menu that allow only specific pre-defined entries. Multiple choice fields are differentiated from character entry fields by the presence of brackets ([ and ]) around the field.

Numeric text is any automatically generated text on a SmartWare graph. Such text appears neither on the Graph Definition menu itself nor in referenced cells. It is displayed along any axis used for measurement and in place of division and series names when none are specified.

Outside thick is a double border type with an inner border in the width you specify and an outer border twice as thick.

Percent scaling is an axis scaling method that plots the highest value on the graph at scale maximum (100%) and labels major tics as percentages.

Plot area refers to the large rectangular area where the data values are plotted on most graphs.

Plot interior refers to the rectangular area(s) on 2d and 3d graphs where grid lines are drawn.

Point size is a typographic measurement based on 72nds of an inch. A two-point line is 2/72 or .028 inches wide. Text set in 24-point type (without extra spacing between lines) is 24/72 or .334 inches from base line to base line. Many measurements in SmartWare are expressed in points.

Polygons are geometric shapes whose outlines are composed of a series of connected line segments. In SmartWare, metafiles can be generated in which text strings are stored as rows of character shaped polygons.

Polylines are lines composed of a series of connected line segments.

Position, on a Graph Definition menu, refers to the location of the legend area in relation to the plot area. There are five legend positions: left, right, top, bottom, and off. Off disables the legend entirely.

Quick is an option on the Spreadsheet's Graph menu that provides a shortcut process for generating graphs by combining default settings with a special block of values and labels in the current worksheet.

Quick graph refers to a graph created using the Graph Quick command.

quick.gdq is a file that contains the worksheet cell reference used to create the last quick graph. It can be edited using the Graph Define command to create a complete graph definition file.

Rotation angle establishes the angle about the base from which a 3d plot is viewed.

Row names label one side of the data matrix for an elevation graph. In a worksheet block arranged for use with the Graph Quick command, they appear down the left side, under the title.

Row order is a method of interpreting a block of worksheet data for use in a graph. When row order is specified, data series are assumed to be arranged in rows.

Scales are the lines, tics, and labels that define an axis.

Scale type specifies the tic positions and numeric labels applied to a data measurement axis. There are three scale types: linear, logarithmic, and percent.

Scale dimensions refer to the minimum value, the maximum value, and the number of major and minor tics on a data measurement axis. They can be established manually or set automatically by SmartWare.

Scientific graphs are a special class of graphs used to plot pairs of worksheet values as mathematical coordinates. There are two graph types in the scientific class: Xy and Polar. Xy graphs plot values on a Cartesian coordinate system. Polar graphs plot values on a polar coordinate system.

Series are distinct groups of values that are plotted on a graph. A series, for instance, might include the closing price of a specific stock for every trading day in a month. When row order is specified, series are assumed to be arranged in rows on the worksheet, with series names (if present) in a column on the left. When column order is specified, series are assumed to be in columns, with series names in a row across the top. On most graphs, each series is represented by a separate shade, color, line pattern, or symbol, which is depicted in the legend beside the series name.

Series data labels are labels you can display in the plot area next to each plotted value in a series. They can consist of the series name, the values from the worksheet, or the values expressed as a percent of scale maximum. Series data labels can be positioned at the top, bottom, or center of the objects in the plot. They are not available on non-pie 3d graphs.

Series information table refers to the table in the Data Settings portion of a Graph Definition menu where series are defined for business, high-low, and scientific graphs.

Series names appear in the legend of most business graphs. On three-dimensional graphs, they also appear along the depth axis.

Series width determines the width of bars on a bar chart. It is expressed as a percentage of the space available to each bar. When series width is 50%, for example, the bars and the spaces between them are equal. When bar width is 100%, bars occupy all of the space allotted to them (i.e., they touch each other).

Shading is the process of darkening one side of objects in a three dimensional plot in order to enhance the three-dimensional effect.

Shadows are black rectangles that can be displayed "behind" any of the five areas that comprise a graph. Shadows are used to give areas a three-dimensional look.

Shadow offset is the distance, in points, between an area border and the edge of its shadow. Shadow offset has two components: X (horizontal) and Y (vertical).

Smoothing is the process of rounding the vertices on line, area, Xy, polar, contour, surface, and wireframe graphs.

Stacking is the process of displaying series elements one above the other rather than in separate columns. Area and step graphs are normally stacked. Bar graphs are sometimes stacked to make a special point.

Starting angle specifies the position of the pie piece that represents the first series on a pie chart. The default starting angle is 0 degrees (i.e., the piece rests on a horizontal line extending from the center to the right edge of the pie).

Surface grid refers to the grid that marks the three-dimensional surface of an elevation graph. The resolution of the surface grid is controlled by the smoothing factor (under General Settings). The higher the smoothing factor the finer the surface grid; the lower the smoothing factor the coarser the surface grid. (See also grids.)

Symbols are marks used to highlight data points on line, Xy, and polar graphs. There are 12 symbol types: none, plus, X, box, circle, diamond, dot, thick plus, thick X, filled box, thick circle, and filled diamond.

Text graphs are a special class of graphs that are comprised only of text. They are used primarily as support material in presentations and for adding titles to composite graphs.

Tics appear along an axis to mark divisions, series, or numerical values. Tics come in two varieties: major and minor. Major tics normally appear at each division on a horizontal axis, each marked value on a vertical axis, and each series on the depth axis. Minor tics normally appear only at unmarked, intermediate values on axes used for measurement.

Title area refers to the rectangular area at the top of a graph where a one to three line title can be displayed. The text for a title can be entered directly or referenced in the worksheet and can be justified flush left, flush right, or centered. The title area as a whole can be aligned left, right, or centered within the background area.

Viewpoint refers to the point from which a 3d graph is "viewed." Three parameters establish the viewpoint: viewpoint X, viewpoint Y, and viewpoint distance. Viewpoint X and Y determine the point inside the bounding rectangle of the plot that is in the viewer's direct line of sight. Legal values for X and Y are integers from 0 to 100. Viewing distance establishes the distance, as a percent of front-to-back plot size, from which the plot is viewed. Legal values are 50-1001%. A distance of 1001% disables perspective entirely.

Vertical axis refers to the axis along the left side of a 2d plot (or the back of a 3d plot), where numeric values are normally marked. On most graphs, the vertical axis is the scale against which numeric values are plotted.

Weighting determines the relative size of each pie in a multi-pie graph. (Divisions on a pie graph are represented by separate pies.) There are three types of weighting: by sum, by reference, and off. Weighting by sum is the default. It causes pies to be sized according to the sum of the values they represent. Weighting by reference sizes pies according to values in a specified block of worksheet cells. When weighting is turned off, all pies are of equal size.


Graph

The pulldown menu Graph command starts the ANGOSS GRAPHICS program. Refer to this program's help system.


Window Commands

The Window commands allow you to control the display of your worksheet window and other worksheet elements, and to utilize SmartWare's multiple windowing features.

Window offers the following options:

Split. Splits screen horizontally or vertically, creating multiple windows.
Close. Returns a split screen to its former state.
Zoom. Expands and collapses the current window of a split screen.
Border. Toggles the display of the border surrounding your worksheet.
Numbers. Toggles the display of column and row numbers.
Paint. Assigns colors to various parts of the worksheet.
Titles. Fixes designated rows or columns in place.
Link. Connects windows for simultaneous scrolling.
Unlink. Disconnects linked windows.


Window Split

The Window Split command enables you to split your current window into two windows at the current highlighter position. You can have up to 50 windows open at one time. The minimum window size is one cell (with a width of one character) without row or column numbers or borders.

The message Window Too Small means there is not enough room to split the window at the current position. The problem can occur when border, and row and column numbers are all displayed. Turn off the display of these items, and try again. Or just move the highlighter and issue the command again.


 When you select Window Split, indicate whether you want a Horizontal or a Vertical split.

Quick Key Alt-H executes a horizontal split at the current highlighter position; Alt-V splits the window vertically at the current highlighter position.


Window Close

The Window Close command closes or removes the current window when you are displaying multiple windows. The remaining windows expand to fill the vacated window space. The Window Close command acts only upon the current window.
NOTE: Windows must be rectangular. If closing a window would result in a non-rectangular window, SmartWare issues an error message telling you that the window cannot be closed. Close a different window first.

When you close a window, the worksheet that was displayed in that window remains active, even though it may not appear on your screen.

Quick Key Alt-W also executes the Window Close command.


Window Zoom

If you have split your screen into multiple windows, you can execute Window Zoom to expand the current window to fill the entire screen. "Zooming" and "unzooming" different windows allow you to see either one specific worksheet or several worksheets in turn.

You can move from one window to another via the Goto command (or pressing F4) even if the current window is zoomed.

Quick Key F7 will execute the Window Zoom toggle command.
IMPORTANT: The Window Close command cannot be executed when a window has been expanded by the Zoom command. Also, a zoomed window cannot be split. To return a window to its normal size, execute the Window Zoom command again.


Window Border

The Window Border command is a toggle command that allows you to turn on or off the border display that surrounds the current window. When the border is toggled off, you can display an additional two rows of worksheet data on the screen. If you are using multiple windows, you can toggle the border display for any of the open windows. The Window Border command acts only upon the border of the current window.


Window Numbers

The Window Numbers command controls the display of column and row numbers in the current worksheet window. SmartWare prompts you to specify whether you want to affect column or row numbers.


 Column. When you select the Window Numbers Column option, the column numbers of the worksheet displayed in the current window will be toggled on or off. When column numbers are toggled off, one additional row of worksheet data is displayed on the screen.

If you are displaying multiple windows and you execute Window Numbers Column to toggle off the display of column numbers in the current worksheet, the window identifier number that ordinarily appears in the upper left corner of the window will also be removed. Toggling off column numbers in several worksheets can remove familiar boundaries that make multiple window work easy.
Comment: Paint windows different colors to mark window boundaries when working without borders, and row and column numbers.


 Row. The Window Numbers Row command is used to toggle on or off the row numbers displayed in the current worksheet window. Depending upon the size of the columns, one or more additional columns of worksheet data may be displayed on the screen.


Window Paint

The Window Paint command allows you to assign different colors to various worksheet parts when the worksheet is displayed on the screen. Saving the worksheet saves the selected colors as well.

When you select the Window Paint command, SmartWare allows you to specify whether you want to paint the window border, worksheet cells, worksheet row and column numbers, or the worksheet window itself.


 Once you have chosen an option, a palette of available background colors is shown in the Control Area of your screen to help you visualize and select a color. A palette of available foreground colors is then displayed against the color you selected as the background color.

If your hardware does not support the 16 available colors, the 16 colors are mapped to the options available for your hardware.


Window Paint Border

A border consists of a narrow line inside a wider line which surrounds the worksheet. The wider line is the border background. The narrow line is the border foreground. SmartWare prompts you to enter a number representing background color for the border. SmartWare then prompts you to select a color for the foreground.


Window Paint Cells

You can choose to paint the cursor (highlighter) and various types of cells. By color coding the different cell types, you can create a colorful, informative "map" of your worksheet.

Select a color for the background, which will be color of the cell itself. Then select a foreground color, which is the color used to display the character contents.

The options are as follows:


 Cursor. Choose the Cursor option to select colors for the cell highlighter.


 Formula. Choose the Formula option to select the colors to be used for cells containing formulas.


 Highlight. Choose the Highlight option to select the colors to be used for cells highlighted by the Sheet Audit commands.


 Locked-Cells. Choose the Locked-Cells option to select the colors to be used for locked cells.


 Text. Choose the Text option to select the colors to be used for cells containing text.


 Value. Choose the Values option to select the colors to be used for cells containing values.


Window Paint Numbers

You can color the row and column numbers of the current worksheet by selecting the Window Paint Numbers command.

Select a color for the row and column number background. The background color can be the same color as the worksheet itself or a contrasting color. Then select a color for the numbers.


Window Paint Window

Paint the worksheet window itself by selecting the Window Paint Window command. All cells except those assigned colors via the Window Paint Cell command are displayed in the window color.


Window Titles

The Window Titles command allows you to freeze one or more rows or columns in place in the worksheet window. Then, regardless of how large the worksheet is, or how you choose to scroll the worksheet data through the window, the rows or columns you have indicated will remain on the screen.
NOTE: You cannot move the highlighter into a fixed title area by using the cursor movement keys. You can enter a fixed title area with the Sheet Goto Cell command.

SmartWare prompts you to specify whether you want to Fix or Drop a fixed title area on the screen.


Window Titles Fix

To freeze titles in position in the window, select the Fix option.


 If you choose to fix a title, SmartWare asks you to indicate whether you want to affect rows or columns. SmartWare then asks you for the number of columns or rows to fix. Columns are fixed beginning with the leftmost column in the window and counting right. Rows are fixed beginning with the uppermost row in the window and counting down.


Window Title Drop

You can remove fixed titles in your worksheet by executing the Window Titles Drop command.

Quick Key Alt-T executes the Window Titles command, placing you at the point where you must select the Fix or Drop option.


Window Link

The Window Link command connects windows so they can be scrolled together at the same rate and in the same direction. When you select the Window Link command, SmartWare prompts you to enter the identifier numbers of the windows you want to link. Enter the numbers, separated by spaces. The current window does not have to be included in the link for the command to execute.
NOTE: The most current Window Link overrides any previous link. For example, if Windows 1, 2, and 4 are linked and you execute the command: "Worksheet Window Link 3 4 5", window 4 is no longer linked to windows 1 and 2. Window 1, however, remains linked to window 2.


Window Unlink

The Window Unlink command disconnects a group of windows you previously linked using Window Link. When you select the Unlink option, SmartWare prompts you to enter the window identifier number for the window or windows you want removed from the link. If you want to unlink all linked windows, press Enter. If you unlink only some of the windows in the linked group, the remaining windows continue to be linked.


Spreadsheet Error Messages

     1000 Preformatted empty cell not found.

Cells can be preset as value cells before any data is entered. When Sheet Find Empty was executed, SmartWare did not find any of these cells in your worksheet. Be sure the highlighter is in the upper left corner of the area to be searched.

     1001 No error found below current cell.

When Sheet Find Calc-Error is executed, SmartWare searches right from the current column and then down from the current row. No formula error was found in the searched area.

     1002 Highlighted cell not found.

When Sheet Find Highlight is executed, SmartWare searches right from the current column and then down from the current row. No cell highlighted by one of the Sheet Audit commands was found in the searched area.

     1003 Specified text not found.

When searching for text, SmartWare searches right from the current column and then down from the current row. The text string you specified was not found in the searched area.

     1004 Specified value not found.

When searching for a value, SmartWare searches right from the current column and then down from the current row. The value you specified was not found in the area searched.

     1020 Insufficient number of observations to compute statistics. Report abandoned.

A regression calculation can be done with as few observations as the number of columns in the matrix, but the statistical calculations on the report require the number of observations to be at least the number of columns plus 1. Define the matrix block to include more observations, or use the No-Report option.

     1021 Equations not independent.

When executing N-Solve, two or more equations in the matrix block are too similar to compute a unique solution. Revise the equations so that the numerical coefficients are not so similar.

When executing Regression, two or more independent variables are almost identical; therefore, a valid regression calculation cannot be performed.

To determine which variable(s) are causing the problem, begin with one dependent variable and one independent variable, and execute the Sheet Matrix Regression command. Add additional independent variables one at a time, and re-execute the command until this message is generated. Then delete the last variable.

     1022 Not enough observations to perform regression.

When executing Sheet Matrix Regression, there must be at least as many observations as there are columns containing independent variables.

     1023 Maximum number of independent variables is fourteen.

You have defined too many columns as independent variables while executing Sheet Matrix Regression. The left-most column in the matrix will be used as the dependent variable. Up to 14 columns to the right of the dependent variable column will be used as independent variables. Delete the necessary number of columns.

     1024 Matrix is singular.

The determinant of the source matrix is singular, i.e., zero, or near zero. Two rows are virtually identical. Review and correct the data before executing the command again.

     1025 Dimensional mismatch.

When you multiply two matrices, the number of columns in the first matrix must equal the number of rows in the second matrix. That is, if Matrix A has m rows and n columns and Matrix B has n rows and p columns, the resulting matrix (A * B) has (m * n) * (n * p) = m rows and p columns. When the number of columns in the first matrix does not equal the number of rows in the second matrix, SmartWare displays the error message and abandons the command. The Sheet Matrix Parallel command requires that all the matrices be exactly the same size. When they are not equal, SmartWare displays the message and abandons the command.

     1026 Transposed block would extend beyond worksheet bounds.

Transposing the block in its current location would place part of the matrix outside the bounds of the worksheet. Move the block of data to an area large enough to permit transposition within the worksheet.


 To remove Count or Test recalculation processing from your worksheet, select Remove.


      1917 Truncation occurred in the entered item.

When entering a long data string, you allowed the input line to exceed the width of the screen. Some of the data at the end of the line was lost. Remember that quotation marks imbedded in the input string are doubled, and both sets of quotation marks are considered to be part of the line.

     1918 Worksheet size is limited to 25 rows by 25 columns.

You are using the limited, demonstration version of SmartWare Spreadsheet and the command you are attempting to execute will cause the worksheet to exceed the maximum size allowed for this version.

     1919 Worksheet size is limited to 256 rows by 64 columns.

You are using the limited, educational version of SmartWare Spreadsheet and the command you are attempting to execute will cause the worksheet to exceed the maximum size allowed for this version.

     1920 Can perform this command only in current worksheet.

You have specified an external worksheet for the command you are trying to execute. This command affects only the current worksheet. To affect the external worksheet, use Sheet Goto Sheet or Sheet Goto Window to make the external worksheet the current worksheet, and execute the command again.


Help Commands

On-line help is available through the Help command. For assistance in running the Tutorial, read the following section. For information on the other Help options, select the appropriate related topic.

Help
Help About-Help
Help Contents
Help Index
Help On-Error


Tutorial

The Help Tutorial command invokes the tutorial for the Spreadsheet module. You may use the tutorial in a step-by-step process to learn the entire module, or you may use it to learn about one particular aspect of the module. If the Spreadsheet tutorial was not installed on your system, use the Changes and Additions option of the Install program to add it at any time.

At the Okay to unload files without saving to run the tutorial? (y/n) prompt, type n and press Enter if you have files that need to be saved first. Otherwise, type y and press Enter.

Enter your name at the prompt Ask for Name.

To use the tutorial as a step-by-step process, select the first option on the tutorial's main menu. If you want to learn about something specific, select the appropriate topic.

The rest of the instructions for using the tutorial are included in the on-line information.


Quit Commands

The Quit commands allow you to leave SmartWare Spreadsheet to enter another module, return to the Main Menu, or return to the operating system. The Quick Key for Quit is F10.

If you have selected the Quit keyword and decide that you do not want to leave SmartWare Spreadsheet, press Escape.


Remember Commands

The Remember commands allow you to create and run project processing files. Project processing is an automated method of executing a sequence of commands.

Refer to Project Processing for detailed information on using the Remember commands.


Sheet Commands

The Sheet commands allow you to audit your worksheets for specific entries or for potential errors, to specify calculation mode and order, to control access to cells and formulas in your worksheets, and to integrate SmartWare Spreadsheet files with other SmartWare module files.

Sheet provides the following options:

Audit. Highlights various kinds of formulas and cells in your worksheets for debugging purposes.
Calc-Mode. Specifies when recalculation is to be done, and in what order. Allows iterative (repetitive) recalculations.
Find. Searches for and moves the highlighter to a cell containing a specified type of entry.
Goto. Moves the highlighter through a worksheet or between worksheets, or from one window to another.
Lock. Restricts access to cells and formulas in your worksheet.
Matrix. Allows you to perform matrix mathematics calculations.
Name. Assigns a name to a cell or block of cells.
Send. Allows you to integrate worksheets with other SmartWare module files.
Unlock. Removes restricted access to cells in your worksheet.


Sheet Audit

The Sheet Audit options highlight cells that contain various types of entries. Use this command to locate and highlight formulas which reference empty or blank cells, all formulas referencing a specific cell, all cells referenced by a formula, unused formulas, and cells containing references to other worksheets.

You can also use the Sheet Audit command to highlight empty cells that have been predefined as value cells, cells containing circular references, or cells containing data not used anywhere.

Highlighting remains with the worksheet until it is edited or until the Sheet Audit Restore command is executed.

When you select the Sheet Audit command, SmartWare asks you to indicate the type of cell entries you want to locate and highlight. Select one of the following options:


Sheet Audit Circular

Select the Sheet Audit Circular command to highlight formula cells containing circular references. A circular reference occurs when a formula directly or indirectly references the cell in which it resides.

SmartWare highlights the first circular reference group it encounters. Determination of the first group is based on natural order calculation. Sheet Audit Circular recalculates the worksheet, using natural order, if:
** the worksheet has been edited but not recalculated, or
** the worksheet has been set for row or column order calculation.

Instruct SmartWare to highlight the next group by pressing F9. Some editing operations (such as inserting columns or rows, or adding new formulas) performed between highlighting iterations, will cause SmartWare to begin at the first reference again.


Sheet Audit Empty

Select the Sheet Audit Empty command to highlight any empty worksheet cells that were predefined as value cells using the Layout Format Block command.


Sheet Audit Formulas

Select the Sheet Audit Formulas command to see what kinds of cells are used by the formulas in your worksheet.


 By selecting Blanks, you instruct SmartWare to highlight any formula cells referencing blank, unformatted cells. Select Xternal to instruct SmartWare to highlight all formula cells that contain references to external worksheets. Selecting Empty instructs SmartWare to highlight all formula cells that contain references to preformatted but empty cells.


 The Child and Parent options allow you to identify the use of cell references in formulas. Selecting Parent highlights formula cells containing references to the current cell. Child highlights the cells referenced by the current cell's formula.

For example, suppose that r3c1 contains the formula "r1c1+r2c1." If you position the highlighter at either r1c1 or r1c2 and select the Parent option, r3c1 will be highlighted. If you position the highlighter at r3c1 and select the Child option, r1c1 and r2c1 will be highlighted.


 Sheet Audit Formulas Unused instructs SmartWare to highlight cells containing formulas which are not used elsewhere in the worksheet.


 Unused. Select Sheet Audit Unused if you want SmartWare to highlight data cells that are not referenced elsewhere in your worksheet. When you select this option, SmartWare asks you to identify the type of data cell to highlight.


 You are given the choice of highlighting all the unused cells in your worksheet, only unused text cells, or only unused value cells.


 Restore. Select the Sheet Audit Restore command to restore your worksheet to its unhighlighted state.


Sheet Calc-Mode

The Sheet Calc-Mode command controls worksheet recalculation. You can choose to recalculate formulas automatically or manually. You can specify the recalculation order. You can also specify iterative (repeated) recalculations. In addition, you can view the recalculation settings for the current worksheet.

Options include Automatic, Manual, Display, Calc-Order, and Iterate.


Sheet Calc-Mode Automatic

The Sheet Calc-Mode Automatic and Manual commands control the timing of recalculations. When you choose Automatic, SmartWare Spreadsheet recalculates formulas as soon as you make changes to the worksheet.


Sheet Calc-Mode Manual

When you select the Manual option, SmartWare waits until you press the recalculation key, F5, before formulas in the worksheet are recalculated. In manual recalculation mode, SmartWare reminds you that your worksheet should be recalculated by displaying CALC on the Status Line after changes are made.


Sheet Calc-Mode Display

The Sheet Calc-Mode Display command displays the current recalculation mode (either Automatic or Manual) and order (Natural, Row, or Column) in the Control Area of your screen. If you have executed the Sheet Calc-Mode Iterate Count command, the iteration count is also shown. If you have executed the Sheet Iterate Test command, SmartWare shows the test cell, the delta value, and the maximum iteration count.


Sheet Calc-Mode Calc-Order

The Sheet Calc-Mode Calc-Order command allows you to control the order in which your worksheet is calculated.


 Natural-Order means that formulas are calculated in the order needed, not in the order of placement in the worksheet. Row-Order means that all formulas in Row 1 are calculated, then Row 2, etc. Column-Order means that the worksheet is recalculated by columns, beginning in Column 1, then moving to Column 2, and so on.
NOTE: Row-Order and Column-Order calculations begin processing in the upper left corner of the worksheet and proceed in the direction indicated. Therefore, if you use Row-Order or Column-Order, proper placement of values and formulas in the worksheet is important. Unless you have a specific reason for using Row-Order or Column-Order, use Natural-Order recalculation.


Sheet Calc-Mode Iterate

The Iterate option of the Sheet Calc-Mode command is used to set conditions that affect the repetitions SmartWare performs when recalculating the worksheet. Iteration can be set to meet a specific number of recalculation passes or specific test conditions. When you select the Sheet Calc-Mode Iterate command, SmartWare prompts you to specify the conditions to establish.


 To set the condition to a specific number of recalculations, select Count and enter the number of repetitions desired. SmartWare will automatically recalculate the worksheet the number of times specified each time the worksheet is recalculated, regardless of whether you are performing Automatic or Manual recalculations.


 To define a specific test condition, select Test. SmartWare prompts you to enter the cell name or the cell reference of the cell containing the test formula.


 SmartWare asks you to Enter delta value:. The "delta value" will be used as the measure of significant difference between the results of one iteration and the next. As long as the difference between the two iterations is greater than the delta value, recalculation continues, up to the number of times specified. When the difference is less than or equal to the delta value, recalculation stops.


 SmartWare then prompts you to Enter maximum number of iterations:. Enter the maximum number of times that SmartWare is to recalculate the formula in the event that the delta value convergence specified in the previous prompt is not attained.

If you find it necessary to stop an iterative recalculation in process, unload the worksheet.


Sheet Find

The Sheet Find command instructs SmartWare to look for and move the highlighter to a cell containing a specified type of worksheet entry.

According to your preference, the program can search a particular block or the entire worksheet to locate formula cells containing errors, empty preformatted cells, highlighted cells, and specific text or value entries. The search is conducted in a forward direction only, beginning at the cell following the current highlighter position, and stops on the first occurrence of the specified cell type or cell entry. You can continue the search by pressing F9 or Alt-R; SmartWare will then move to the next occurrence of the specified type of cell. When the last occurrence has been found, a message appears in the Control Area of your screen, informing you that no more occurrences exist.
IMPORTANT: SmartWare searches left to right, row by row, beginning with the cell following the current cell. Cells to the left of or above the current cell will not be searched. If you want to include the whole worksheet in the search area, position the highlighter at r1c1 before executing the Sheet Find command.

The Quick Key for the Sheet Find command is F3.


 When you select the Sheet Find command, SmartWare prompts you to indicate the section of the worksheet you want to search. If you select Block, enter the name or a block reference of the area to be searched. The description of the block, including a block name, can consist of up to 40 characters. If you select All, SmartWare searches from the cell following the current cell to the end of the worksheet.

Block Marking


Sheet Find Calc-Error

The Sheet Find Calc-Error command searches for formula errors. If an error is found, SmartWare moves the highlighter to the cell and displays an error message in the Control Area of your screen. If no errors are encountered, SmartWare displays the message:

     No Error found below current cell.
NOTE: The Calc-Error option does not find Error 7 which is generated only when a formula refers to a cell containing another error. Correct all other errors and then recalculate to eliminate Error 7.


Sheet Find Empty

Use the Sheet Find Empty command to search for empty cells that have been preformatted as value cells. The highlighter moves to the first cell found.


Sheet Find Highlight

The Sheet Find Highlight command, normally used with a worksheet too large to be displayed on one screen, locates the first occurrence of a cell highlighted by one of the Sheet Audit commands.


Sheet Find Text

The Sheet Find Text command searches for specific text in the worksheet. You are prompted to enter the text string (up to 100 characters) to be located. SmartWare moves the highlighter to the first occurrence of the specified string, ignoring upper and lower case differences.
NOTE: The Sheet Find Text command searches for text cells, or for formula cells returning text results. Formulas themselves are not searched for with this option.


Sheet Find Value

The Sheet Find Value command allows you to find a specific value in the worksheet. You are prompted to enter the value you want to locate. SmartWare then moves the highlighter to the first occurrence of the specified value.


Sheet Goto

The Sheet Goto command allows you to move through a single worksheet, between several active worksheets, or between windows. By executing Sheet Goto, you can quickly and easily change the current worksheet, current worksheet window, or current highlighter position.

The Quick Key for the Sheet Goto command is F4.

When you execute the Sheet Goto command, SmartWare offers the following options: Cell, Sheet, Window or Other.


Sheet Goto Cell

To display a different part of the current worksheet, select the Cell option. Enter either a cell reference (e.g., r10c4) or name.
NOTE: You can also enter the name of a reference in an active, external worksheet (e.g., income.total). The worksheet containing the block name is displayed in the current window. If the block name is not found in any of the active worksheets, SmartWare displays an error message in the Control Area of your screen.


Sheet Goto Sheet

To go to another active worksheet and display it in the current window, select the Sheet option. Type the name of the worksheet at the prompt and press Enter. The previously displayed worksheet remains active, even though it is not in the current window.

If you want to create a new worksheet while other worksheets ar active, select (none) from the file prompter menu. A blank, unnamed worksheet is displayed. You can also use Sheet Goto Sheet (none) to return to an unnamed worksheet in which you have entered data.

If the worksheet that you want to appear in the current window is not active, execute the File Load command.

File Load


Sheet Goto Window

To move the highlighter to a different window on a split screen, select the Window option. Type the window number you want to go to and press Enter.

Press Alt-F8 to go to the next window in the sequence of numbered windows. Press Alt-F7 to go to the previous window.

Refer to the instructions for the Window Split and Window Close commands for more information on using windows.

Window Split
Window Close


Sheet Goto Other

Select the Other option and press one of the cursor movement keys (i.e., Right-Arrow, Left-Arrow, Up-Arrow, and Down-Arrow) to move the highlighter in the direction of the arrow. When the cursor movement keys are used in conjunction with the Sheet Goto command, the keys invoke the following actions:
** If the current cell does not contain data, the highlighter moves in the direction indicated by the cursor movement key until a cell containing data is located. The "filled" cell then becomes the current cell.

** If both the current cell and the adjacent cell in the indicated direction contain data, the highlighter moves in the direction you specified until it finds an empty cell. The last "filled" cell before the empty cell becomes the current cell.

** If the current cell contains an entry but the adjacent cell is empty, the highlighter moves in the direction indicated until it locates another cell that contains an entry. The "filled" cell becomes the current cell.

You can also use the Home, End, Ctrl-Left-Arrow, and Ctrl-Right-Arrow keys with the Sheet Goto Other command to jump to one of the edges of data in your worksheet. Table 9-1 lists the actions and their meanings.

Table 9-1
Key | Action | Meaning
Home | GOTO UPPER-EDGE | The highlighter moves up in the current column to the first row.
End | GOTO LOWER-EDGE | The highlighter moves down in the current column to the last row.
Ctrl-Right-Arrow | GOTO RIGHT-EDGE | The highlighter moves right in the current row to the last column.
Ctrl-Left-Arrow | GOTO LEFT-EDGE | The highlighter moves left in the current row to the first column.


Sheet Lock

The Sheet Lock command is used to safeguard cells in the current worksheet by disallowing changes to their contents. Sheet Lock can be used to prevent the inadvertent alteration of your worksheet, or to permanently conceal its formulas.

Locked cells cannot be edited, deleted, blanked, or overwritten by the Edit Blank, Edit Copy, Edit Delete, or Edit Move commands. In addition, no new information can be entered into locked cells. Formulas can be protected so that they cannot be displayed, edited, or printed. Protected formulas can never be unprotected.

The locked status of cells can be temporarily disabled so that changes can be made. Locked cells can be permanently unlocked by using the Sheet Unlock command. Refer to the instructions for Sheet Unlock for more information on unlocking cells.

The toggle Quick Key for locking and unlocking the current cell is Ctrl-L.

The Sheet Lock command offers the following options: Blanks, Formulas, Text, Values, All, Disable, Enable, and Protect.


 Blanks. When the Blanks option is selected, all cells containing no data or formulas in the current worksheet are automatically locked. This means that you cannot enter any information into new cells.


 Formulas. The Sheet Lock Formulas command preserves cells containing formulas in a selected area.


 Text. Use the Sheet Lock Text command to lock cells containing text entries in a selected area.


 Lock. After you have selected the type of cell to be locked with the Sheet Lock command, you can specify a particular area of the worksheet to be affected: Block, Columns, or Rows.


 Select All to include the entire worksheet in the area to be locked.


 Values. The Sheet Lock Values command locks selected cells containing values in a selected area.


 All. The Sheet Lock All command locks all cells of every type in your worksheet.


 Disable. Cell locking can be temporarily suspended by selecting the Sheet Lock Disable command, allowing you to modify any of the locked cells.


 Enable. To reactivate cell locking, select the Sheet Lock Enable command. SmartWare automatically remembers which cells were locked prior to the execution of the Disable option and restores the locked status for those cells.
NOTE: SmartWare remembers the cells that were locked, not the type of cells. If, in a worksheet with formula cells locked, Sheet Lock Disable is executed, a formula cell is revised to contain text, and then Sheet Lock Enable is executed, the cell will still be locked even though it no longer contains a formula.


 Protect. The Sheet Lock Protect command prevents formulas in the current worksheet from being displayed, printed, or edited. Any new formulas entered into a protected worksheet are automatically protected.

The current worksheet must be unmodified before Sheet Lock Protect is executed; therefore, it may be necessary to execute File Save before selecting the Sheet Lock Protect command. When you select the Protect option, you are prompted to verify that you want to protect the worksheet.
IMPORTANT: Formula protection cannot be removed or suspended. When you save a worksheet after executing Sheet Lock Protect, the formulas are permanently concealed. Save the protected version of the worksheet under a new filename and retain the original version in unprotected form for future use or reference.

When the highlighter is positioned on a protected formula cell (in Data Entry Mode), the word PROTECTED, rather than the actual formula, appears in the Control Area of the screen. If you attempt to edit a protected formula, SmartWare Spreadsheet displays a message to inform you that a protected formula cannot be edited.

Protected formula cells usually recalculate faster and result in a smaller disk file. However, unlike locked formula cells, protected formula cells can be blanked, deleted, or overwritten by the Edit Blank, Edit Copy, Edit Delete or Edit Move commands. To prevent protected formula cells from accidentally being deleted or overwritten, you can also choose to lock these cells.


Sheet Unlock

Sheet Unlock is used to permanently unlock cells that have been locked by the Sheet Lock command. Once a Sheet Unlock command has been executed, the specified cell types in the designated area of your worksheet can be edited as desired. You can unlock blank cells only, formula cells only, text cells only, value cells only, or all the locked cells in the worksheet. Formula protection (Sheet Lock Protect) cannot be removed.

The toggle Quick Key for locking and unlocking the current cell is Ctrl-L.

When executing Sheet Unlock, select from the following options:


 Blanks. Select the Sheet Unlock Blanks command to unlock any blank cells in your current worksheet.


 Formulas. The Sheet Unlock Formulas command unlocks locked formulas in a selected area of your worksheet.


 Values. The Sheet Unlock Values command unlocks locked value cells in a selected area of your worksheet.


 Unlock. When you select the Sheet Unlock command, SmartWare prompts you to specify the type of cell you want to unlock: Blanks, Formulas, Values, Text, or All. If you select either Formulas, Values, or Text as the type of cell to unlock, you can specify the area of the worksheet to be unlocked. Choose Block, Columns, Rows, or All. You will be asked to identify the block, columns, or rows to be affected.


 Selecting All as the area of the worksheet to be unlocked automatically executes the command.


 Text. The Sheet Unlock Text command unlocks any locked text entries in a selected area of your worksheet.


 All. To unlock all cells (regardless of type) in your worksheet, execute the Sheet Unlock All command.

Locking or Unlocking Selected Areas


 For either Sheet Lock or Sheet Unlock, enter a block name or reference or the number of columns or rows, beginning with the current column or row.
NOTE: When locking or unlocking a specified number of rows, the program operates on the current row and the rows below the current row. For example, if you specify 3 rows, the current row plus the next 2 rows are affected. When locking or unlocking a specified number of columns, the command operates on the current column and the columns to the right of the current column.

Block Marking
Row-Col Marking


Sheet Matrix

The Sheet Matrix commands perform a variety of sophisticated calculations. Several of the options are useful in business applications (e.g., the Regression option for performing regression analysis). Other options require familiarity with matrix mathematics or linear algebra.


Matrix Overview

The Aux option of the Sheet Matrix command calculates determinant, rank, and power, and normalizes. The Diagonal option provides sum, product, and copy of the diagonal. The Invert option inverts a matrix. The Multiply option multiplies two matrices.

The N-Solve option of the Sheet Matrix command solves multiple equations with multiple unknowns. The Parallel option provides direct matrix addition, division, multiplication, and subtraction, element by element. The Regression option performs multiple linear regression on values in a specified block.

The Sweep option of the Sheet Matrix command sweeps on one or more pivots. The Transpose option transposes a matrix, converting row data to column data and vice versa. The Upper option converts to row echelon form.

The Sheet Matrix commands deal only with values. Blank cells, text cells, unevaluated formulas, and formulas having text results are considered to have zero value. The exceptions are the Transpose option, where data types are preserved, and the Regression option, which ignores non-numeric data.

In options that return values to an input matrix, non-numeric cells and formula cells are replaced by numeric cells containing the result of the matrix function, except in the Parallel option.

Many matrix options permit the use of the transpose operator. For a named block A, the transpose of A is written as A'. Use the same notation for explicit block references. Thus, write the transpose of r1:7c8:25 as r1:7c8:25' (not r8:25c1:7). You cannot use the transpose operator in commands other than the Sheet Matrix commands. You cannot use the transpose operator in blockmarking. Also, you cannot use the transpose operator to define the following matrix blocks.
** The first block in Sheet Matrix Aux Determinant
** The first block specified in Sheet Matrix Aux Power
** All blocks specified in Sheet Matrix Invert
** The first block specified in Sheet Matrix N-Solve
** The second block specified in Sheet Matrix Parallel
** All blocks specified in Sheet Matrix Upper
** All blocks specified in Sheet Matrix Regression


Source Matrix

Many of the Sheet Matrix commands require you to define a block of the worksheet to be acted upon. The entry can be made manually, or can be selected by block marking. Instructions for specific commands are listed below.

Aux Determinant. You are prompted to enter a matrix block to be used as the source matrix. If the source matrix is not square, the largest sub-matrix, starting in the upper left corner, is used.

Upper. Specify the matrix block to be converted. There are no restrictions on the shape. It may be transposed.


 Aux Diagonal. Enter the name or reference of the block whose diagonal is to be copied, multiplied or summed.


Result Matrix

Many Sheet Matrix commands ask you to specify a block for the result. When a new matrix is created, the location can be specified by defining its upper left corner. The dimensions are automatically computed. Ordinarily, a vector matrix is N rows and 1 column. However, the matrix can be created as 1 row and N columns by specifying the row.

Aux Determinant. You are then prompted to enter the location for the result. The cell to receive the result must not overlap the source matrix.

Upper. Specify the area to receive the result. The new matrix cannot overlap the original.


 Aux Normalize and Rank. The Sheet Matrix Aux Normalize and Rank commands operate upon columns or rows, as you specify. You are prompted to enter the length of the column or row.


 After you choose either the Standard option or the Unit option, select either the Column option or the Row option. If Column is selected, all columns are normalized independently. If Row is selected, all rows are normalized independently.


 Normalize. The Normalize option performs either the standard or unit operation on a row or column. Normalize Standard is a statistical operation that replaces each value in a row or column with its value after normalization to the statistical normal distribution (i.e., with mean equal to zero, and variance equal to one.) The normalization is based on the sample mean and sample variance of the row or column. Normalize Unit scales each row or column in the matrix to the unit vector V in N-space such that SUMSQ(V) = 1.
IMPORTANT: The Normalize option changes the original data.


 Diagonal, Parallel, N-Solve. You are prompted to enter a cell, column vector, or row vector to receive the result. If you enter a cell or portion of a column (column vector), the new matrix is N:1, where N is the number of elements in the diagonal. If you enter a portion of a row (row vector), the new matrix is 1:N. For N-Solve, if you specify a cell or a column, the results will displayed down the column. If you specify a row, the results will be displayed across the row.


 Invert, Multiply. After specifying the source matrix, you are prompted to enter the name or block reference for the block to contain the inverted matrix. Identify the destination block by entering just its upper cell.


Sheet Matrix Aux

When you select the Sheet Matrix Aux command, you can choose the Determinant, Normalize, Power, or Rank option.


 Determinant. The Determinant option computes the determinant of a matrix. The result is placed in the cell you specify.


 Power. The Power option raises a matrix to a power (i.e., multiplies a matrix by itself (exponent-1) times). You are prompted to enter the matrix block, either as a name or block reference, to be operated on. The matrix must be square.

Block Marking


 You are then prompted to enter the exponent, or the power to which the matrix is to be raised. The result is placed in the original matrix when you press Enter.
IMPORTANT: The Power option changes the original data.


 Rank. The Rank option replaces values with their rank, relative to the row or column in which they appear. The largest value receives the value 1, the next largest receives 2, and so on. Select either Column or Row.

To change the ranking from descending to ascending, press F9. This repeats the rank operation on the ranked data.
IMPORTANT: The Rank option changes the original data.


Sheet Matrix Diagonal

When you select the Sheet Matrix Diagonal command, you can choose the Copy, Product or Sum option. No overlapping of matrices is permitted in the Diagonal option.


 Copy. The Copy option copies the diagonal of a matrix, producing a new matrix.


 Product. The Product option computes the product of the diagonal elements and places the result in a cell.


 Sum. The Sum option computes the sum of the diagonal and places the result in a cell.


Sheet Matrix Invert

The Sheet Matrix Invert command uses the Gauss-Jordan method to invert an N:N matrix, producing an N:N matrix. The blocks for these two matrices cannot overlap. If the matrix defined is not square, the largest available sub-matrix, starting in the upper left corner, will be used.


 You are prompted to enter a name or block reference of a matrix block, which will be the source matrix. The source matrix must be non-singular (i.e., the determinant of the matrix is not zero) If you attempt to invert a singular matrix, the following error message appears:

     Matrix is singular

If the coefficients of the matrix are much less than one, use the Sheet Matrix Parallel command to multiply by a constant. Then retry.

Block Marking


Sheet Matrix Multiply

The Sheet Matrix Multiply command performs standard matrix multiplication.


 When you select the Multiply option, you will be prompted to enter three matrix blocks. The first matrix block (A) will be multiplied by the second matrix block (B), and the result will be placed in the third matrix block (C), which cannot overlap either of the two source matrices. Blocks A and B must be matrix blocks.

Matrix B can equal Matrix A, but only if Matrix A is a square. The number of columns in Matrix A must equal the number of rows in Matrix B. Otherwise, the following error message appears:

     Dimensional mismatch

If Matrix A is an M:N matrix, and Matrix B is an N:P matrix, the result matrix is M:P.


Sheet Matrix N-Solve

The Sheet Matrix N-Solve command solves multiple equations with multiple unknowns, using the Gauss-Jordan method of elimination.


 When you select the N-Solve option, you are prompted to enter a matrix block. Enter a name or block reference for a block where the numeric coefficients are located in the left section of the matrix, and the constants are located in the right-most column.

Block Marking

A unique solution can be computed only if the equations are independent. If the coefficients are too similar in effect on the results, the following error message appears:

     Equations not independent


Sheet Matrix Parallel

The Sheet Matrix Parallel command allows a matrix block A and a second matrix block (or value or cell) B to be added, subtracted, multiplied, or divided, element by element. If B is defined as a matrix block, its dimensions must be identical to A. Matrix A and Matrix B can be in separate worksheets.

The result is placed in a third matrix block C, which can be a block or a single cell. It is only necessary to specify the location of the upper left corner of matrix block C. The resultant matrix can overlap part or all of either A or B, or can occupy the entire worksheet. Overlapping matrices must have the same cell as the upper left corner.
NOTE: Text and formula cells in the resultant matrix block are not overwritten.

Select the operation to be performed. The options are Add, Div (divide), Mult (multiply), and Sub (subtract).


 Add. If you selected the Add option, SmartWare adds A and B, placing the result in C. If B is a value or a single cell, the resultant matrix C is the original matrix plus a constant.


 Div. If you selected the Div option, SmartWare divides A by B, placing the result in C. If B is a value or a single cell, the resultant matrix C is the original matrix divided by a constant. The result of any division by zero is zero.


 Mult. If you selected the Mult option, SmartWare multiplies A by B, placing the result in C. If B is a value or a single cell, the resultant matrix C is the original matrix multiplied by a constant.


 Sub. If you selected the Sub option, SmartWare subtracts B from A, placing the result in C. If B is a value or a single cell, the resultant matrix C is the original matrix minus a constant.


 When you select the Parallel option of Sheet Matrix, you are prompted to enter a matrix block. Enter the name or block reference of matrix block A.


 You are prompted to enter a matrix block, value or single cell for matrix B.

Block Marking


Sheet Matrix Regression

The Sheet Matrix Regression command performs multiple linear regression on values in a specified block and places the computed regression coefficients in another specified block. An optional report can be placed in another block. Sheet Matrix Regression can operate with up to 14 independent variables.


 When you select the Regression option, you are prompted to enter a matrix block. Enter the name or reference for the block containing the values from which the regression coefficients are computed. SmartWare assumes the dependent variable values are in the leftmost column, and the independent variable values are in the remaining columns. The regression takes as its first case that row in the data block whose item in the leftmost column is a value, and the last case as the last such row in the block.

Block Marking

If the first row of the data block contains text, that text is interpreted as labels of the variables. The text will be included in the report if you choose the Report option. Any missing value in the data block causes the entire case containing the missing value to be ignored.
NOTE: If two or more independent variables are identical, the following error message is displayed:

     Equations not independent


 No-Report. If you select the No-Report option, you will receive only the regression coefficients.


 Report. If you select the Report option, a multiple linear regression report is produced. You are prompted to enter a name or block reference for a block, 6 columns by (21 plus the number of independent variables) rows. SmartWare will enter the following statistics into this block:
** Analysis of variance table (ANOVA)
** Root of the mean square error (Root MSE)
** Mean of the dependent variable
** Coefficient of variation
** R-square and adjusted R-square values
** The Mean for each variable
** The parameter estimates for each variable (Coefficients entered in the worksheet)
** The standard error estimate for each variable
** The T value of 0 for the test of the null hypothesis (H0)


Sheet Matrix Sweep

The Sheet Matrix Sweep command modifies a matrix on a pivot when you build matrices to perform regression analysis. The Sweep option is not used in conjunction with the Regression option.


 When you select the Sweep option, you are prompted to enter a matrix block. Enter the name or block reference for the sweep matrix.

Block Marking


 You are then prompted to enter the pivot rows. If a pivot is not specified, the current row is assumed. This allows you to move to another row and press F9 (repeat) to pivot according to the current row.

Any number of pivots can be specified during a single command. Specify a series of pivots as follows <start-row>:<stop-row>.

The Sheet Matrix Sweep command is reversible. Sweeping twice on the same pivot is the same as not having swept at all. The order of sweeping is unimportant. Sweeping on row i followed by row i' is the same as sweeping on row i' followed by row i.

The inverse of a matrix is created by sweeping on all rows (pivots).


Sheet Matrix Transpose

The Sheet Matrix Transpose command transposes a matrix (converts row data to column data and vice versa). The transposition occurs in the location occupied by the matrix.


 When you select the Transpose option of Sheet Matrix, you are prompted to enter a matrix block. Enter the name or reference of the block to be transposed.

Block Marking

The transposition occurs in the location occupied by the specified matrix. If the specified matrix is square, the transposition is straightforward. If the specified matrix is not square, additional columns or rows are included in the transposition to make a square.

Beginning in the upper left cell in the specified matrix, SmartWare transposes the specified matrix from, for example, a 6-row by 3-column matrix to a 3-row by 6-column matrix. Data in columns 3 through 6, although not specified as part of the matrix, are included in the transposition to provide a destination for all six rows to be transposed.

The remaining cells in the worksheet are unchanged.

A double transpose of the same area restores the matrix to its original condition.

The Sheet Matrix Transpose command is particularly valuable when you need to change from a row to a column format, or vice versa. For example, when you send or receive information from SmartWare Database, each record is a single row. Each column is a field in a record. The Sheet Matrix Transpose command allows you to change the worksheet to accommodate communication with the Database.
IMPORTANT: Sheet Matrix Transpose does not adjust cell references in formulas.


Upper

The Sheet Matrix Upper command converts to upper-triangular (or row echelon) form using standard forward elimination methods.


Sheet Name

The Sheet Name command is used to assign a name to any cell or block of cells in a worksheet. Once a name has been assigned to a cell or a block of cells, it can be used in a cell or block reference instead of cell or block coordinates.

When you select Sheet Name, SmartWare gives you the choice of defining, editing, printing, or undefining a name.


Sheet Name Define

The Define option is used to assign a name to a cell or block of cells. You are prompted to enter the name of the cell or block and a definition for this name.


 A name can contain from 1 to 15 characters. It must start with an alphabetic character, an underscore, or a pound sign (#). The name can contain digits but cannot contain blank spaces.


 To enter the definition, type the cell or block address, or mark the block. If the definition includes an external reference, precede the external reference with the name of the other worksheet (e.g., sales.r3c4 or qtr1.expenses). The definition can contain up to 35 characters, including cell names and external worksheet references. Named blocks can be used in the definitions of other named blocks. Press Enter to record the definition.

Pressing Enter without entering a cell or block reference uses the current cell reference as the definition.

Press F4 to view a list of existing names and their definitions.

Block Marking
Definition Menus


Sheet Name Edit

The Edit option of the Sheet Name command is used to edit a previously defined cell or block name, allowing you to change the definition. You are prompted to select the name from the prompter menu. When the definition menu appears, revise the definition as necessary.

Prompter Listings
Definition Menus


Sheet Name Print

The Print option of the Sheet Name command produces an alphabetical list of names defined for the current worksheet. Printing begins immediately after you select the option.


Sheet Name Undefine

The Undefine option of the Sheet Name command removes a name from a cell or block. Once a name is undefined, it is no longer recognized in formulas or commands. If you try to remove a name currently used in a formula, an error message will be issued.


 You are prompted to enter the name of the cell or block which you wish to undefine. No prompter menu is shown.


Sheet Send

The Sheet Send command provides you with the ability to integrate SmartWare Spreadsheet with other SmartWare modules. Sheet Send allows you to transmit worksheet data and then automatically transfers you to the destination module.
IMPORTANT: None of the options will send a worksheet file in a format that retains formula entries. If you want to use the SmartWare Communications module to transmit an actual worksheet file, do not use the Sheet Send command. Instead, use SmartWare Communication's Data Transmit XMODEM command to transmit the worksheet file from the disk.

When you select the Sheet Send command, SmartWare lists the modules that are available to receive worksheet data. The options are Communications, Database, and Wordprocessor.


 When executing Sheet Send Communications with the Document, Text, or SmartWare option, you are prompted to enter a name or a block reference. When selecting the Graphics option, you are prompted to enter the graph metafile name. When executing Sheet Send Database, you are prompted to enter the name or reference of the block to be sent to the Database module. After you select one of the options of Sheet Send Wordprocessor, you are asked to specify the worksheet block reference or name, or the name of the metafile to be sent, or both.

Block Marking


 SmartWare Spreadsheet offers further power and integration capabilities by enabling you to attach a project file to the Sheet Send command. This project file is executed when the worksheet or graph file is transmitted. You are prompted to enter the project file name for the next application. If you do not want to execute a project file in the receiving module, just press Enter. Refer to Project Processing Manual for a complete discussion of SmartWare integration capabilities using project files.


Send Communications

If you select the Communications option of the Send command, you have the option of sending a worksheet block in Document, SmartWare, or Text format, or a graph metafile in Graphics format to the Communications module.


 Document. The Document option sends a worksheet block in SmartWare Word Processing format.


 Graphics. The Graphics option sends a graph metafile.


 SmartWare. The SmartWare option sends a worksheet block in SmartWare Data Interchange format, which is a specially formatted ASCII file for transferring information between SmartWare modules.


 Text. The Text option sends a worksheet block in standard ASCII text format.


Send Database

If you select the Sheet Send Database command, you are sending a worksheet block to the Database module. Each row in the worksheet block becomes a record in the Database module. Each column becomes a field.


Send Wordprocessor

If you select Send Wordprocessor, you can send either a worksheet block or a graph metafile or both to the Word Processor module.

Select from the following options.


 Document. The Document option sends a worksheet block. Any special fonts entered into the block will accompany the worksheet to the Word Processor.


 Graphics. The Graphics option sends a graph metafile to the Word Processor. The graph metafile must have been created by executing the Graph Generate Metafile command.


 Both. The Both option allows you to send both a worksheet block and graph metafile to the Word Processor module.


Tools Preferences

The Tools command keyword provides various file manipulation capabilities. Only the Tools Preferences Spreadsheet options are discussed in this section. Refer to Software System Manual for information regarding the other Tools commands.


Tools Preferences

The Tools Preferences commands are used to configure default settings. For information on the Global and Hardware options, refer to Software System Manual.


Tools Preferences Spreadsheet

The Tools Preferences Spreadsheet command invokes the Spreadsheet Preferences Menu.

Recalculation. The Recalculation option controls whether recalculation of your worksheet is done automatically each time there is a change, or only when F5 is pressed.

Data Path. The Data Path option allows you to define the default path to your worksheets each time you execute the Spreadsheet module.

Project File to Run on Entry. Project File to Run on Entry allows you to execute a project automatically each time you enter SmartWare Spreadsheet. Enter the complete filename, including path, of the project to be executed.

Automatic Load of Macro File. The Automatic Load of Macro File option instructs SmartWare to load a Spreadsheet macro file each time you access SmartWare Spreadsheet. Enter the name of the macro file, including device and path, if necessary, to be loaded.

Automatic Load of Worksheet. The Automatic Load of Worksheet option instructs SmartWare to load a particular worksheet each time you access the Spreadsheet module. Enter the name of the worksheet to be loaded. Include device and path, if necessary.

Encryption Driver. The Encryption Driver to Use on New Files setting determines whether SmartWare's standard encryption driver or an alternate encryption driver will be used to encrypt files.
IMPORTANT: Changing the encryption driver could cause worksheet files to become corrupted and unusable. Do not change the setting unless you are thoroughly familiar with the encryption process.

Map Mode Characters. The Map Mode Characters setting controls the characters to be used to indicate various types of cells on a map of your worksheet.

Default settings for map mode characters are as follows:
** Formula character: "."
** Left-justified: l
** Right-justified: r
** Centered: c
** Values formatted as General: G
** Fixed decimal values: F
** Scientific notation values: S
** Currency values: C
** Percentage values: P
** Date: D
** Time: T
** Histogram: +
** Preformatted blank cells: b

Text and value cells show formatting information only. Formula cells are depicted with the formula code and a format code. The codes, which can be redefined to suit your needs, are used by the Layout Format Formula-Display Map and Print Map commands.

Definition Menus


SmartWare Word Processor Command Reference

This section of on-line help explains the purpose and format of each SmartWare Word Processor command. Menu keywords are presented in this section in the same order in which they appear on the Word Processor Module Menu.

Four of the keywords, Tools, Help, Remember, and Quit, are applicable to all SmartWare modules. Discussions of these keywords are general, with details being limited to Word Processor usage. For more information on the use of these commands, refer to Software System Manual and Project Processing.

If you have not used a word processing program before, we suggest that you read the Word Processor Manual, and that you also use the Word Processor Tutorial. If you are familiar with word processing programs, the sections that follow provide brief descriptions of SmartWare Word Processor concepts and techniques.


Operating Modes

SmartWare Word Processor uses two operating modes, Text Entry Mode and Command Mode. You can toggle between these two modes by pressing Escape. Text Entry Mode is used to type text into a document Command Mode is used to execute commands.


Text Entry Mode

The Word Processor is in Text Entry Mode when you enter the module. Every character you type is interpreted as part of your text. The cursor appears on the screen and moves as you type, indicating the current character position.


Command Mode

To access Command Mode from Text Entry Mode, press Escape. You can also use Quick Key Alt-Z. The Word Processor Module Menu is displayed in the Control Area of the screen.


Marking Techniques

Whenever you select a command that affects existing text, a marking menu appears in the Control Area of the screen and prompts you to specify the amount of text to be affected by the command. Standard text area commands utilize different marking types and menus than defined multiple column area (MCA) commands.


Standard Text Marking

Block, column, and line-marking are available when you are working in a standard text area. Some commands allow you to switch between block and column-marking, using the marking menu key F4, while other commands allow only one type of marking.

When a command is selected that invokes marking, the current cursor position becomes the "anchor" position. As you use marking menu keys or cursor keys to indicate the text you want affected by the command, the text becomes highlighted from the anchor position to wherever you move the cursor. You can set a new anchor anywhere in the text by moving the cursor to the desired location and pressing F2. Or, you can erase any highlighting and restart the marking process by pressing F3.


Block-Marking vs. Column-Marking

For commands that can operate in either block or column-marking, the "default" is block-marking. When the command is selected, SmartWare enters block-marking; to use column-marking, you must press F4.

A block of text can be based on a character, a word, a line, a sentence, a paragraph, a page, a combination of these, or an entire document. A column of text is based on a single character.

Block-marking works on a horizontal aspect while column-marking works on a vertical aspect in a document. When the cursor is moved down one vertical position in block-marking, all horizontal positions between the original cursor position and the current cursor position are included in the marked block. In column-marking, when the cursor is moved down one vertical position, only the original cursor position and the current cursor position are included in the marked column. Columns can be extended horizontally only by using horizontally-oriented cursor keys (i.e., Left-Arrow or Right-Arrow) or Quick Keys (i.e., CTRL-F, CTRL-G, or CTRL-F5).

Block-marking can be used to include an MCA in a block of marked text. For example, if you mark a block of standard text above and below the MCA, the entire MCA is included in the marked block. Column-marking does not allow you to cross MCA "boundaries."


 The marking menu keys F5, F6, F7, F8, F9, P and R are used in block-marking to highlight specified areas of text. If you have switched to column-marking and subsequently press one of these marking keys, block-marking is automatically activated and the corresponding text is highlighted. The characters encompassed by these menu keys are defined below.

F5 Word. Highlights the current word and any blank spaces following the it.

F6 Sentence. Highlights the current sentence, including punctuation, and any blank spaces following it.

F7 Paragraph. Highlights the current paragraph and the end of paragraph mark.

F8 Document. Highlights the current document from the beginning of the document to the end of file mark.

F9 Line. Highlights the current line, from left margin to right margin.

P Page. Highlights the current page from one page break to the next.

R Remainder. Highlights the remainder of the document, from the current anchor position to the end of file mark.


Line-Marking

Line-marking is used when Document Dictionary Hyphenate or Layout Keep is selected. The current line is automatically marked and a marking menu is displayed in the Control Area of the screen.

As with the other marking types, you can press F2 to set a new marking anchor, or F3 to restart the marking process. Press F10 when marking is completed.


MCA Marking

The type of marking allowed in an MCA depends upon whether it is a linked or unlinked MCA. Column-marking and entry-marking, are available in a linked MCA. Only column-marking is available in an unlinked MCA.


Linked MCA Marking

When you select Document Columns Edit Move or Document Columns Edit Delete, Angoss enters MCA entry-marking, highlights the current entry, and displays a marking menu in the Control Area of the screen.

By pressing F4, you can change to column-marking.

Entry-marking works on a horizontal aspect and highlights all the text contained in an entry. An entry consists of a group of related text that is entered in one or more linked columns.

Column-marking works on a vertical aspect and highlights all the text contained in a column. To extend column-marking across multiple columns, press left or right, whichever is applicable.

When Document Columns Edit Move or Document Columns Edit Delete is selected and entry-marking is invoked, the current entry becomes the "anchor" entry. As you use up or down to extend the marking to multiple entries, the text is highlighted in all the entries from the anchor entry to the current entry. You can designate a new anchor by moving the cursor to the desired entry and pressing F2. Or, you can erase any highlighted entries and restart the marking process by pressing F3.

When column-marking is selected (by pressing F4), the current column becomes the "anchor" column. As you use left or right to extend marking across multiple columns, all columns from the anchor column to the current column are highlighted. You can set a new anchor by moving the cursor to the desired column and pressing F2. Or, you can erase any highlighted columns and restart the marking process by pressing F3.


Document Commands

The Document keyword is the basis for the command formats that enable you to:

* establish multiple column areas (MCAs)
* access on-line spellchecker and thesaurus
* move between windows, documents, or to new locations in
the current document
* create footnotes, indexes, or a tables of contents
* send files to other SmartWare modules
* control the display of hidden text, special marks, and
rulers
* protect documents from permanent modifications


Document Options

Document provides the following options:

Columns. Defines and edits multiple column areas (MCAs).
Dictionary. Hyphenates, spellchecks, and provides access to the thesaurus.
Find. Locates a specified character string in a document.
Goto. Moves the cursor between windows or documents, or to a new position within the same document.
Math. Calculates a formula or totals a series of numbers.
References. Provides character markers, paragraph numbering, and the creation of footnotes, an index, or a table of contents.
Send. Provides file integration with other SmartWare modules.
Visible. Toggles on or off the display of hidden text, marks, rulers, or tabs.
Lock. Protects a document from permanent modification.
Unlock. Removes permanent modification protection from a document.


Document Columns

Document Columns is used to define, edit, or remove multiple column areas (MCAs), sometimes called tables. Each column can be of variable or equal width, with column text being linked or unlinked.
Sorting columnar text
MCA, sorting text


Document Columns Define

Document Columns Define creates an MCA in which you can specify the size and position of each column. When you select Document Columns Define, you must specify whether you want the columns to be linked or unlinked.


 Linked. Linked columns retain the horizontal alignment and relationship of text that is entered in an MCA. Each related group of text entered into a linked MCA is referred to as a column "entry." No matter how many lines each entry in the second column runs, it stays horizontally aligned with the appropriate entry in column one.


 Unlinked. Text contained in one column of an unlinked MCA is horizontally aligned independently of the text in any other column.


Defining Columns

After specifying whether the MCA will be linked or unlinked, a definition ruler is displayed at the current cursor position. The following steps explain the definition process.

Step 1: Enter the starting position (left margin) for the first column.

Use the cursor keys to move the cursor to where you want the left margin and press ENTER, or type the left margin position (in inches) and press ENTER.

Step 2: Enter the ending position (right margin) for the first column in the same manner.

Before specifying the right margin, you can restart the definition of the current column by pressing F2. The starting position for the column is negated and once again you are prompted to enter the starting position.

Step 3: Enter right and left margins for all other columns in the MCA.

The column boundaries are displayed on the definition ruler as you enter the margin values.

Step 4: When you have defined the boundaries for all the columns you want, press F10.

The column definition ruler disappears and paragraph marks are inserted at the starting position of each defined column (if paragraph marks are toggled visible.) Column margins are displayed on the Main Ruler (if it is toggled visible.)


Document Columns Quick-Define

Document Columns Quick-Define creates columns of equal width quickly and easily. The following steps explain the process.

Step 1: Select Document Columns Quick-Define.

Step 2: Specify whether you want linked or unlinked columns.

Step 3: Enter the number of columns you want in the MCA.

SmartWare displays a definition ruler with the left and right margins set for each column.

If you do not like the columns as they appear on the definition ruler, press N. The command will terminate, and you can start over. If you do like the columns as they appear on the definition ruler, press Y. The definition ruler disappears and paragraph symbols appear at each column position (if paragraph marks are toggled visible.)
Comment: The Current Document Options Definition Menu is obtained by selecting the Layout Document-Options Current-Document command.

SmartWare automatically determines the right and left margin settings for each column based on the number of columns you specify, and the left and right margin settings of the current ruler. In addition, the minimum "gutter" space between columns (specified in the Current Document Options Definition Menu) is used to compute the size of each column. The current page margins are divided by the number of columns you selected, taking gutter space between columns into consideration.

If you specify more columns than will fit within the current margins, a message is displayed indicating that fact. You can either extend the current page margins to accommodate the number of columns you want, reduce the "gutter" space between columns, or specify fewer columns.


Entering Text in Columns

After you have defined an MCA you can use the keys in Table 9-1 to move around or to enter text in it.

Table 9-1
NOTE: Text in an MCA can be sorted with the Edit Sort Columns command. For more information, see the discussion of Edit Sort in this chapter.
Ctrl-F3 | Move to the previous column.
Ctrl-F4 | Move to the next column.
Ctrl-E | Start a new column entry in a linked MCA.


Document Columns Remove

Document Columns Remove is used to delete an entire MCA. Position the cursor in the MCA you wish to delete and execute the command. Document Columns Remove deletes the entire MCA. To delete only specific columns or entries in an MCA, use Document Columns Edit.
IMPORTANT: Text contained in the MCA is permanently deleted when Document Columns Remove is executed.

MCA, deleting columns/entries


Document Columns Edit

Document Columns Edit allows you to add, move, or delete columns or column entries in an MCA. In addition, Document Columns Edit allows you resize the margins of one or more defined column(s).


Document Columns Edit Add

Document Columns Edit Add is used to add one or more columns, or a single column entry to an MCA. When you select Document Columns Edit Add, you must specify whether you want to add a column to the MCA, or add an entry in the existing columns. Remember, a column entry consists of text that is horizontally aligned (linked) in each column of an MCA. The following steps explain the process.

Step 1: Select Document Columns Edit Add.

Step 2: Specify whether you want to add a column or an entry.


 Column. If you specify that you want to add a column, the column definition ruler is displayed above the MCA and the column editing menu shown appears in the Control Area of the screen.

Position the cursor on the ruler where you want to insert a new column. You can move the existing columns to make room for the new column. Press F5 to shift columns right of the cursor to the left; press F6 to shift columns right of the cursor to the right. To add a column, press F7. SmartWare then prompts you to enter the starting and ending positions for the new column.


 Entry. Document Columns Edit Add Entry is only available when you are working in a linked column area. When the command is selected, space for a new entry is inserted directly below the current entry.


Document Columns Edit Boundaries

Document Edit Columns Boundaries

This allows you to modify the margins or position of any column in an MCA. When the command is selected, the definition ruler for the current MCA is displayed above the columns and the cursor is placed on the ruler, allowing you to modify the margins. Move the cursor to the column you want to move or resize. Then press one of the keys in Table 9-2.

Table 9-2
F3 | Allows adjustment of the column's left margin. After pressing F3, use the cursor keys to move the left margin to the new position.
F4 | Allows adjustment of the column's right margin. After pressing F4, use the cursor keys to move the right margin to the new position.
F5 | Shifts all columns to the right of the cursor one position to the left each time you press F5.
F6 | Shifts all columns to the right of the cursor one position to the right each time you press F6.

When you have completed resizing and repositioning columns, press F10.


Document Columns Edit Delete

Document Edit Columns Delete

Columns or column entries can be removed from an MCA by selecting Document Columns Edit Delete. Any text contained in a deleted column or column entry is lost when the command is executed.


 To delete an entry:

Step 1: Select Document Columns Edit Delete.

An entry-marking menu appears and the current entry is highlighted. Use cursor keys to highlight the entry or range of entries you wish to delete. Press F2 to drop a new anchor and restart the marking process.

Step 2: When the proper entry or entries are highlighted, press F10.

The highlighted entries are deleted, and the MCA reforms.

To delete a column:

Step 1: Select Document Column Edit Delete.

Step 2: When the marking menu appears, press F4 to enter column-marking mode.

Step 3: Highlight the column or range of columns you wish to delete. Press F10.

The highlighted columns are deleted and the MCA reforms.

Linked MCA Marking
MCA deleting


Document Columns Edit Move

Document Columns Edit Move enables you to move either columns or entries from one location to another within an MCA. Only columns can be moved in an unlinked MCA. Columns or entries can be moved in a linked MCA. To move a column entry:


 Step 1: Select Document Columns Edit Move.

An entry-marking menu appears and the current entry is highlighted. Use cursor keys to highlight the entry or entries you wish to move. Press F2 if you need to drop a new anchor and restart the marking process.

Step 2: When the proper entry or range of entries is highlighted, press F10.

Step 3: Specify a new location for this entry.

Move the highlighter to the position you want the entry to occupy, or type in the position number. Then press Enter. For example, if you want the entry to be the third entry in the MCA, type in the number 3. The MCA will rearrange accordingly.

To move a column:

Step 1: Select Document Column Edit Move.

Step 2: If you are in a linked MCA, press F4 to enter column-marking mode.

If you are in an unlinked MCA, only column-marking is available.

Step 3: Highlight the column or range of columns you wish to move. Press F10.

Step 4: Specify a new location for the column or columns.

Move the highlighter to the position you want the entry to occupy, or type in the column number. Then press Enter. For example, if you want the moved column or columns to start at the third column in the MCA, type in the number 3. The MCA will rearrange accordingly.


Document Dictionary Hyphenate

Use the following steps to add hyphenation to an existing document without changing the margins, indention, or line spacing.

Step 1: Select Document Dictionary Hyphenate.

Step 2: Mark the line or range of lines you want to hyphenate.

A line marking menu appears at the bottom of the screen, but you can enter block-marking by pressing any of the normal block-marking keys.

Step 3: Press F10 or ENTER.

Only text in the marked area is hyphenated and the document is reformed as necessary.

Line-Marking


Document Dictionary

Document Dictionary is used to add hyphenation to an existing document, to check a document for spelling errors, and to obtain synonyms and antonyms for specified words via an on-line thesaurus. When you select Document Dictionary, you must specify whether you want to erase a dictionary file, hyphenate the current document, check for spelling errors in the current document, or access the thesaurus.


Custom Dictionaries

You can create your own dictionaries, called custom dictionaries. Jargon, product names, or other words that are unique to your industry or application can be put in a custom dictionary. In this way, they are not always interpreted as potential errors. You can add a word to a custom dictionary by pressing F5 when the word is highlighted during a spell check. You are then prompted to enter the name of a dictionary to place it in. If you enter a dictionary name SmartWare does not recognize, it will ask if you wish to create the dictionary. Custom dictionaries are assigned the extension .udc.

As you create new custom dictionaries, the names are automatically added to the list custom dictionaries on the Document-Options menus. These menus are accessed with Layout Document-Options Current-Document or Layout Document-Options New-Documents. The custom dictionaries listed on the Current Document Options menu will be used to spell check the current document. Custom dictionaries listed on the New Document Options menu will be defaults available to all newly created documents.

To remove a custom dictionary from either list, place the pointer in front of the dictionary you wish to delete, and press F3. To add a dictionary to the list, type in the dictionary name. A maximum of five custom dictionaries can be attached to each document.


Document Dictionary Erase

You can erase a custom dictionary file with the follow steps.

Step 1: Select Document Dictionary Erase.

Step 2: Enter or select the name of the dictionary file you want to delete.

When the command is executed, the file structure and all of the words contained in the dictionary are permanently erased.


Document Dictionary Spellcheck

Document Dictionary Spellcheck is used to check your current document for spelling errors. You can use the spell checker by selecting Document Dictionary Spellcheck. An entire document, or any portion of it, can be checked for spelling errors. During the check, each word in the document is compared with the words in the dictionary and potential errors are flagged.

When you select Document Dictionary Spellcheck, you must specify whether you want the results of the spell check to be written to a file or to the screen. A check written to a file proceeds quickly and without interruption; a check to the screen allows you to interact with SmartWare during the checking process.


Document Dictionary Spellcheck File

The following steps provide a quick, unattended spell check on a document.


 Step 1: Select Document Dictionary Spellcheck File.

Step 2: Highlight the portion of the document you wish to spell check.

Use of the menu marking keys makes this job easier (i.e. press F8 to highlight the entire document.) Then press F10.

Step 3: Enter a name for the file that will contain the spell check results.

No file extension is attached to this file. To place the results in a file in the current directory, just enter the filename. To place this file in another directory, enter the entire path specification. Press ENTER to execute the command and begin the spelling check.

SmartWare rapidly surveys the portion of the text you marked and writes the results to the file. You can display the results of the spelling check by selecting File Load and entering the filename you assigned to the file.

Each line of the file lists the section, page, line, column number, and misspelled or unrecognized word, enabling you to quickly locate the errors in the text of your document. At the end of the file, a Spell Check Summary lists the number of words checked and the number of misspellings encountered.


Document Dictionary Spellcheck Screen

The following steps provide an interactive spelling check.

Step 1: Select Document Dictionary Spellcheck Screen.

Step 2: Highlight the portion of the document you wish to spell check.

Use of the menu marking keys makes this job easier (i.e. press F8 to highlight the entire document.) Then press F10.

Step 3: The spell check begins. You can abandon the spell check at any time by pressing Esc.

When a potential error is encountered, the checking process is temporarily halted. The suspect word is highlighted and the reason for the check is displayed in the Control Area. Reasons a word might be suspect include the double occurrence of a word or the occurrence of a word that is not contained in the dictionary being used.

A prompter listing suggested spellings for the highlighted word appears on the screen. You can replace the highlighted word with one of the words in the prompter by moving the pointer to the word and pressing ENTER. If no alternative words are available, SmartWare displays the message Word misspelled. No suggested spellings.
NOTE: If no prompter of suggested spellings appears, you can enable this feature by executing Tools Preferences Wordprocessor and specifying Yes at the Correction Information: item. If you do not wish to enable this feature, you can still obtain spelling alternatives by pressing F8 each time a misspelled word is encountered.

Table 9-3 lists the keys that are available to you during an interactive spell check.

Table 9-3
IMPORTANT: If you use F2 to replace all occurrences of the misspelled word, the replacements are done as they are encountered. If the spelling check is aborted, any occurrences not yet encountered are not corrected.
F2 | Replaces all occurrences of the currently highlighted word. If you type in a replacement it will be used, if not, the word the arrow in the prompter is pointing to will be used as the replacement.
F3 | Ignores this occurrence of the word.
F4 | Ignores all occurrences of the word throughout the document.
F5 | Adds the word to a custom dictionary.
F6 | Deletes the word from the document.
F7 | Places a copy of the word in the Control Area and allows you to edit it. Press Enter and the edited word is placed in the document.


The Ignore All Buffer

Every time you press F4 to tell SmartWare to ignore all future occurrences of a word, that word is placed in a buffer. The buffer is retained even after spell checking is completed. The buffer is automatically cleared only when you exit the Word Processor, or spell check a different document. If you spell check a long document repeatedly, without leaving the Word Processor or spell checking another document, the total length of all words marked "ignore all" can fill up the buffer.

An error message will be generated if you try to enter another word in a full buffer. Between spell check sessions, you can clear this buffer by pressing ALT-F9. You will be prompted Erase ignore buffer?(y/n). Press Y to clear the buffer.
NOTE: Any words you mark as "replace all" are also placed in a buffer, but that buffer is cleared after each spell check session.


Spell Check Summary

As the spell check proceeds, SmartWare monitors its progress on the bottom line of the screen. The number of words examined and the number of corrections that have been made to the document are shown. When the spelling check is completed, a Spell Check Summary is displayed.


Quick Keys

The following Quick Keys allow you to quickly perform interactive spell checks on specific parts of your document.

Table 9-4
Alt-F2 | Executed Document Dictionary command. You must then specify whether you want to delete a custom dictionary file, hyphenate a document, spell check a document, or use the thesaurus.
Alt-F3 | Spell checks the current word.
Alt-F5 | Spell checks the remainder of the document, from the cursor to the end of the file.
Alt-F6 | Spell checks the entire document from beginning to end.


Document Dictionary Thesaurus

The thesaurus is used to obtain alternative words or phrases for existing words in your document. The following steps explain how to use the thesaurus.

Step 1: Select Document Dictionary Thesaurus.

Step 2: Move the cursor to the word you want to look up. Press Enter.

The thesaurus is based on root words. If you select a word that is a derivative of another word, SmartWare displays a prompter list of possible root words.

Step 3: If the root word prompter appears, move the pointer to the root word that is most appropriate for the word you are researching and press Enter.

After choosing a root word, or if the word is not a derivative of another word, a list of possible meanings for the word you are researching appears.

From this "meanings" list, you can find synonyms, antonyms and additional meanings for the word you have marked. Table 9-5 lists quick keys that initiate actions from the "meanings" menu. Move the pointer to the meaning you are interested in researching before pressing the quick keys.

Table 9-5
Enter | Moves the word at the pointer to the command line and allows you to edit it. This is helpful if the word needs minor changes, such as changing it from singular to plural. After editing the word, press Enter again and the word is placed in your document.
F2 | Displays a list of synonyms for the word at the pointer. Once any other list is displayed, you can press F2 to return to the meanings list.
F3 | Replaces the word in your document with the word at the pointer.
F4 | Displays an additional meanings list for the word at the pointer.
F5 | Displays a list of antonyms for the word at the pointer.
F6 | Returns to the original "meanings" screen. This is particularly helpful since you can go several levels deep, exploring meanings, synonyms or antonyms of various words.


Document Find

To locate a specific series of characters:

Step 1: Select Document Find.

Step 2: Enter the text string you wish to find.

You can enter up to 50 characters. A question mark (?) will match any character. For example, "move?" would match "mover," "moves," and "moved." SmartWare automatically inserts double quotation marks (") around the search string. If you want to search for a string that has a leading or trailing space, include the space when you type the search string.

Step 3: Enter search options to control how your document is searched for the specified string.

Up to ten options can be entered. A list of available options is displayed.


 The following table explains each search option:

Table 9-6
Option | Action
F | Search forward from the current cursor position to the end of the file.
B | Search backward from the current cursor position to the beginning of the file
I | Ignore the case of the character string during the search.
W | Search for whole words only.
M | Search an area of the document you mark.
G | Search from the beginning of the file, regardless of cursor position.

These options can be combined to specify the scope of a search. You can also enter a number after the search option character(s) to instruct SmartWare to find a specific occurrence of the character string.

For example, FI9 instructs SmartWare to search forward from the cursor for the ninth occurrence of the string, ignoring its case. When the ninth occurrence is located, the cursor is positioned at the beginning of the string and the search stops.

If the string is not found, the message Text "xxx" not found. is displayed.

The text string you are searching for and the search options are stored in buffers, becoming "default" values for subsequent uses of Document Find. To accept a displayed default value, press ENTER in response to the prompt. To change the value, enter the desired text or option.

Repeating a Search

Executing Document Find will take you to only one occurrence of the search string. To go on to the next occurrence, press F9 to repeat the last command. If you have executed another command since Document Find, use ALT-R to repeat the last search. When you press ALT-R, SmartWare repeats either the last Document Find or the last Edit Replace command, whichever command was executed more recently.


Finding or Replacing Special Characters

You can also search documents for special characters such as tab characters or paragraph marks. At the prompt Enter search text:, enter %T to find Tab marks or %P to find paragraph marks. Since the percent sign has special meaning in search commands, you must enter two percent signs (%%) if you ever want to search for a percent sign.


Document Goto

Document Goto allows you to move your cursor to a new location, either within the same document or in a different, active document. If the cursor moves to a different window, that window becomes the current window. Likewise, if the cursor moves to a different document, that document becomes the current document. When you select Document Goto, you must specify whether you want to move to a different window, to a different document, to a marker, or to a location.


Document Goto Window

The following steps explain how to move to a different window. In order to move to a different window, you must have split the document window into one or more windows.

Step 1: Select Document Goto Window.

Step 2: Enter the number of the window you want to move to and press ENTER.

The window you specify becomes the current window. When the document border is toggled on in multiple windows, the current window (the window containing the cursor), displays a double-line border while all other windows display a single-line border.

Splitting windows
Multiple windows, creating
Document Window, splitting


Document Goto Document

The following steps explain how to move to a different document when multiple documents are active.

Step 1: Select Document Goto Document.

A prompter list of active files appears.

Step 2: Enter or select the name of the active document you want to move to and press ENTER.

The document you move to becomes the current document. Only documents that are currently in background memory can be accessed using Document Goto Document. The document must have been loaded, using File Load, at some point during the current word processing session. If a document has been unloaded, it is no longer active.

Loading files
Unloading files
Saving files
Active files


Document Goto Marker

The following steps explain how to move to a marker in the document.

Step 1: Select Document Goto Marker.

A prompter listing the markers in the current document are displayed.

Step 2: Type the desired marker name, or select it from the prompter.

The cursor then moves to the character location in the document where the marker is located.


Document Goto Location

When you select Document Goto Location, SmartWare prompts Enter a new cursor location:, allowing you to move the cursor to a new document, section, page, line, or column.
NOTE: Only documents that are currently in background memory can be accessed using Document Goto Location. The document must have been loaded, using the File Load command, at some point during the current session. If a document has been unloaded it is no longer active.
Loading files
Unloading files
Saving files
Active files

Document. To move the cursor to a different document, enter the name of the active document and press ENTER.

Section. To move the cursor to a different section, enter s, the number of the section you want to move to, and press ENTER. For example entering s2 takes you to section 2 of the document.

Page. To move the cursor to a different page, enter p, the number of the page you want to move to, and press ENTER. For example, entering p23 takes you to page 23.

Line. To move the cursor to a different line, enter l, the number of the line you want to move to, and press ENTER. For example, entering l19 takes you to line 19 of the current page.

Column. To move the cursor to a different column (character position) in your document, enter c, the number of the column you want to move to, and press ENTER. For example, entering c29 takes you to the 29th column on the current line in the document. If the current text line is shorter than the column number you specify, the cursor will be moved to the end of the line.

Combination Specification. A combination specification can also be entered to move the cursor to a new location. Document, section, page, line, and column delimiters can be strung together, enabling you to specify the exact location to move to in a particular document.

There are two methods available for entering a combination specification. You can separate the entities of the specification using periods, or you can enter the identifying characters described above. For example, to move to section 3, page 5, line 20, column 5 in your current document, you can enter s3.5.20.5 or s3p5l20c5 in response to the Enter a new cursor location: prompt. To move to section 1, page 2, line 10, column 15 in the active document "adoc," you can enter adoc.s1.2.10.15, adoc.1.2.10.15, or adoc.s1p2l10c15.

No designation is required if you are retaining the current "value" for an entity when entering a combination specification. For example, to move to a different page in the current section of the current document, you do not need to enter a document or section specifier. If the cursor is currently on line 1, column 1 on page 10 in section 2 of a document named "letter", enter p3l10c25 or p3.10.25 in response to move to line 10, column 25 on page 3 in the same section of the "letter" document.

Likewise, you do not need to specify a designation if you want the value of an entity to be "1." For example, if you want to move to line 1, column 1 of a particular page, you do not need to enter a line or column specifier. If the cursor is currently on page 10 in section 2 of a document named "letter", enter s1p3 or s1.3 to move to line 1, column 1 on page 3 in section 1 of the same document.

When page numbering is continuous across section breaks, you can move to a page in a different section of your document without specifying the section number.

Marker specifications can also be combined with document specifications using the Document Goto Location command. For example, entering test.intro in response to the Enter a new cursor location: prompt moves your cursor to the marker "intro" in the active document "test."


Document Math

Document Math is used to calculate a formula or total a series of numbers in a document.


Document Math Formula

Document Math Formula allows you to obtain the result of a formula contained in your document. A formula may contain numbers, parentheses, the operators "+," "-," "*," and "/", and SmartWare functions. (Refer to Formula Reference Manual for additional information on SmartWare formulas and functions.) The formula must reside on one line. Termination of the formula is indicated by either an equal sign (=) or the end of the line on which the formula resides.

Select Document Math Formula. Move the cursor to the starting character of the formula and press ENTER.

The result of the formula is stored in memory until another Document Math command is executed, or until you exit SmartWare Word Processor. The result of the formula can be inserted at the cursor position in any active document, by pressing CTRL-C when in Text Entry Mode.


Document Math Sum

Document Math Sum allows you to calculate totals of columnar or linear numbers.

Step 1: Select Document Math Sum.

Step 2: Mark the numbers you want to total and press F10 or ENTER.

The sum of the numbers is stored in memory until another Document Math command is executed or until you exit SmartWare Word Processor. The result can be inserted at the cursor position within any active document, by pressing CTRL-C when in Text Entry Mode.

Marking Techniques


Document References

When you select Document References, you must specify whether you want to access the footnote, index, marker, paragraph-numbering, or table of contents feature.


References Footnote

The placement and numbering scheme of footnotes for each document is determined by settings on the Current Document Options Definition Menu. This menu is accessed with the Layout Document-Options Current-Document command. Footnotes can be continuously numbered throughout the document or numbering can be restarted at page or section boundaries. In addition, footnotes can be placed at the end of each page, at the end of each section, or at the end of the document.

Footnote numbering is automatically maintained by SmartWare, based on the numbering scheme and placement option selected. If footnotes will be numbered consecutively throughout the document, or placed at the end of the document, a new footnote inserted in the middle of a document causes all following footnotes to be renumbered. However, if you have chosen to restart the footnote numbering at each page or section, only footnotes subsequent to the new entry and prior to the page or section break are renumbered.

The font used for the footnote reference numbers inserted into a document is specified on the Document-Options menu. This menu is accessed by Layout Document-Options Current-Document or Layout Document-Options New-Documents. By default, the font for this purpose is font #1. It comes predefined as a standard 10 point superscript font. If you edit font #1 or whichever font you specify for this purpose, your footnote references may appear different than you expect.


References Footnote Insert

The following steps explain how to create a footnote.

Step 1: Insert.

SmartWare displays a footnote input screen containing ten blank lines. The cursor is placed in column 1 of the first footnote line. The message Insert text for footnote. Press F10 when finished. is displayed in the Control Area.

Step 2: Type in the footnote text.

A maximum of 255 characters of footnote text can be entered on each line. If you attempt to print a document with footnote lines that contain more characters than your printer can handle, or if your footnote lines extend beyond the right boundary of your document, the printed footnote text is truncated.

Word wrap is not available when entering footnote text. The text does not move to the next line when you reach the end of the current line. You must press ENTER to move the cursor to the beginning of the next footnote line.

Step 3: After you have typed all the footnote text desired, press F10.

The footnote text is then stored, the footnote input screen disappears, and the appropriate footnote number is inserted at the current cursor position in the document. The footnote text is stored with the current document the next time the document is saved.


Changing Fonts

Footnote text can be printed in various fonts by entering a font specification code as part of your footnote text. A code sequence controls the footnote text immediately succeeding it, either until the end of the footnote, or until a new control sequence is encountered. The format for inserting font control codes is %[#BU]. The # represents any valid font number. An uppercase B turns boldfacing on, and a lowercase b turns it off. An uppercase U turns underscoring on, and a lowercase u turns it off.


Copying and Moving Footnotes

If you copy a block of text that contains a footnote reference number, the reference is preserved in the copied text and the duplicated text is assigned another footnote number. The number assigned to the duplicated text depends upon where in the document the text was copied and the footnote numbering sequence specified on the Current Document Options Menu. If the duplicated text is placed in front of the original footnote reference, the original footnote number is also changed.

If you move a block of text containing a footnote reference number, the reference is preserved with the relocated text. The footnote is renumbered depending upon where in the document the text was moved.


References Footnote Modify

The following steps describe the process for editing footnote text.

Step 1: Within the document, position the cursor on the reference number of the footnote you want to modify.

Step 2: Select the Footnote Modify command.

The footnote input screen for the corresponding footnote reference number is then displayed. If the cursor is not positioned on a footnote number before you select the command, SmartWare searches for the footnote from the current cursor position to the bottom of the Document Window. If no footnote reference number is displayed in this area, an error message is generated.

Step 3: Modify the footnote text.

Step 4: After the desired changes have been made, select F10.


Deleting Footnotes

Several methods can be used to remove a footnote number from a document and delete the footnote text associated with the footnote number. You can delete the footnote reference number displayed in the text. Or, you can remove a footnote by modifying it and deleting all the text contained in the footnote itself.


References Index

The Document References Index command provides a method for marking text as index items, typing index entries for the index items, and automatically generating an index.

The format, style, and appearance of a generated index is determined by the settings on the Current Document Options menu. This menu is accessed by selecting Layout Document-Options Current-Document. Index margins, the style and placement of alphabetic headings and page numbers, the inclusion of section numbers with the page numbers, and the style and format of primary and subordinate entries are all dependent upon the settings on this definition menu.

Index marks, displaying


Index Add

Index Add is used to designate a portion of text in a document to be referenced by an index entry. The wording of each index entry can be taken exactly from the marked document text. In many cases however, you will wish to type in a unique word or phrase for the index entry instead of using the document text. The following steps explain the procedure.

Step 1: Position the cursor in or near the text you want referenced by an index entry.

Step 2: Select the Index Add command.

Step 3: Highlight the text you want referenced by the index entry.

The prompt Enter Index Entries: is displayed.

Step 4: Determine what the actual index entry will be.

Press Enter if you want the index entry to be taken from the marked document text. If you prefer a different word or phrase to be the index entry, type it in at the prompt. The following characters are important in index entries, whether you use document text or your own entries.

Table 9-7

: | The colon is used to separate primary and subordinate index entries.
/ | The slash will separate multiple listings for the same marked text.

The following discussion explains the use of these characters more completely.


Subordinate entries

Index entries can be referenced as primary or subordinate entries. If you press Enter to accept marked text as your index entry, or type in a unique phrase, the index entry will be a primary one. To create a subordinate index entry, you must separate primary and subordinate phrases with a colon (:).

For example, if you mark the phrase "custom dictionary" in a document and you want it to appear in the index as a subordinate entry under the primary entry creating, you must enter creating: in response to the prompt.

If you want to type in your own index entry, you must type in primary and secondary entries separated by a colon. For example, creating:custom dictionary.


Multiple references

Marked text can also be referenced by multiple index entries by separating each reference with a slash (/). For example, if "custom dictionary" was marked in the document you might want it to be referenced under the primary headings creating, editing and spellchecker. To accomplish this, type in creating:/editing:/spellchecker: at the Enter Index Entries: prompt.

Again, if you type in your own entry you can still specify multiple listings. Again, let's assume "custom dictionary" is marked. You could enter creating:custom dictionaries/editing:custom dictionaries/spellchecker:custom dictionaries as an index entry, or custom dictionaries/creating:/editing:/spellchecker: to obtain multiple index entries.

If a slash is entered as either the first or last character in a multiple entry, the marked text is automatically referenced as a primary entry. Thus, if "custom dictionary" is highlighted and you enter either /creating:/editing:/spellchecker: or creating:/editing:/spellchecker:/ in response to the prompt, in addition to the three subordinate entries for "custom dictionary," you would also get a primary entry for "custom dictionary,".
NOTE: If you want to enter an index entry that contains a colon (:), you must enter double colons (). Otherwise, SmartWare interprets a single colon as an instruction to create a subordinate entry.

SmartWare surrounds a designated index item with the index marks. The display of these marks in your document can be toggled on or off using Document Visible Marks Index.


Index Edit

Existing index entries can be edited by using the Index Edit command. To edit an index entry, position the cursor on the index item in your text that is referenced by the index entry you want to change. Then select Index Edit command. Any index entries that reference the selected index item are then displayed in the control area of the screen.

You can delete an entry by moving the cursor to the entry you want to delete and using Delete or Backspace to erase each character in the entry. New listings can be added by following the standard conventions used when adding an index entry. Modifications can be made to an existing entry by typing over the displayed text, or adding or deleting characters as needed. These modifications will affect the entries in the index next time it is generated.


Copying or Moving

If you copy a block of text containing an index item, the index reference is retained in the original text and also appears in the duplicated block of text. You can then delete one of the index references, if desired. If both references are left intact and the references appear on different pages or sections of your document, two listings will exist for the index item the next time an index is generated. You may wish to edit the index to combine them into one listing.

If a block of text containing an index item is moved, the index reference is moved with the text. The relocation of the index reference will be reflected in the index the next time it is generated.

If you copy or move a block of text that causes text marked as an index item to be split, the index reference is left intact in the original text and does not appear in the duplicated text.


Index Generate

Generate an index based on the index entries you have specified.

The generated index is placed at the end of the current document, separating it from the rest of the document by a section break.

You can edit the index in the same manner as any other part of a document. However, any manual editing done to the index will not be retained if the index is subsequently regenerated. In addition, if you make any changes to existing index entries in a document, these changes will only be reflected in the index if it is regenerated.

If you do regenerate the index, the new one will overwrite the old one unless you have moved it from the end of the document.


Index Remove

Index Remove is used to "unmark" index items in the document and subsequently eliminate all index entries that reference that text. To remove the marks, position the cursor on the text surrounded by the marks and execute the command. Both the marks and the index entries referencing the text are eliminated. You can also delete an index item and its accompanying index entries by using the delete key to delete either of the index marks.


References Marker

Marker is used to assign names to selected characters in your document. This enables you to move directly to a character marker, using the Goto Marker command, without knowing the exact location of the marked character. When you select Marker, you must specify whether you want to add, remove, or view a marker.

Moving to a marker


Marker Add

The following steps explain how to create a marker.

Step 1: Move the cursor to the position in the document where you want to create a marker

Step 2: Select the Marker Add command.

Step 3: Enter a name for this marker. Press Enter.

A marker name must begin with a letter, be a maximum of eight characters, and be unique for the current document. If you enter a marker name that is already in use in the document, the message Marker is already in use. is displayed. Markers are not displayed on the screen and do not appear on printed documents.

If you copy text that contains a marker, the marker is retained in the original text but does not appear in the duplicated text. If you move text that contains a marker, the marker is moved with the text. If you delete the character associated with a marker, the marker is also deleted.


Marker Remove

A marker can be removed by deleting the text associated with it or with the following steps.

Step 1: Select Marker Remove.

A prompter appears displaying all markers in the current document.

Step 2: Enter or select the name of the marker to be deleted.


Marker View

Scrolls through the current document, stopping at each occurrence of a marker. Text is searched from the current cursor position forward until a marker is found. When a marker is found, the cursor is positioned on the character associated with the marker and the name of the marker is displayed in the Control Area. To scroll to the next marker, press ENTER. To abort the process, press ESC. If you press ENTER and no more markers are contained in your document, the message No markers found. is displayed.

Moving to a Marker


References Paragraph-Number

You can assign a numbering sequence to the paragraphs in a document by selecting the Document References Paragraph-Number command. Paragraph numbering is the way outlines and other structured documents are created in SmartWare.


Number Styles

A setting on the Current Document Options Menu determines whether Outline, Legal, German-Legal or Paragraph style is used for numbering in the current document. To change the numbering style, select Layout Document-Options Current-Document. Under the Paragraph Numbering heading, select the numbering style you desire.


Number Position

Also under the Paragraph Numbering heading on the Current Document Options Definition menu are two other settings. You can specify whether you want paragraphs numbered consecutively throughout the document, or numbering to restart at each section boundary. Here you can also specify how the paragraph number is separated from the paragraph text. The text of a paragraph can immediately follow the paragraph number with no space between number and text. Or, the number can be separated from the text of the paragraph by inserting a single space, a tab or by block indention of the entire paragraph of text.


Paragraph-Number Insert

Paragraph numbers are inserted by selecting the Paragraph-Number Insert command or the Quick Key Shift-F8. When the command is selected, you must specify whether you want to use the automatic or fixed method of numbering.

The insertion of a new paragraph number in a document (or section, if paragraph numbering is restarted at section breaks) causes any subsequent, existing paragraph numbers to be automatically renumbered. However, references to other paragraph numbers you typed into a paragraph will not be updated. Only paragraph numbers inserted with Paragraph-Number commands are affected by the renumbering.


The Automatic Method

The level of an automatically inserted number fluctuates depending on the number of indent tabs that precede it. If one or more indent tabs are inserted or deleted to the left of a number, the number's level automatically changes. If text or regular tabs are entered to the left of an automatic paragraph number, it is automatically converted to a "fixed" paragraph number.


The Fixed Method

The level of a fixed paragraph number is stationary, regardless of the number of indent tabs that precedes it. If one or more indent tabs are inserted or deleted to the left of a paragraph number generated by the fixed method, the number's level remains unchanged.


Inserting a Paragraph Number

The following steps assign a number of a particular heading level to a paragraph.

Step 1: Place the cursor in the paragraph to be numbered.

Step 2: Select Paragraph-Number.

Step 3: Specify whether you want to Insert a fixed or automatic paragraph number (see previous discussion).

Step 4: Enter a heading level from 1 to 15.

The appropriate heading level is placed in front of the paragraph in the style and format specified on the Current Document Options menu.

The heading level of a particular automatically-numbered paragraph can be quickly renumbered by changing the number of indent tabs in front of it. To change a number to a higher number, place the cursor on an indent tab and press Delete. To change a number to a lower heading level, place the cursor on one of the indent tab marks and press Ctrl-T.


Paragraph-Number Remove

Paragraph-Number Remove is used to delete a paragraph number from a document. The Delete and Backspace keys can also be used to remove a paragraph number. When the number is deleted, any indentions or tabs associated with the number's level are unaffected.


References Toc

For many word processing applications, a table of contents is an essential reference for finding particular sections or topics within a long document. However, to manually create a table of contents can be a long, time-consuming process. The Document References Toc command provides an easy method for designating words in your text as table of contents entries and automatically generating a table of contents based on the entries you have marked.

The format, style, and appearance of a generated table of contents is determined by the settings on the Current Document Options menu. This menu is accessed by selecting Layout Document-Options Current-Document. Margins for the table of contents, the style and placement of page numbers, the inclusion of section numbers with the page numbers, and the style and format of the table of contents entries and levels are all dependent upon the settings specified in this definition menu.

Table of contents marks, displaying


Toc Add

Toc Add is used to designate document text as a table of contents entry and assign it a heading level. The table of contents lists the marked entries in a "first encountered, first listed" order. Therefore, entries that you want to be subordinate to other entries must occur later in your document text than the related, "higher-ranking" entries. The following steps explain the entry-marking process.

Step 1: Position the cursor on the text you wish to make a table of contents entry.

Step 2: Select Toc Add command.

Step 3: Highlight the text that will be the entry. Press F10.

Step 4: Enter a number from 1 - 5 to determine the heading level for this entry. An example of the different heading levels is shown below.

Example:

     TABLE OF CONTENTS

     CHAPTER I.  INTRODUCTION   (Heading Level 1)

     SmartWare Word Processor  (Heading Level 2)
     Features and Capabilities  (Heading Level 3)
     Multiple Windows  (Heading Level 4)
     Splitting Windows  (Heading Level 5)
     Closing Windows  (Heading Level 5)
     Graphics in Documents  (Heading Level 4)

The wording of the heading will appear in the table of contents exactly the same as the marked text appears in the document. This includes capitalization and punctuation.

Once you mark document text to be a table of contents entry, it is surrounded by table of contents marks.


Toc Generate

After marking entries in the document, select the Toc Generate command to generate the table of contents.

SmartWare places the generated table of contents at the end of the current document, separating it from the rest of the document by a section break.

A generated table of contents can be edited in the same manner as any other part of a document. However, any manual editing done to the table of contents will not be retained if Generate is executed subsequent to the editing. In addition, if you add any new entries using the Toc Add command, these additions are not reflected in the table of contents until it is regenerated subsequent to the entry additions.

If you do regenerate the table of contents, the new one will overwrite the old one unless you have moved it from the end of the document.


Editing Toc Entries

If you edit text marked as a table of contents entry, or if you move a block containing marked text, the changes are automatically reflected in the table of contents the next time it is generated. If you copy a block of text containing an entry, the TOC marks are kept with the new entry and it is reflected in the table of contents. If, however, you move or copy a block of text that causes the marked table of contents entry to be split, the corresponding heading will consist of only the marked text that remained in the original location. The portion of the marked text that was moved or copied will no longer be referenced by a table of contents heading when the table of contents is next generated.


Toc Remove

To "unmark" table of contents entries in your document, position the cursor on the text surrounded by the marks and execute the Toc Remove command. You can also delete either of the table of contents marks. The table of contents heading that references that text is eliminated the next time the table of contents is generated.


Document Send

Document Send is used to transfer information from an active Word Processor document file or textfile to SmartWare Communications, SmartWare Database, or SmartWare Spreadsheet. When you execute Document Send, SmartWare exits the Word Processor and enters the module that you have selected to receive the information.

When you select Document Send, you must specify the SmartWare module you want to receive the information. After entering the name of the file to send, the prompt Enter project file for next application: is displayed. To execute a project file immediately upon entry to the module you are sending the file to, enter the project file name. If you do not want to automatically execute a project file, press ENTER in response to the prompt. The file is then sent to the module you specified, the current module is unloaded and the destination module is loaded.


Document Send Communications

Select Document Send Communications to send a Word Processor file to SmartWare Communications. Then specify whether you want to send the information as a textfile or a document file.


Text Option

If you select Document Send Communications Text, the Word Processor file is sent to SmartWare Communications in an ASCII textfile format, regardless of whether the word processing file is a document file or a textfile.


Document Option

Select Document Send Communications Document to send the Word Processor file in its current file format to SmartWare Communications. For example, if you send a document file using this option, the file is sent to SmartWare Communications in the document file format. If you send a textfile using this option, the file is sent in ASCII textfile format.


Document Send Database

Select the Document Send Database command to send a Word Processor file to SmartWare Database. SmartWare then prompts you to Enter the document or textfile name: for the file to send. A Word Processor file is sent to SmartWare Database in an ASCII textfile format, regardless of whether the word processing file is a document file or a textfile.
Comment: A blank space constitutes the end of a character string "group."

When the Word Processor file is received in SmartWare Database, the data is displayed in "fields" and "records." Each word or character string "group" of the word processing file is translated into a Database field. Each line of the word processing file is translated into a Database record. The record structure for the Database file (i.e., the number of fields available in each record) is determined by the first line of the word processing file.

For example, if the first line of the word processing file contains 4 words, the record structure for the Database file is established as having 4 fields. If the second line of the word processing file contains 10 words, the record structure is still restricted to only 4 fields; the remaining 6 words are lost in the second record.

You can format the Word Processor file, prior to sending it to the Data Base, so that more than a single word or character string group is included in a Database field. The word processing file should be formatted in the following manner:
*** The data to be contained in each Database record should be entered on a separate line, terminated by a carriage return (ENTER).
** A blank space (SPACEBAR) should separate the data to be contained in each Database field.
** Data that is to be interpreted as a text field in the Database file should be surrounded by quotation marks in the word processing file.

For information on SmartWare Database field types and record structures, refer to Database Manual.


Document Send Spreadsheet

Select Document Send Spreadsheet to send a Word Processor file to SmartWare Spreadsheet. SmartWare then prompts you to Enter the document or textfile name: for the file to send. A Word Processor file is sent to SmartWare Spreadsheet in an ASCII textfile format, regardless of whether the word processing file is a document file or a textfile.
Comment: A blank space constitutes the end of a character string "group."

When the Word Processor file is received in SmartWare Spreadsheet, the data is displayed in "rows" and "cells." Each word or character string "group" of the word processing file is placed in a separate Spreadsheet cell. Each line of the word processing file is placed in a separate Spreadsheet row.

You can format the Word Processor file, before sending it to the Spreadsheet, so that more than a single word or character string group is included in a Spreadsheet cell. The word processing file should be formatted in the following manner:
*** The data to be contained in each Spreadsheet row should be entered on a separate line, terminated by a carriage return (ENTER).
** A blank space (SPACEBAR) should separate the data to be contained in each worksheet cell.
** Data that is to be interpreted as text by SmartWare Spreadsheet should be surrounded by quotation marks in the word processing file.

For information on SmartWare Spreadsheet cell types and worksheet structures, refer to Spreadsheet Manual.


Document Visible

Document Visible is used to toggle on or off the display of hidden text in a document; page breaks; section breaks; rulers; tabs; and marks such as paragraph marks, keep marks, index marks, table of contents marks, or hidden text marks. All of the Document Visible commands are toggle commands; if the execution of one of the Document Visible commands turns the display of a feature off, executing the same command again will turn the display of the feature on.


Document Visible Hidden-Text

Document Visible Hidden-Text is used to toggle on or off the display of hidden text in the document. When text is hidden (using the Layout Hidden-Text command), SmartWare surrounds the hidden text with hidden text marks. Whether or not these marks are displayed is dependent upon whether Document Visible Marks Hidden-Text is toggled on or off.
*** When the hidden text marks are not displayed and the hidden text is displayed, the hidden text appears in the document and there is no indication that any text in the document is marked as hidden text.
** When the hidden text marks and hidden text are not displayed, there is no indication that hidden text exists in the document. The document reforms to compensate for the hidden text.
** When the hidden text marks and hidden text are displayed, hidden text marks surround the hidden text.
** When the hidden text marks are displayed and hidden text is not displayed, the document reforms to compensate for the hidden text and the hidden text marks are combined into one mark. This mark is located at the position where the first character of the hidden text will reappear when Document Visible Hidden-Text is executed again.

If invisible hidden text that contains a hard page break or a section break is positioned inside a designated Keep area, when the hidden text is made visible, the corresponding Keep area is eliminated. Invisible hidden text is made visible internally by SmartWare when:
*** the file is saved
** text containing hidden text is moved
** text containing hidden text is copied

Refer to the Layout Keep command discussed under Layout Commands later in the Command Reference for more information on this subject.


Document Visible Marks

Document Visible Marks is used to toggle on or off the display of hidden text marks, index marks, keep marks, and table of contents marks in the current document. When Document Visible Marks is selected, you must specify the type of mark you want to toggle on or off.


Document Visible Marks All

Document Visible Marks All toggles the display of all types of marks on or off in the current document. The display of hidden text marks, index marks, keep marks, and table of contents marks are all affected by the execution of this command.


Document Visible Marks Hidden-Text

Document Visible Marks Hidden-Text is used to toggle on or off the display of hidden text marks. When text is hidden (using the Layout Hidden-Text command), SmartWare distinguishes the hidden text by surrounding the specified text with hidden text marks. Whether or not these marks are displayed depends on whether Document Visible Marks Hidden-Text is toggled on or off.


Document Visible Marks Index

Document Visible Marks Index is used to toggle on or off the display of index item marks. When a word or phrase is designated as an index item (using the Document References Index Add command), SmartWare surrounds the specified word or phrase with index item marks.


Document Visible Marks Keep

Document Visible Marks Keep is used to toggle on or off the display of keep marks. When an area of text is designated as a keep area (using the Layout Keep Insert command), SmartWare "fences off" the specified area so that it cannot be split by a page break or section break. Keep marks are inserted at the far left of the Document Window (character position 0) on the line above and the line below the specified Keep area.


Document Visible Marks Toc

Document Visible Marks Toc is used to toggle on or off the display of table of contents marks. When text is designated as a table of contents entry (using the Document References Toc Add command), SmartWare surrounds the specified text with table of contents marks.


Document Visible Newpage

Document Visible Newpage is used to toggle on or off the display of hard page breaks, soft page breaks, and section breaks. Hard page breaks are inserted using the Layout Newpage Insert command. Section breaks are inserted using the Layout Section Insert command.


Document Visible Paragraphs

Document Visible Paragraphs is used to toggle on or off the display of paragraph marks. A paragraph mark is inserted whenever ENTER is pressed.


Document Visible Rulers

Document Visible Rulers is used to toggle on or off the display of rulers. Two types of rulers can be displayed in a document, the Main Ruler or Embedded Rulers. The Main Ruler is displayed at the top of the screen and is a copy of the Current Ruler, which reflects the settings for the current paragraph. Embedded rulers are displayed in the body of the text and represent changes in the format of the document.


Document Visible Tabs

Document Visible Tabs is used to toggle on or off the display of tab symbols. A tab symbol is inserted whenever TAB is pressed.


Document Lock

Document Lock is used to protect a document from permanent, unauthorized modification. Locking a document does not prevent others from loading, editing, printing, or merging the document. However, if modifications are made to the document, it cannot be saved, printed, or merged. Lock protection is not available for textfiles.
IMPORTANT: While locking a document does protect it from revision in most cases, there are ways to get around this protection. The only way to completely protect a document is to use the ATTRIB command at the DOS level to make it a read-only file.

Password Protection


 When you select Document Lock, the prompt Enter a lock password: is displayed. Enter a maximum of 16 characters and press ENTER. You are then prompted to confirm the password.
NOTE: Once you've assigned a password to the document you want to lock, you must unload the file before the lock takes effect. If you just save the file, it is locked against anyone else who loads it, but you can still make changes to it. Only after it is unloaded is the document truly locked.

After a document has been locked, the File Newname command and the Document Auto-Save feature are disabled for the document. Once the locked document has been unloaded, the File Save command is also disabled for the document.


Document Unlock

Document Unlock is used to remove the lock protection that was assigned to the current document when Document Lock was executed. When you select Document Unlock, the prompt Enter the lock password: is displayed. Type the password that was entered at the time the Document Lock command was executed and press ENTER to execute the Document Unlock command.


Edit Commands

The Edit keyword is the basis for the command formats that enable you to modify and refine documents in a variety of ways. Using these commands, you can:

* copy, move, or delete sections of text
* replace a specified character string with an alternative
character string
* perform alphabetical sorts on sections of text.


Edit Options

Edit provides the following options:

Copy. Duplicates specified text.
Delete. Removes selected text from your document.
Edit-Case. Changes the case of specified text.
Move. Relocates text to another area of the document.
Replace. Finds a specified character string and replaces it with an alternative character string.
Sort. Sorts standard or columnar text in A to Z or Z to A order.
Undelete. Inserts at the current cursor position any text contained in the delete buffer.


Edit Copy

Edit Copy is used to duplicate selected document text. The duplicated text can either be inserted at another location in the current document or the text can be copied to the copy buffer. By copying to and from the copy buffer, duplicated text can be inserted in multiple locations in the current document or another active document.

The following steps are required for a copy.

Step 1: Select Edit Copy.

The block-marking menu then appears in the control area.


 Step 2: Mark the text you want to copy.

You can use the block-marking keys to highlight specific areas of text (i.e. F6 to highlight a sentence), press F4 to go into column-marking mode, or use cursor keys to highlight the desired text. Press Enter or F10 to complete the marking process.

Marking Techniques


Edit Delete

Edit Delete is used to remove text from a document. When you select Edit Delete, SmartWare enters block-marking and displays a marking menu in the Control Area of the screen. You can switch to column-marking by pressing F4.

Indicate the text you want to delete by using the cursor keys or the marking keys defined in the marking menu. Press F10 or ENTER to execute the Edit Delete command and remove the marked text from your screen. Your document automatically reforms to compensate for the deleted text.

When you execute Edit Delete, the text you have removed from your document is stored in a delete buffer. The text remains in the delete buffer until you either execute Edit Delete again, erase the contents of the delete buffer using ALT-minus, or exit SmartWare Word Processor.

The contents of the delete buffer can be inserted in one or more locations within any active document by executing the Edit Undelete command. A portion of the delete buffer can be viewed in the Control Area of the screen by repeatedly pressing F2 when in Text Entry Mode.


 Step 3: You are then prompted to Move cursor to desired location and press Enter (B = Buffer[]).

Use cursor keys to move to the desired location in the current document and then press Enter. The text is then copied to its new location.

Using Buffers

If you want to copy text to another document, or you aren't sure where you want it right now, you can place it in a copy buffer until you are ready to reinsert it. To copy text to the buffer, mark the text as described previously, and press B at the prompt Move cursor to desired location and press Enter (B = Buffer). The text will remain in the buffer until you copy more text to the buffer, clear the buffer by pressing Alt-minus, or exit the Word Processor.
NOTE: The amount of text that may be placed in a buffer is limited by available memory and available disk space.


Inserting Text from the Buffer

There are two ways to insert text from the buffer into a document. You can use the Edit Copy command or use the Quick Key Alt-I.

Commands. Select Edit Copy. When the marking menu appears in the Control Area, press B for Buffer. SmartWare then recognizes the contents of the copy buffer as the text you want copied. Move the cursor to the new location and press Enter. The buffer contents are inserted at the cursor position, and the document reforms, as necessary, to compensate for the additional text.

ALT-I. The contents of the buffer can also be inserted at the current cursor location by pressing ALT-I. This method is particularly useful if you need to insert the contents more than once into your document. Position the cursor at the first location you want to insert text and press ALT-I. Then move to the second location and press the repeat key F9. If no other command has been executed since ALT-I was pressed, the buffer text will again be inserted at the cursor position. You can continue moving the cursor and pressing F9 as often as needed. If you execute other commands between insertions, you must use ALT-I again.


Repeating a Copy

There may be times you want to repeat the entire copy process you have just completed. As just illustrated, the F9 key can be used to repeat the last command. F9 repeats the last command exactly as SmartWare recorded it. Therefore, the way you mark text and specify its location makes a big difference if you want to use F9 effectively.


Marking Text

The text you want to copy or move can be marked using cursor keys or marking keys. When you use cursor keys, SmartWare records a command such as:

     Edit Copy point

If you press F9, Edit Copy will be executed, but the command will be interrupted and you will be asked to mark the text you wish to copy.

If you use marker keys to specify text, the appropriate word becomes part of the command. For example, if you select Edit Copy and then press F6 to highlight a sentence, the command is recorded as:

     Edit Copy sentence

If you press F9, Edit Copy will be executed, and the sentence at the current cursor position will be copied.

As you can see, the second alternative is a more automatic process.

If you repeat a command that used column-marking instead of block-marking, you must use cursor keys to specify how many columns are affected.

If you repeat a command that used buffered text as the source, the current buffer contents will be used.


Location

If you repeat a copy in which you moved the cursor to the new location for the text, you will be asked to do so again. If you repeat a copy that placed text in a buffer, the text will again be placed in a buffer.

For example, if you execute Edit Copy, press F7 to mark a paragraph and then move the cursor to the new location, the following command is recorded.

     Edit Copy paragraph to point

If you move the cursor to a new location and press F9, Edit Copy will be executed and the current paragraph affected. You will then be prompted to move the cursor to the new location for the text. You can move the cursor or press B for Buffer.


Edit Edit-Case

Edit Edit-Case allows you to change the case of words or blocks of text without retyping. You can put all marked text into lower case, upper case, or make it proper by capitalizing only the first letter of each word. The case of marked characters marked may also be inverted.


 The options for this command are: Lower, Upper, Proper and Inverted. Selecting any of these options takes you into marking mode. Highlight all the text you want the command to affect. Press F10 and the command is executed.


Edit-Case Lower

If you select the option Lower, all text you highlight will be put into lower case.


Edit-Case Upper

If you select the option Upper, all highlighted text will be put into upper case.


Edit-Case Proper

If you select the option Proper, the first letter only of each word in the highlighted text will be capitalized.


Edit-Case Invert

If you select the option Invert, the case of each character in the highlighted text will be reversed. That is, all upper case characters will be converted to lower case, lower case characters will be converted to upper case.


Edit Move

Edit Move is used to relocate specified text from its current position in a document to a new position. The text can either be relocated in the current document or the text can be moved to the copy buffer. By moving text to and from the copy buffer, moved text can be inserted (using ALT-I) any number of times into any active document.

The following steps are required for a move.

Step 1: Select Edit Move.

The block-marking menu then appears in the control area.

Step 2: Mark the text you want to move.


 You can use the block-marking keys to highlight specific areas of text (i.e. F6 to highlight a sentence), press F4 to go into column-marking mode, or use cursor keys to highlight the desired text. Press Enter or F10 to complete the marking process.


File Export

File Export is used to write all or part of the current file to a new file. When you select File Export, SmartWare enters block-marking mode. You can switch to column-marking mode by pressing F4. Use the cursor keys or the marking menu keys to highlight the section of text you want to export and press F10 or ENTER. The prompt Enter the filename: is then displayed.


Layout Font Change

The following steps explain how to change the type style for a specified area of text.


 Step 3: You are then prompted to Move cursor to desired location and press Enter (B = Buffer[]).

Use cursor keys to move to the desired location in the current document and then press Enter. The text is then moved to its new location.

Using Buffers

If you want to move the text to another document, or you aren't sure where you want it right now, you can place it in a buffer until you are ready to reinsert it. To move text to the buffer, mark the text as described previously, and press B at the prompt Move cursor to desired location and press Enter (B = Buffer). The text will remain in the buffer until you move more text to the buffer, clear the buffer by pressing Alt-minus, or exit the Word Processor.
NOTE: The amount of text that may be placed in a buffer is limited by available memory and available disk space.


Inserting Text from the Buffer

There are two ways to insert text from the buffer into a document. You can use the Edit Move command or use the Quick Key Alt-I.

Command. Select Edit Move. When the marking menu appears in the Control Area, press B for Buffer. SmartWare then recognizes the contents of the buffer as the text you want moved. Move the cursor to the new location and press Enter. The buffer contents are inserted at the cursor position, and the document reforms, as necessary, to compensate for the additional text.

ALT-I. The contents of the buffer can also be inserted at the current cursor location by pressing ALT-I. This method is particularly useful if you need to insert the contents more than once into your document. Position the cursor at the first location you want to insert text and press ALT-I. Then move to the second location and press the repeat key F9. If no other command has been executed since ALT-I was pressed, the buffer text will again be inserted at the cursor position. You can continue moving the cursor and pressing F9 as often as needed. If you execute other commands between insertions, you must use ALT-I again.


Repeating a Move

There may be times you want to repeat the entire move or process you have just completed. As just illustrated, the F9 key can be used to repeat the last command. F9 repeats the last command exactly as SmartWare recorded it. Therefore, the way you mark text and specify its location makes a big difference if you want to use F9 effectively.


Marking Text

The text you want to copy or move can be marked using cursor keys or marking keys. When you use cursor keys, SmartWare records a command such as:

     Edit Move point

If you press F9, Edit Move will be executed, but the command will be interrupted and you will be asked to mark the text you wish to move.

If you use marker keys to specify text, the appropriate word becomes part of the command. For example, if you select Edit Move and then press F6 to highlight a sentence, the command is recorded as:

     Edit Move sentence

If you press F9, Edit Move will be executed, and the sentence at the current cursor position will be copied.

As you can see, the second alternative is a more automatic process.

If you repeat a command that used column-marking instead of block-marking, you must use cursor keys to specify how many columns are affected.

If you repeat a command that used buffered text as the source, the current buffer contents will be used.


Location

If you repeat move in which you moved the cursor to the new location for the text, you will be asked to do so again. If you repeat move that placed text in a buffer, the text will again be placed in a buffer.

For example, if you execute Edit Move, press F7 to mark a paragraph and then move the cursor to the new location, the following command is recorded.

     Edit Move paragraph to point

If you move the cursor to a new location and press F9, Edit Move will be executed and the current paragraph affected. You will then be prompted to move the cursor to the new location for the text. You can move the cursor or press B for Buffer.


Edit Replace

Edit Replace locates a text string and replaces it with an alternative text string. The following steps explain the procedure.

Step 1: Select Edit Replace or use the Quick Key F5.


 Step 2: Enter the text string to search.

You can enter up to 50 characters. A question mark (?) will match any character. For example, "move?" would match "mover," "moves," and "moved." SmartWare automatically inserts double quotation marks (") around the search string. If you want to search for a string that has a leading or trailing space, include the space when you type the search string.


 Step 3: Enter the text string to replace the search string.

For example, if you enter blue as the search text and red as the replacement text, the word blue in your document will be replaced by red. Whether this change affects the entire document or only specific occurrences of blue depends on the search options you select.


 Step 4: Enter search options to control how your document is searched.

Up to ten options can be entered. A list of available options is displayed.

The following table gives an explanation of each search option:

Table 9-8
Option | Action
F | Search forward from the current cursor position to the end of the file.
B | Search backward from the current cursor position to the beginning of the file
I | Ignore the case of the character string during the search.
W | Search for whole words only.
M | Search an area of the document you mark.
GF | Search from the beginning of the file and searches forward replacing every occurrence of the string with the replacement text.
GB | Search from the end of the file and proceeds backward, replacing every occurrence of the string with the replacement text.
C | Prompts Replace? (Enter = yes, space = no, F10 = quit) each time the character string is encountered. Press ENTER to replace the string; press SPACEBAR to leave the string intact; or press F10 to abort the Edit Replace command.

These options can be combined to specify the scope of a search. You can also enter a number after the search option character(s) to instruct SmartWare to find a specific occurrence of the character string.

For example, FI9 instructs SmartWare to search forward from the cursor for the ninth occurrence of the string, ignoring its case. When the ninth occurrence is located, the cursor is positioned at the beginning of the string and the search stops.

If the string is not found, the message Text "xxx" not found. is displayed.

The text string you are searching for and the search options are stored in buffers, becoming "default" values for subsequent uses of Edit Replace. To accept a displayed default value, press ENTER in response to the prompt. To change the value, enter the desired text or option.

Finding Character Strings

Repeating a Search

You can repeat a search by pressing F9 to repeat the last command. If you have executed another command since Edit Replace, use ALT-R to repeat the last search. When you press ALT-R, SmartWare repeats either the last Document Find or the last Edit Replace command, whichever command was executed more recently.


 To sort columns:

Step 1: Select Edit Sort Columns.

Step 2: Specify whether you want an ascending or descending sort.

When an Ascending sort is performed, the paragraphs in the column are reordered alphabetically. When a Descending sort is performed, the paragraphs in the column are placed in reverse alphabetical order.

SmartWare enters MCA column-marking and highlights the current column.

Step 3: Use the cursor keys to move to the column you want to sort.

If you are sorting a linked MCA, move to the "key" column. When the appropriate column is highlighted, press F10 or Enter.


File Import

File Import inserts at the current cursor position a file stored on disk. The following steps explain the importing process.

Step 1: Move the cursor to the position you want the imported text inserted.

Step 2: Select File Import.

A prompter listing the document and text files in the current data directory is displayed.

Step 3: Enter the name of the file to import.

Type the name of the file you want, or move the pointer to the appropriate filename, and press ENTER. The file is then inserted in your current document at the current cursor position.

Loading Files

You can also use File Import to bring information from other SmartWare modules into a document. In order to do this, the files must have been exported with the proper file Export commands from the module in question.
*** From the Spreadsheet: File Export ASCII, File Export WP-Doc, or File Export Text.
** From the Data Base: File Export ASCII, File Export Smart, or File Export Text.


Print Document

Print

The Print command is used to produce a printed copy of a document.


Window Paint Window

Window Paint Window is used to color both the foreground and the background of the Document Window. Text that you enter into your document appears in the color specified for the foreground.

When the command is selected, the prompt Enter background color (0 to 15): and a color selection bar are displayed in the Control Area of the screen. Enter the number corresponding to the color desired for the document text and press F10 or ENTER. SmartWare then prompts Enter foreground color (0 to 15): and again displays the color selection bar. Enter the number desired for the Document Window background and press F10 or ENTER. The Document Window and text are then displayed in the selected colors.


Replacing Special Characters

Edit Replace can also be used to replace tab or paragraph marks with blank spaces. To replace a sequence of tab characters with blank spaces, enter %T as the search string and press SPACEBAR once to specify the replacement string. Likewise, to replace a sequence of paragraph marks with blank spaces, you would %P as the search string and press SPACEBAR once to specify the replacement string.
NOTE: Edit Replace performs a "one-to-one" replacement until all the characters in either the original string or the replacement string are used. If you are replacing a character string that includes any control characters (i.e., hidden text marks, index marks, table of contents marks, font changes) and the replacement string contains more characters than the original string, the replace is performed in the following manner:
*** The same number of characters are replaced before the opening control character as were present before the opening control character in the original string.
** If the search string ends with the character immediately preceding an ending control character, the remaining characters in the replacement string are inserted before the ending control character, regardless of the number of characters that existed between the control characters in the original string.
** If the search string contains characters to the right of the ending control character, the same number of characters are replaced inside the control codes as were present in the original string.


Edit Sort

Edit Sort provides an alphabetical A to Z or Z to A sorting of standard text or text contained in a multiple column area. The amount of text that you can sort at one time is limited only by the memory restrictions of your computer.

Edit Sort considers everything between two paragraph marks to be a unit that must be kept together during a sort. Because of this you do not have to worry if each item you sort wraps to more than one line. SmartWare will keep the lines together and sort according to your specification.

Edit Sort allows you to specify one or more text column positions to use as the "key" for a sort. Text entries are alphabetized according to the specified "key" in either ascending (A to Z) or descending (Z to A) order. When you select the Edit Sort command, you must indicate whether you want to perform a sort on text contained in a multiple column area or on text entered in a "standard" format.


Sort Column

Edit Sort Column provides ascending and descending alphabetical ordering for text contained within an MCA. In an unlined MCA, only one column of text can be sorted at one time. In a linked MCA, all the columns are sorted together, with one column being designated as the "key for the sort.


Sort Text

Edit Sort Text provides ascending or descending alphabetical ordering for standard text (non-MCA text.) SmartWare identifies a single sort "item" as the text positioned between two paragraph marks.


 The following steps explain the process for sorting text.

Step 1: Select Edit Sort Text

Step 2: Specify whether you want an ascending or descending sort.

When an Ascending sort is performed, the paragraphs in the column are reordered alphabetically. When a Descending sort is performed, the paragraphs in the column are placed in reverse alphabetical order.

Step 3: Mark the block you want to use as your sort key.

Use UP or DOWN to mark the text that you want to sort. You can designate more than one column of characters to use as the "key" for your sort by using LEFT, RIGHT, CTRL-F, or CTRL-G.

Step 4: After you have marked the text, press F10 or ENTER.

The message Sorting . . . temporarily appears in the Control Area of your screen while SmartWare works internally to manipulate the data into the order specified by the "key" you marked. Your text is then reordered and displayed on the screen.

When using Edit Sort, be certain to extend your "key" across sufficient columns to allow for correct alphabetical sorts for words that contain the same first few characters.
IMPORTANT: Accented or "double" foreign language characters may not sort properly unless you select the character comparison table for that language. To select a character comparison table, select Tools Preferences Global and move the cursor to the Character Comparison Table: prompt. Press F6 to display a list of languages for which character comparison tables have been installed. Select the language you will be sorting.


Edit Undelete

Edit Undelete is used to restore text that was deleted when the last Edit Delete command was executed. Edit Undelete retrieves all of the text stored in the delete buffer and inserts it into your document at the current cursor position.

Deleting text

Before selecting Edit Undelete, position your cursor at the location where you want the text to be inserted. When you execute the command, the text in the delete buffer is inserted at the current cursor position and your document reforms to accommodate the inserted text.

Text stored in the delete buffer can be inserted in multiple places in your document by repeatedly executing Edit Undelete. The text remains in the delete buffer until you either execute another Edit Delete command, erase the contents of the delete buffer using ALT-minus, or exit SmartWare Word Processor.


File Command

The File keyword is the basis for the command formats that enable you to perform direct disk and file access operations. These commands provide you with storage, access, and retrieval capabilities for managing and maintaining your document files.


File Options

File provides the following options:

Load. Loads into the current window a document file or textfile stored on disk.
Save. Stores on disk a copy of the current file.
Unload. Removes the current file from memory.
Newname. Assigns a new filename to the current document file or textfile.
Display-Active. Displays a listing of all currently active files.
File-Type. Changes the current document file to a textfile or vice versa.
Export. Writes all or part of the current document file or textfile to a new file.
Import. Inserts at the current cursor position a document file or textfile stored on disk.
Password. Restricts user access to a document.


File Load

File Open

This command copies a document into memory and displays it. With pulldown menus this command is called Open while on command lists it is load. In both cases it is accessed from the File menu.

When selected, SmartWare displays a file promptor or Windows dialog box requesting the name of the file to load.

You can select a document from the displayed listing, or, if the file you want is not in the directory, you can type the name of the document.

The remaining instructions refer to the SmartWare file prompter.


Displaying Directories Within a File List

In addition to listing files, file prompters also display subdirectories of the current directory. Directories are listed after files and are identified by the path symbol (\). For example files\ indicates a subdirectory of the current directory named files.

If you point to a directory and press Enter, the prompter displays files and subdirectories in the newly selected directory. The current path is identified on the Status Line. Continue selecting directories until you find the file you want.

After loading a file, File Load can be executed a second time without unloading the first file from memory. The second file is displayed in the current window and the first file remains active in the "background." Active, non-displayed files can be displayed in your current window or in a split window by selecting the Document Goto Document command.

Unloading Files


File Save

File Save as

File Save is used to store on disk a copy of the current file. When File Save is selected, the prompt Enter a filename: is displayed.

To save a file:
*** with the same name, in the directory from which it was loaded, press ENTER.
** using a different name, in the directory from which it was loaded, type the new filename and press ENTER.
** to a different directory, type in the complete pathname, including drive letter if applicable, and press, Enter.
Comment: Enter path specifications only when you are deviating from the current data path. The current path is automatically accepted unless otherwise specified.

If a file does not have a name, you must assign it one when you save the file.

The name you assign to a file can be a maximum of eight characters, using any combination of letters, numbers, and the underscore (_) character. Filenames cannot contain blank spaces.

If you enter a filename that already exists in the path specified, the prompt File of that name exists. Overwrite (y/n) is displayed. Enter y to overwrite the file currently stored on disk. Enter n to abort the command. Refer to Software System Manual for a complete discussion of filenames, file extensions, and file specifications.


File Unload

File Close

This command is used to remove the current file from memory. When selected, the current file is removed from the screen and memory, unless it has been modified since it was last saved. If changes have been made to the file, SmartWare prompts Save modified document first (y/n). Enter y to save the modified document before it is unloaded. Enter n to unload the modified document without saving any changes you have made.
IMPORTANT: When you unload a locked document, any changes you have made to the document are permanently lost.

If you enter y and the document is unnamed, the message Current document is unnamed; enter new name: is displayed. Enter a filename and press ENTER. Once a document is unloaded using File Unload, it cannot be displayed using the Document Goto Document command until it has been loaded again using the File Load command.

Loading files
Saving files


File Newname

File Newname is used to assign a filename to the document file or textfile in your current window. When File Newname is selected, the prompt Enter the new filename: is displayed.

Enter a maximum of eight characters for the filename, using any combination of letters, numbers, and the underscore (_) character and press ENTER.

After the File Newname command is executed, the new filename is displayed on the Status Line next to the Document: or Textfile: indicator.


File Display-Active

File Display-Active is used to display a listing of all currently active files. When you select this command, the Document Window is temporarily displaced and the screen is filled with an active files listing. The filename, file type, and status are displayed for each active word processing file. To remove the listing from the screen and return to the Document Window, press F10, ESC or ENTER.


File File-Type

File Type

This changes the current document file to a textfile or vice versa. The file type of the current file is displayed on the Status Line at the bottom of the screen. If it is a document file, Document: filename is displayed. If it is a textfile, Textfile: filename is displayed.

File Type is a toggle command. If the current file is a document file, execution of the command changes it to a textfile and assigns the file the extension "txt." Likewise, if the current file is a textfile, execution of the command changes it to a document file and assigns the file the extension "doc."

When you change the type of a file, if a file of that type and name already exists, you will receive a warning message.

The file type of the current file is displayed on the Status Line at the bottom of the screen. If the current file is a document file, the Status Line displays Document: filename. If the current file is a textfile, the Status Line displays Textfile: filename.

The following changes are made when a document file becomes a text file.
*** All lines end with a carriage return and a line feed.
** Tabs are represented as a series of space characters.
** Special control characters, fonts, and print attributes are not used.
** No formatting options or print options are stored with the file.
** When the file is saved, footnotes are written to the file and appear as normal text when the file is reloaded.

The following changes are made when a text file becomes a document file.
*** The carriage return and line feed remain at the end of every sentence.


 Type a name for the output file (preceding the filename with path designations if you do not want to write the file to the current data path), and press ENTER to execute the File Export command.

Saving files
Integration, Modular


File Password

File Password is used to restrict access to a document. When you select File Password, you must specify whether you want to attach or remove a password for the current document.

Locking Documents


File Password Attach

To attach a password to a document:

Step 1: Select File Password Attach.

The prompt Enter new password: is displayed.

Step 2: Enter a password for this file and press Enter.

Type a maximum of 16 case sensitive characters, using any combination of letters and numbers.

Step 3: Repeat the password for verification and press Enter.

Once a password has been attached to a document, you must save the document, using the File Save command, to effect password protection on the file. The specified password is then saved with the document file and SmartWare prompts for the password whenever an attempt is made to load, import, or print the document.

Password protection is not available for textfiles. If you change a password-protected document file to a textfile (using the File File-Type command), the textfile is not protected. Hence, if the file is saved in textfile format, restriction to the file is lost. However, if before you unload the file from memory you convert the textfile back into a document file, the password is saved with the document when the file is saved. When new files are created from a password-protected file using the File Export or Document Send command, the new files are not password protected.


File Password Remove

File Password Remove is used to eliminate a password that was assigned to restrict access to a document. Since File Password Remove operates on the current document only, you must load the password-protected document and have it displayed on the screen as the current document before executing the File Password Remove command.

Once a password has been removed from a document, you must save the document, using the File Save command, to eliminate password protection in the file.

Unlocking Documents


Layout Commands

The Layout keyword enables you to manipulate the arrangement of your document text. Using the Layout commands, you can:

* format and reformat text
* divide a document into sections
* control the layout of index, table of contents, and
footnotes
* enhance the display of documents with font and style
changes


Layout Options

Layout provides the following options:

Document-Options. Provides formatting for an index, table of contents, or footnotes; controls language, consecutive hyphenations, and dictionaries used during spellchecking operations.
Font. Provides type style changes for document text.
Hidden-Text. Allows specified text to be marked so that it can later be hidden or displayed.
Keep. Allows insertion and deletion of "fences" to keep blocks of text on the same page.
Newpage. Provides automatic and manual document pagination.
Ruler. Enables text alignment, margin, indention, tab, and line spacing changes within the same document.
Section. Separates sections of text, enabling print option items to vary within the same document.


Layout Document-Options

Layout Document-Options displays a definition menu containing specification items to control:

* margins
* headings
* line spacing
* tabs
* indention levels for an index or table of contents
* footnote numbering and placement
* dictionary language
* custom dictionaries
* hyphenation standards

The same definition menu is displayed when either Layout Document-Options Current-Document or Layout Document-Options New-Documents is selected. Settings established with the Current Document Definition Menu affect the current document only. Settings in the New Document Definition Menu create a template for all new documents that are created.


Layout Document-Options Current-Document

The Current Document Definition Menu contains specification items that govern the placement and numbering sequence for footnotes, and the style and numbering sequence for the paragraph numbering feature. In addition, dictionary language, hyphenation standards, and custom dictionary information items are contained in the definition menu, as well as index and table of contents margins, heading, font, page number placement, spacing, and indention controls. Each definition menu item is discussed in detail below.


Footnote Options

Enter a number between 1 and 6 to control where footnotes will be printed and how they will be numbered. Following is a list of available numbers and a description of the footnote formats they represent.
1. Print footnotes at the bottom of each page containing a reference and restart numbering on every page.
2. Print footnotes at the bottom of each page containing a reference and restart numbering at the beginning of each document section.
3. Print footnotes at the bottom of each page containing a reference and number them sequentially throughout the document.
4. Print footnotes at the end of each document section and restart numbering at the beginning of each section.
5. Print footnotes at the end of each document section and number sequentially throughout the entire document.
6. Print footnotes at the end of the document and number sequentially throughout the entire document.

Footnote Reference Font. Enter a valid font number that will be used for the footnote reference numbers inserted in a document. Font number 1 is the default for this purpose and is predefined as standard 10 point superscript.

Footnote features, using


Paragraph Numbering Options

The Paragraph Numbering options control the style used for paragraph numbering, numbering sequence and how the number will be separated from the text.

Style. Select either Paragraph, Outline, Legal, or German-Legal for the numbering style.
NOTE: German-Legal is the same as Legal, except that no punctuation is provided after numbers on any level.

Restart at Section Boundary. Select Yes to restart paragraph numbering at the beginning of each section boundary. Select No to number paragraphs sequentially throughout the entire document.

Separation from Text. Select None to have no automatic separation between the number and paragraph text. Select Space to separate the number and text with a single space. Select Tab to have the first line of text tabbed over one tab stop on the current ruler. Select Indent-Tab to have the entire paragraph indented via an indent tab.

Paragraph Numbering Features


Index Options

The Index options control the structure and appearance of a generated index.

Left and Right Margins. Enter a number, in inches, for each margin. When an index is generated, it will conform to these margins.

Alphabetic Headings. To have no alphabetic headings for your entries, select BB`None. If you choose to have alphabetic headings, specify whether they are to be Uppercase or Lowercase characters.

Alphabetic Heading Alignment. Specify whether index entry headings will be Left-aligned, Right-aligned, or Centered.

Alphabetic Heading Font. Select a type style to use for the index headings. Enter a font number, or press F6 to display a prompter of fonts defined for the current document. Select a font by entering the font number or moving the pointer to the desired font and pressing ENTER.
NOTE: If you enter an invalid font number, it will be converted to font 0 when the index is generated.

Blank Lines Before/After Heading. Select a number from 0 to 3 for each setting. The number of blank lines before an alphabetic heading determines the spacing between the last group of index entries and the next alphabetic heading. The number of blank lines after an alphabetic heading determines the spacing between the alphabetic heading and the first entry of each group. If no blank lines are specified before or after the alphabetic headings, and no alphabetic headings are specified, the index will be generated as one continuous alphabetized listing.

Primary/Subordinate Entries Fonts. Enter font numbers for primary and secondary index entries. Enter a font number, or press F6 to display a prompter of fonts defined for the current document. Type in the font number, or move the pointer to the desired font and press Enter.
NOTE: If you enter an invalid font number, the font will be converted to font zero when the index is generated.

Blank Lines Between Primary Entries. Select a number from 0 to 3 to specify the number of blank lines to occur between primary entries in the generated index. If no alphabetic headings have been specified, you can set the blank lines between primary entries to 0 and generate a continuous alphabetical index that contains no blank lines.

Subordinate Entries Indention. Enter a number, in inches, to specify how far to the right each level of subordinate entries is to be indented.

Page Number Placement. Select Right-aligned to have all page numbers aligned on the right margin. Select Follow-entries to have the page numbers immediately follow the index entries.

Include Section Numbers. Select Yes to include section numbers in the page number references. Select No to exclude section numbers. The section number is separated from the page number by a hyphen (-).

If you have specified page numbering to be restarted at section boundaries, you can avoid confusion by including section numbers in the page number references.

Follow Entry With Comma, Blanks, or Leaders. Select Comma to place a comma between the index entry and the page refence. Select Blank to put three or more blank spaces between the index entry and the page reference. Select Leaders to put three or more leaders (. . .) between the index entry and the page reference.

Index Features


Table of Contents Options

The following options affect the structure and appearance of the table of contents.

Left and Right Margins. Enter a number, in inches, for each margin. When a table of contents is generated, it will conform to these margin specifications.

Page Number Placement. Select Right-Aligned to have all page numbers aligned on the right margin. Select Follow-entries to have the page numbers immediately follow the table of contents entries.

Include Section Numbers. Select Yes to include section numbers in the page number references. Select No to exclude section numbers. The section number is separated from the page number by a hyphen (-).

If you have specified page numbering to be restarted at section boundaries, you can avoid confusion by including section numbers in the page number references.

Follow Entry With Comma, Blanks, or Leaders. Select Comma to place a comma between the entry and the page reference. Select Blank to put three or more blank spaces between the entry and the page reference. Select Leaders to put three or more leaders (. . .) between the entry and the page reference.

Fonts. Specify fonts for up to five levels of table of contents entries. Setting different fonts for different levels can help differentiate them. Enter a font number, or press F6 to display a prompter of fonts defined for the current document.
NOTE: If you enter an invalid font number, the font will be converted to font 0 when the table of contents is generated.

Blank Lines Before Level. Specify 0 to 3 lines to be placed between each table of contents level. Specify a number for each level.

Blank Lines Between Consecutive Entries in Level. Specify 0 to 3 lines to be placed between consecutive table of contents entries that are assigned the same level. Specify a number for each level.

Indention. Enter a number, in inches, for each level. This number controls the left margin indention for that level.

Table of Contents features


Spellchecker Options

The following options control the operation of the Spellchecker.

Language. Spellcheckers are available in a number of languages. Select the language you want to use for the standard dictionary employed during a spellcheck. (Various language dictionaries may have to be purchased and installed separately.)

Maximum consecutive hyphen breaks. Enter a number between 1 and 100 to specify the maximum number of consecutive lines that are allowed to end with hyphenated words.

Custom Dictionaries. Enter the names of up to five custom dictionaries SmartWare will reference when spellchecking a document. The language of the custom dictionaries must match the language selected for the standard dictionary.

Dictionary Features


Miscellaneous Options

The following miscellaneous options also appear on this menu.

Minimum Gutter Space Between Quick-Define Columns. Enter a number, in inches, to control the minimum amount of blank space placed between columns when the Quick-Define column definition method is used.

Minimum Widows/Orphans Allowed. Enter the number that specifies the minimum number of lines of a paragraph that can be left at the bottom of a page, or moved to the next page when pagination causes the paragraph to be split.

Starting Section Number. Enter a number from 1 to 155 to control the starting section number for a document.


Layout Document-Options New-Documents

The same definition menu is displayed by Layout Document-Options New-Documents and Layout Document-Options Current-Document. Any changes that you make to the specifications in the New Documents Definition Menu become the new "template" that will be used for subsequent documents you create.

Refer to the previous discussion on the Current Document Definition Menu for information on each menu item.

Document Options, detail information


Layout Font

The Layout Font command is used to change the type styles used for existing text, select different type styles for new text, insert or remove boldfacing for existing text, and insert or remove underscoring for existing text.

Two predefined fonts are provided in SmartWare Word Processor. Each font name and number is shown in Table 9-9.

Table 9-9

Font Number | Font Family
0 | 12 pt Standard
1 | 10 pt Standard Superscript

In addition to the pre-defined fonts, SmartWare's Font Selector Definition Menu enables you to "customize" fonts. This definition menu is obtained by pressing F6 at the prompt, Enter Font Number: after selecting Layout Font Select, Layout Font Change, or Layout Font Edit. A total of 32 fonts, numbered 0 through 31, may be defined for each document.


Font Selector

The Font Selector Definition Menu contains numerous specification items, including a font family selection and corresponding items such as point size, slant, and weight. While you may select any of the options available, those that are surrounded by parentheses "()" are not supported by the printer currently selected in the Hardware Preferences Definition Menu. A printer capable of supporting these options must be specified and available to achieve the desired results of these options. The Hardware Preferences Definition Menu is obtained by selecting the Tools Preferences Hardware command.

For a complete description of each definition menu item, refer to the Tools New-Font command in Chapter 9 of Software System Manual.

The following Quick Keys are available for font operations:

Table 9-10

Quick Key | Result
CTRL B | Toggles on or off boldfacing for new text.
CTRL U | Toggles on or off underscoring for new text.
SHIFT F3 | Inserts or removes boldfacing for existing text.
SHIFT F4 | Inserts or removes underscoring for existing text.
F6 | Accesses Layout Font Select.


Layout Font Select

The following steps select a type style for any new text entered into the current document.

Step 1: Select Layout Font Select or the Quick Key F6.

The prompt Enter Font Number: is displayed, with a prompter containing the predefined fonts and any "custom" fonts you have defined for the current document. Each font listed in the prompter is identified by a font number, a family descriptor, and characteristics of the font such as point size, attributes, and slant.


 Step 2: Select a font from the prompter.

Move the pointer to the number desired and press ENTER or type the corresponding number and press ENTER. The number selected is displayed to the right of the Font: indicator on the Status Line and any new text you type into the document is entered in the selected font.

If the font you want to use is not listed in the prompter, press F6 in response to the Enter Font Number: prompt, to create the font desired. The Font Selector Definition Menu is then displayed.

You can change the option items for the current font family, or press F6 to display other available font family choices.

After you have selected the font family you want and have made all the desired changes, press F10. The newly defined font should now appear in the Font Selector, the next time it appears.


 Step 1: Select Layout Font Change.

Step 2: Mark the text you want affected by the font change. Press F10 or Enter.

A prompter listing the predefined fonts and any "custom" fonts you have defined for the current document is displayed.

Step 3: Enter the desired font number or press F6 to display the Font Selector Definition Menu and create a new font.

After you have selected the font you want, the text you marked is modified.


Layout Font Edit

The following steps edit a previously defined font.

Step 1: Select Layout Font Edit.

Step 2: Select Current-Document to edit a font defined for the current document, or select New-Documents to edit a "default" font defined for any new documents that are created.

If you select Current-Document, a prompter containing all fonts defined for the current document is displayed. If you select New-Documents, a prompter containing fonts defined as defaults for all newly created documents is displayed.

Step 3: Enter the number of a font to edit, or enter an unused font number to define a new font. Press Enter.

The Font Selector Definition Menu is then displayed.

Step 4: Make the desired changes to the font definition. Then press F10.

You can change any settings on the font menu. At the Current font family setting, you can press F6 to see a list of available font families.

Any existing text in the current document that uses that font will now be changed to reflect the edits you made.
IMPORTANT: You must specify the font SmartWare uses for footnote reference numbers on the Document-Options menu. The default font for this purpose is font #1. If you alter the definition of font #1, or whichever font is specified in the document options, our footnote reference numbers may not work properly.


 Step 3: Specify which pages of the file you wish to print by entering the starting section and page number and ending section and page number.

You can specify the section and page number by entering either s#p# or s#.# where "s#" indicates the section number and "p#" or ".#" indicates the page number desired. To specify page numbers in the current section only, enter p# or #. To print the entire file, simply leave the defaults. in response to the section and page number prompts.


 Step 4: Select Destination.

Selecting Printer sends the file to the currently select printer. Selecting Disk puts a copy of the document or textfile, including printer control codes into a disk file. If you print the document to a disk file, SmartWare prompts you to enter a name for the file that will be created. You can assign any extension you desire for this file (i.e., prn). SmartWare does not automatically assign this file an extension. If you do not assign an extension, there will not be one attached to the file. Selecting Screen sends the document to the print previewer which allows you to view a document as it appears in the printed output.

Note that the pulldown menu dialog box only presents the Printer and Screen options.


Layout Font Pick-Up

This toggle command changes the "mode" used to determine which font will be used to insert new text. If the font pick-up mode is turned on, the font at the current cursor position is used for new text. This is particularly helpful when you are editing existing text and want the font of the new text to match the existing text.

If the font pick-up mode is turned off, the font displayed at the Font: prompt will be used for new text. This will be either font 0, or the last font selected with the Layout Font Select command.

If a number appears at the Font prompt, the pick-up mode is off. When the pick-up mode is on, an asterisk will appear at the prompt.

Executing Layout Font select when the pick-up mode is on will cancel the pick-up mode and new text will have the newly selected font.

You can specify the default font mode with the following setting on the Global Preferences menu.

     Font Pick-up Mode: On  Off

Ctrl-N is the quick key for toggling between font modes.


Layout Font Remove

The following steps explain how to delete a font definition.

Step 1: Select Layout Font Remove.

Step 2: Select Current-Document or New-Documents.

Current-Documents allows you to delete a font defined for the current document. New-Documents deletes a font from the default list you create.

A prompter appears containing fonts defined for the current document or for new documents. If you are editing fonts in the current document, an asterisk precedes any font that is unused in the current document. You cannot delete a font that is in use.

Step 3: Mark the font or fonts to be deleted.

Move the prompter arrow to the font you want to remove and press F6 to mark it for deletion. To mark all unused fonts, press F8. When the desired fonts are marked, press F10 or ENTER to delete the designated fonts.


Layout Bold Insert

To insert boldfacing for existing text:

Step 1: Select Layout Font Bold Insert.

Step 2: Mark the text you want to boldface. Press F10 or ENTER.

If you are using a color screen, the boldfaced text appears in a contrasting color. When positioned on a boldfaced character, the FN: indicator on the Status Line displays the font number for the character, followed by a B to signify boldface.


Layout Bold Remove

To remove boldfacing from existing text:

Step 1: Select Layout Font Bold Remove.

Step 2: Mark the text you wish to unbold. Press Enter or F10.


Layout Font Underscore

Layout Font Underscore is used to insert or remove underscoring for existing text. When Layout Font Underscore is selected, you must specify whether you want to insert or remove underscoring.


Layout Font Underscore Insert

To insert underscoring in existing text:

Step 1: Select Layout Font Underscore Insert.

Step 2: Mark the text you wish to underscore. Press Enter or F10.

If you are using a color screen, the underscored text appears in a contrasting color. When positioned on an underscored character, the FN: indicator on the Status Line displays the font number for the character, followed by a U to signify the character is underscored. If the character also appears in boldface type, a B is displayed between the font number and the U.


Layout Font Underscore Remove

To remove underscoring from existing text:

Step 1: Select Layout Font Underscore Remove.

Step 2: Mark the text you want affected. Press Enter or F10.


Layout Hidden-Text

Layout Hidden-Text allows you to hide specified areas of text when a document is displayed or printed. Whether or not hidden text appears, however, depends on the status of the Visible Hidden-Text command. If Visible Hidden-Text is toggled on, hidden text remains visible when the document is displayed or printed. If Visible Hidden-Text is toggled off, hidden text is not displayed or printed.
NOTE: When a document is saved, any hidden text contained in the document is temporarily "unhidden" as part of an internal operation by SmartWare. Therefore, if you have invisible hidden text containing section breaks or hard page breaks in the middle of a keep area, when the document is saved, the corresponding keep areas are permanently removed.

When Layout Hidden-Text is selected, you must specify whether you want to add or remove hidden text marks in your document.

Hidden Text, displaying
Hidden Text marks, displaying


Layout Hidden-Text Add

To specify text as hidden:

Step 1: Select Layout Hidden-Text Add.

Step 2: Mark the text you want to hide. Press F10 or Enter.

SmartWare inserts hidden text marks to designate the position in the document where the hidden text is located. These marks are displayed in your document only if the Visible Marks Hidden-Text command is toggled on. Consequently, if Document Visible Marks Hidden-Text is toggled off, the hidden text marks are not displayed.

When a block of text containing hidden text is copied or moved, the hidden text is preserved in the duplicated or moved text block, regardless of whether or not it is visible. However, if you split a hidden text entry while copying a block of text (a portion of the text and either the opening or closing hidden text mark are not included in the marked block), the hidden text is preserved in the original text, but is not contained in the duplicated text. If you split a hidden text entry while moving a block of text, the indicated text is moved to the new location, but the hidden text marks are not.

Copying Text
Moving Text


Layout Hidden-Text Remove

To remove hidden text marks from a specified section of text:

Step 1: Unhide either the text (Visible Hidden-Text) or hidden-text marks (Visible Marks Hidden-Text).

Step 2: Position the cursor in a hidden text area, or on a hidden text mark.

Step 3: Execute Layout Hidden-Text Remove.

The hidden text marks associated with this area of text are deleted, the text is redisplayed and the document reforms to compensate for the "inserted" text. If you attempt to remove hidden text without being positioned within the hidden text area or on a hidden text mark, the message Cursor is not positioned within hidden text marks. is displayed.

Hidden text may also be removed by positioning the cursor on a hidden text mark and pressing DEL.


Layout Keep

Layout Keep enables you to insert or remove "fences" around specified areas of text. This protects the text from being split by a section break or page break during document pagination. When you select Layout Keep, you must specify whether you want to insert "fences" around an area of text or remove existing "fences."

Keep Marks, displaying
Paginating Documents
Section Breaks


Layout Keep Insert

To create a Keep Area:

Step 1: Select Layout Keep Insert.

Step 2: Mark the text you want to keep together. Press Enter or F10.

If you have Keep marks are visible, a begin keep mark is inserted at position 0 on the line above the designated keep area and an end keep mark is inserted at position 0 on the line below the designated keep area.

To copy or move the text within a keep area and retain the keep controls associated with it, you must include both keep marks in the block you specify. Since the cursor cannot be positioned on a keep mark, you must set the anchor for the block on the line above the beginning keep mark and extend the block beyond the ending keep mark. When Edit Copy is executed, both the original block of text and the copied block of text are designated as keep areas. When the Edit Move command is executed, the keep marks are moved with the text.

If you fail to include one of the keep marks in the block you specify to copy or move the original block of text retains the keep controls, while the copied or moved block of text does not. If you do not include either of the keep marks in the block you specify to copy, the original block retains the keep controls and the copied block does not. If no text is left in the original keep area, a paragraph mark is inserted at the position where the moved text was originally located, retaining an empty, but controlled, keep area.

If a hard page break or a section break is part of a block of invisible hidden text inside a keep area, when you display the hidden text containing the page or section break, the keep area is eliminated, the keep marks denoting the keep area are removed, and the message Hidden text contained page/section break(s); 1 or more keep areas were removed. is displayed. Hidden text is redisplayed when:
*** the Document Visible Hidden-Text command is executed
** the hidden text marks are removed by executing Layout Hidden-Text Remove
** the hidden text marks are deleted using BACKSPACE, DEL, or Edit Delete.

In addition, when a document is saved, or when an Edit Copy, Edit Move, or Edit Delete command is executed, SmartWare temporarily displays hidden text as part of an internal operation. Therefore, after one of these editing operations, or after a document has been saved (either by executing File Save or via the Document Auto-Save feature), the keep areas that contained invisible hard page breaks or section breaks no longer exist.


Layout Keep Remove

To remove keep marks from a specified section of text:

Step 1: Position the cursor within the keep area.

Step 2: Execute Layout Keep Remove.

Layout Keep Remove cannot be used to remove the "fences" from only a portion of the protected text. To reduce the keep area, you must first execute Layout Keep Remove and then redefine the keep area by selecting Layout Keep Insert and marking the new area of text to protect. You can increase a keep area by inserting text between the keep marks.


Layout Newpage

Two types of page breaks, soft page breaks and hard page breaks, can be inserted in Word Processor documents. Page breaks can be inserted either automatically or manually; as you are typing text into a document, or after a document has been typed.


Layout Newpage Automatic

Layout Newpage Automatic is used to toggle on or off the automatic insertion of soft page breaks in the current document. If Layout Newpage Automatic is toggled on, page breaks are automatically inserted as you enter text in the document. The current page number is displayed on the Status Line at the bottom of the screen; this number changes as the cursor crosses page break boundaries.
NOTE: The default pagination for new documents is determined by a setting on the Word Processor Preferences menu, accessed by executing Tools Preferences Wordprocessor. Toggling automatic pagination on or off with Layout Newpage Automatic, overrides the default setting.

Soft page breaks appear as a solid line extending across the document window. The placement of soft page breaks in a document is determined by numerous settings on the Print Options Definition Menu. Things such as top and bottom boundaries, the use of headings and footings, and page size all affect pagination. Widow/orphan controls specified in the Current Document Options Definition Menu and any keep areas you have marked in the document also affect the placement of the page breaks. The Current Document Options Definition Menu is obtained by selecting the Layout Document-Options Current-Document command.

If automatic pagination is toggled on, SmartWare continually repaginates the document as you enter or delete text. This repagination is done in the background to interfere as little as possible with your work. In text entry mode, pagination will take place whenever you are not entering keystrokes. In command mode, pagination will take place when you are at the top menu level and no keyboard activity is taking place.

Pagination must complete before some commands, including Document Goto commands, Window Close, and Ctrl-E, can be executed. There may be a slight pause before execution of these commands until SmartWare finishes paginating the document.

If Layout Newpage Automatic is toggled off, no page breaks are inserted in the document until you either toggle on Layout Newpage Automatic, execute Layout Newpage Paginate, or manually insert hard page breaks using Layout Newpage Insert.


Layout Newpage Insert

You can force a page break at any point in your document by inserting a hard page break. Hard page breaks are inserted directly above the current line in a document by executing Layout Newpage Insert. They appear in the document as a single broken line extending across the Document Window. Hard page breaks are displayed in the document if Visible Newpage is toggled on.

If you have automatic pagination toggled on, and you insert a hard page break, the remainder of the document will repaginate.

Hard page breaks are not adjusted to compensate for any revisions you make to a document, such as inserting or deleting text. In addition, hard page breaks are not adjusted when you execute Layout Newpage Paginate.


Layout Newpage Paginate

If a document has been typed with automatic pagination off, soft page breaks can be inserted into the document by executing Layout Newpage Paginate. As with automatic pagination, the placement of the page breaks is determined by the definition items mentioned previously.
NOTE: If you use this method to paginate a document, and then modify the document, the soft page breaks that were inserted when Layout Newpage Paginate was executed are not adjusted to compensate for the revisions. To ensure that a revised document is correctly paginated, you must execute the Layout Newpage Paginate command after any editing is done.

If you have typed a document with automatic pagination toggled on, there is no need to paginate the document using Layout Newpage Paginate.

Print Options
Document Options
Keep Areas


Layout Newpage Remove

Layout Newpage Remove is used to delete a hard page break immediately above or below the current line. If Layout Newpage Automatic is toggled off, Layout Newpage Remove can also be used to remove soft page breaks in the document.


Layout Ruler

Layout Ruler is used to change the margin settings, indentions, tabs, text alignment, line spacing, or characters per inch (CPI) setting for document text. There are three types of rulers that control these settings. Table 9-11 briefly defines each ruler type.

Table 9-11

Default Ruler | The ruler that controls the format for new documents. Settings on the Default Ruler remain in affect unless the ruler is edited, or new rulers are inserted.
Current Ruler | The ruler that controls the format of the paragraph where the cursor currently sits.
Named Ruler | A specific ruler whose settings have been recorded and assigned a name for future use.


Default Ruler

When you begin with a blank document, the default ruler settings are displayed at the top of the Document Window. This ruler is called the Default Ruler. It controls all paragraphs in the document unless new rulers are inserted.

Settings on the Default Ruler are determined by settings on the Word Processor Preferences menu, which is displayed by executing Tools Preferences Wordprocessor. To change the defaults for all future documents, you must change the settings on this menu. You can change the defaults for the current document with Layout Ruler Edit Default. These changes affect only the current document.


Current Ruler

The ruler that controls the format of the current paragraph (where the cursor sits) is called the current ruler. As you move the cursor through paragraphs that have different formats, the ruler at the top of the window changes to display the settings controlling the current paragraph.

By inserting additional rulers in the document, you can have paragraphs of varying margins, justification or line spacing within the same document.


Named Rulers

You can assign names to specific ruler formats and save them for future use in this document. This eliminates the need to repeat the same ruler editing later. For example, if you commonly indent entire paragraphs within a document, you could insert a ruler once and then give this format a name. Named rulers are only available in the document in which they were created.

To name a ruler, select Layout Ruler Insert Current or Layout Ruler Edit and make any necessary changes to the settings, press F8 and enter a maximum of eight characters. The ruler name is then displayed on the Status Line next to the Ruler indicator.

The next time you want to use the same format, just place the cursor in the paragraph you want to change and select Layout Ruler Insert Named. A list of named rulers for this document will appear. Select the name of the format you want. You don't have to make individual changes to the ruler each time you use it.


Ruler Options

Many of the Layout Ruler command formats place the cursor on a Ruler Line and display a ruler menu in the Control Area of the screen, thus enabling you to modify the format of your text.


Text Alignments

The first position on the Ruler Line indicates the alignment of text within the right and left margins. There are four different options. These options are explained in Table 9-12.

Table 9-12

Option | Alignment | Definition
l | left-aligned | Text is aligned flush with the left margin.
r | right-aligned | Text is aligned flush with the right margin.
j | justified | Text is block aligned on both margins.
c | centered | Text is centered between margins.

To change the alignment of a paragraph, move the cursor to the first position of the ruler and type over the letter there with one of the other options.


Line Spacing

The second and third positions on the Ruler Line specify the vertical line spacing for the text. To change the line spacing, enter a number in the second position. Typing 2 specifies double spacing, 3 specifies triple spacing, and so forth.

Half-spacing is specified by entering + in the third position on the Ruler Line. For example, entering 1+ in the second and third positions specifies 1-1/2 line spacing; entering 2+ specifies 2-1/2 line spacing and so forth. To remove half-spacing, press DEL to delete the + or type over the + with a -.

Any number from 0 through 9 can be entered in the second position. However, an entry of 0 in the second position is accepted only if + has been entered in the third position.


Margins

Margins are depicted on the ruler as brackets. The left margin is indicated by [ and the right margin is indicated by ]. To change a margin setting, use cursor keys to move to the new margin location and type the appropriate bracket.


Indents and Outdents

Indent settings are displayed on the ruler as the letter i. If it is a capital I, it indicates the indent shares the same position as a tab mark.

You can specify an indent or outdent on the ruler. Both affect the first line of each paragraph controlled by the ruler. An indent moves the first line of text a specified distance inside the margins. An outdent allows the first line to extend the specified distance beyond the left margin.

To place an indent or an outdent on the ruler, move the cursor to the desired location and press i.


Tabs

Normal tabs and decimal tabs can be specified on the Ruler Line. Normal tabs are indicated on the ruler by [ntab]. Decimal tabs are indicated on the ruler by [dtab].

Decimal tabs are used during numeric entry to create columns of numbers with aligned decimal points. When Tab is pressed to move the cursor to a decimal tab, any entered text or digits are pushed to the left until a decimal point is entered. Thereafter, text or numbers are entered to the right of the decimal point.

Several methods can be used to change tab settings on the Ruler Line; the best method to use depends on what changes you want to make. If you want to remove one or two tab stops, move the cursor to the tab you want to remove and press DEL. If you want to remove all of the displayed tabs and establish new tab stops, press F6 to clear all the current tab settings. Then move to the first location where you want a tab and press F3. Repeat this procedure to set all the normal tabs desired. To set a decimal tab, follow the same procedure, but press F4 instead of F3.

You can also enter a series of incremented tabs on the Ruler Line.

Step 1: Press F5.

Step 2: Select Normal or Decimal to specify what type of tabs you want.

Enter tab increment (inches): appears.

Step 3: Enter a number, in inches, to designate how much space you want to separate the tabs, and press Enter.

The incremented tabs are then displayed on the Ruler Line, between the current margins.


Characters Per Inch

Any ruler division from 4 to 24 can be entered for a SmartWare Word Processor ruler. The default division (characters per inch) setting is 10. When 10 cpi is used, 10 ruler division marks (tics) are required to equal 1 inch. Therefore, if the cursor is located on ruler division 10 when a 10 cpi setting is being used, the position identifier at the bottom of the screen registers 1.0, indicating you are 1 inch from the left edge of the ruler.

To change the cpi setting, press F7, enter the desired ruler division and press Enter. The new ruler division is displayed at the bottom of the screen next to the Ruler Division(cpi): identifier and the Pos: indicator changes to reflect the new measurement. For example, if the cursor is located on ruler division 10 when a cpi setting of 15 is being used, the Pos: indicator registers 0.67.


Name Format

The F8 Name Format option is available whenever Layout Ruler Insert Current or Layout Ruler Edit is selected. Using this option, you can assign a name to a ruler format. See the previous discussion in this section on naming rulers for more information.


Change All

The F9 Change All option is available whenever the Layout Ruler Reformat command is selected. Using this option, you can change all the format settings for all the paragraphs in a specified area of your document, to the format settings of the Current Ruler.


Layout Ruler Insert

Layout Ruler Insert is used to change the settings for a single paragraph. To do this, you must insert a ruler above the paragraph. You can insert the default ruler, a named ruler or the current ruler.


 If you select the Default or Named options the ruler is placed above the current paragraph and the paragraph reforms to reflect the ruler's settings.


 If you select the Current option, the ruler is placed above the current paragraph, the cursor is placed on the ruler line, and you are allowed to make any desired changes. After making all desired changes, press F10. The text reforms, the new ruler is inserted above the paragraph, and a copy of the ruler that previously controlled this paragraph is inserted below it.

The Quick Key Alt-J can also be used to change the alignment of a single paragraph. It displays the prompt Enter new alignment (j/l/r/c): on the command line. Enter j to justify, l to left align, r to right align, or c to center the current paragraph.


Layout Ruler Edit

Layout Ruler Edit is used to change the format settings for all of the paragraphs controlled by the ruler being edited. When the command is selected, you must specify whether you want to edit the Current Ruler, the Default Ruler, or a Named Ruler.

After specifying which ruler you want to edit, the cursor is moved to the ruler line and you can make any changes you desire.

Once all desired changes have been made to the ruler, press F10 or Enter. If you edited the Current Ruler, all paragraphs controlled by the ruler are reformatted. If you edited the Default or a Named Ruler, no changes are made to any existing paragraphs controlled by either of these rulers. Instead, the template for the edited ruler has been changed. The changes will appear the next time the ruler is used.


Layout Ruler Reformat

The Layout Ruler Reformat command is used to change the format settings for multiple paragraphs in a document, regardless of which ruler controls them. When the command is selected, SmartWare enters block-marking mode and displays the marking menu.


 Mark the portion of the document you want to be affected by the ruler changes. You can highlight as much of your document as desired.
NOTE: A paragraph is considered "marked" even if only a single character in the paragraph is included in the block

When all the paragraphs you want affected by the ruler changes have been marked, press F10 or Enter.

A copy of the Current Ruler is then placed above the first paragraph in the marked block, and the editing menu is displayed. In addition, the Status Line changes to reflect the ruler name (or ruler type, if it is not a Named Ruler), the current cursor position on the ruler, and the ruler division (cpi) of the ruler.

You can then change any of the ruler settings. For specific information about changing individual settings, see the previous discussion of Ruler Settings in this chapter.

Changing All Settings

The F9 Change All option is available on the ruler editing menu whenever Layout Ruler Reformat is chosen. This option enables you to change ALL the format settings for all paragraphs in the marked block.

For example, if you mark a block of text that extends across four different rulers, and change the tab settings, only the new tab settings will be reflected on all the rulers unless you press F9. Each ruler will keep its old line spacing, text alignment and margin settings. However, if you press F9, all four rulers will change to have the same margins, line spacing, alignment, etc., as the ruler you just edited.

Press F10 or Enter to record the changes to the current ruler. If you pressed F9, the "subordinate" rulers in the marked block are removed and the text in the marked block is reformatted to match the settings on the current ruler. If you did not press F9, the changes you made are reflected on each ruler in the marked block and the text reformats as necessary.

If only a portion of the text controlled by a ruler was included in the marked block, a copy of the original ruler, containing the settings before the changes were made, is inserted below the last reformatted paragraph.


Layout Ruler Delete

When the Layout Ruler Delete command is selected, you must specify whether you want to delete the Current Ruler, or a Named Ruler.


Layout Ruler Delete Current

Layout Ruler Delete Current deletes the ruler controlling the current paragraph. When the command is executed, all of the paragraphs controlled by the ruler are reformatted to conform to the settings of the preceding ruler.


Layout Ruler Delete Named

Layout Ruler Delete Named deletes a named ruler format that was previously defined for the current document. When the command is selected, SmartWare prompts Enter format name: and displays a prompter listing all the format names assigned to rulers in the current document. Specify the ruler format to delete and press F10 or ENTER to execute the command.

The deletion of a named ruler format has no effect on any existing text that is controlled by a ruler assigned this format name. The ruler format is simply a "template" that is saved with the current document.


Layout Section

Layout Section is used to subdivide a document into two or more separate sections. By "sectioning" a document, Print Option items can be different for each section. For example, page numbering can be changed in the middle of a document, or different paper path can be specified to allow for the use of different types of paper during the printing of a document. In addition, different headings, footings, page number styles, or top and bottom boundaries can be specified for each section of a document.


Layout Section Insert

Layout Section Insert is used to insert a section break at the cursor position. If Visible Newpage is toggled on, a section break appears as two solid lines across the width of the Document Window.

The number of the current section is displayed on the Status Line beside the Sc: indicator.

To obtain new Print Option settings for the new section, position the cursor anywhere within the new section, select the Print Options command, and specify the changes desired. Refer to the Print Options command for information on available settings.


Layout Section Remove

Layout Section Remove is used to delete a section break. Position the cursor on the line directly above or below the section break before selecting the command. When a section break is removed, the text contained in the deleted section becomes a part of the section preceding it.


Layout Section Move

Layout Section Move is used to move an entire section of a document from one location in the document to another. To move a section:

Step 1: Select Layout Section Move.

Step 2: Enter the number of the section you wish to move.

You can type in a number or move the cursor in the document until it is in the section you want to move. Then press Enter.


 Step 3: Enter the number of the destination section.

When you move a section, it is inserted into the document in front of the destination section. Therefore, you must enter the number of the section you want to immediately follow the moved section.

For example, if you have a 4 section document, and want to move section 2 to the end of the document, you must enter the number 5 or end as your destination. If you enter 4, section 2 is placed in front of section 4, thereby becoming section 3.


Print Commands

The Word Processor's Print commands allow you to output the documents you have created to a printer.


Print Options

Print provides the following options:

Document. Provides printing of document files and textfiles.
View. Sends the document to the print previewer which allows you to view a document as it appears in the printed output.
Merge. Provides merging of an input file information with document files.
Options. Controls the formatting options for printing the current document.
Preset. Controls the formatting options for printing new documents.


Step 1: Select Draft or Enhanced.

If you have included graphics or SmartWare-generated filled-area fonts in your document, select Enhanced. If you don't need these features, and want to print at the fastest speed, select Draft.


 Step 2: Enter the number of copies you want.


Print View

Print Preview

The Print View command enables you to view printed documents and text files on the screen. This feature allows you to view items without printing, letting you see the what the end results are without printing.


Print Merge

The Print Merge command is used to print the combined text of two files: a template file containing merge variables, and an input file containing replacement data for those merge variables. When Print Merge is executed, the input file data is merged into the template file, replacing the merge variables.

For example, you can put the variables "name", "address", "city", "state", and "zipcode" into a template document. This file can then be merged interactively or automatically. An interactive merge prompts you to enter replacement strings for each variable before the letter is printed. An automatic merge uses strings in a textfile to replace the variables in the template document. This textfile can be one you create yourself, or one created in the Data Base which contains a field for each one of the variables.

The results of a merge can be output either to a printer or to a file. This powerful SmartWare feature makes creating and printing form letters quick and easy.


Merge Variables

Replacement variables and formula variables may be entered into the template document. Each template document can contain a maximum of 100 replacement variables, and an unlimited number of formula variables.


Replacement Variables

Replacement variables are character strings, such as "Name", "Address", "Phone", or "Product Name". These variables are not case sensitive. Therefore, the variables "Name", "name", and "NAME" are all considered identical during a merge.


Formula Variables

Formula variables are indicated by entering an equal sign (=) as the first character immediately following the merge start character.

When a formula variable is encountered during a merge print, the formula is calculated and the result replaces the variable in the template document. Every formula variable is individually recalculated; three occurrences of the same formula generate three separate recalculations.

Formula variables can use the standard SmartWare functions, but they cannot reference other replacement or formula variables. Syntax error messages are not provided. Variables from project-processing programs can be included in the formula variable.


Creating the Template File

To begin a merge print, you must first create the template file containing the merge variables. To enter a merge variable into a document:

Step 1: Position the cursor where you want the merge variable.

Step 2: Press Ctrl-J to insert a start merge character into the document.

The Quick Keys used to insert start and end merge characters can only be used while in Text Entry mode.

Step 3: Type in the variable name.

Each merge variable may contain from 1 to 50 characters. If you are going to be merging with a file from the database, the variable name must be the same as the name of the field that contains the replacement information.

Step 4: Press Ctrl-K to insert an end merge character in the document.

Step 5: Repeat this process until all your variables are entered.

The template document is now ready to be print merged interactively, or you can create an input file if you want to do an automatic merge.


Print Merge Screen

The following steps explain how to do an interactive print merge.

Step 1: Load the template document containing the merge variables.

Step 2: Select the Print Merge command.

Step 3: Select the Screen option.

Selecting Screen tells SmartWare that the replacement information is to be received from the Screen rather than from an input file.


 Step 4: Select Draft, Enhanced, or WP-Document.

If you have included graphics or SmartWare-generated filled-area fonts in your document, select Enhanced. If you want faster printing, without these features, select Draft.

WP-Document will create a series of editable Word Processor document files retaining all font and ruler information. If you want to create merge documents that you will need to edit later, select this option. A separate document file will be created for each set of replacement data. These documents will be placed in the data directory and named according to the following convention.

The first 5 letters of the file name will be taken from the template document. The last three letters are replaced with a number beginning with 000 and incremented by one for each data set. The newly created files are given the extension .WMD (Word Processor Merged Document).

For example, if you merge 5 sets of data with the template document "mymerge.doc" the data directory will contain the files: mymer000.wmd, mymer001.wmd, mymer002.wmd, mymer003.wmd, and mymer004.wmd.

If you select this option, you will skip steps 5 and 6.


 Step 5: Select Printer or File.

If you specify File, the merged documents will be saved to a disk file for later use. You will be prompted to enter a name for the disk file that will be created. If you select Printer, each merged document will be sent to the printer as it is completed.
IMPORTANT: When the file is written to disk, it will contain printer control codes. This allows it to be printed quickly and easily later. It can even be printed from DOS. If you will be editing this disk file later, use the WP-Document option discussed in the previous step.

Step 6: Enter the number of copies you want of each merged document.

A screen listing all replacement variables in the document appears. Formula variables do not appear on the screen, but will be calculated as the merge is done.

Step 7: Type in the replacement string you want for each variable.

If you make a mistake while typing in a replacement string, press F8 to clear the current variable and start over. You can press F3 to clear all the variables for this document.

When you have finished entering all replacement strings for one document, press F2. The document is then sent to the printer or to the disk file.

Step 8: Press F3 to blank all the variables, and enter replacement strings for the next document.

Step 9: Repeat this process until you have printed all necessary documents.

Step 10: Press F10 to complete the merge process and return to your template document.

The Input File

In order to do an automatic print merge, you must have an input file that provides the replacement strings for each variable. This input file is just a specially-formatted textfile and can be created in SmartWare Word Processor. Or, data stored in SmartWare Database can be sent to SmartWare Word Processor to create an input file. More information about merge printing with Data Base information is provided later in this chapter.

A valid merge input file must satisfy the following conditions:
*** The input file must be either a Smart textfile or an ASCII textfile produced with a text editor.
** The input file must consist of one or more lines of text, each line containing from 0 to 1025 characters, followed by a carriage return/line feed pair. (A carriage return/line feed pair is produced when ENTER is pressed.)
** Each replacement string in the input file must be surrounded by either single (') or double (") quotation marks.
** The first line of the input file must be a list of the merge replacement variable strings used in the template document. If the same merge variable appears more than once in your template document, it only needs to appear once in your input file. For example, if you wish to insert a client's name in three places in a letter, you would put "Name" in those three locations in the template file. However "Name" only has to appear once in the input file. Formula variables should not be included in the input file.

For an example, consider the content of the following input file.

     "First name" "Last Name" "Address" "Title" "Phone"
     "John" "Doe" "123 4th Street, Wichita, KS" "Manager" "(316)462-6621"
     "Debbie" "Baker" "46 Bell, Lewiston, ME" "Manager" "(207)769-5525"

The first row in the file shows that the variables First name, Last name, Address, Title and Phone will be found in the template file. Each of the following lines is a set of replacement strings for those variables. The first letter will be addressed to John Doe, and the next copy of the letter will be addressed to Debbie Baker.

A "line" of text can extend across more than one line if the line continuation character (\) is used. For example, the following are all valid input file entries:

Example:

     "First name" "Last Name" "Address" "Title" "Phone"
     "John" "Doe" "123 4th Street, Wichita, KS" "Manager" "(316)462-6621"
     "Debbie" "Baker" "46 Bell, Lewiston, ME" "Manager" "(207)769-5525"

     "First name" "Last Name" \
     "Address" \
     "Phone"
     "John" "Doe" \
     "123 4th Street, Wichita, KS" \
     "(316)462-6621"
     "Debbie" "Baker" \
     "46 Bell, Lewiston, ME" \
     "(207)769-5525"

     "First name" "Last Name" "Address" \
     "Title" "Phone"
     "John" "Doe" "123 4th Street, Wichita, KS" \
     "Manager" "(316)462-6621"
     "Debbie" "Baker" "46 Bell, Lewiston, ME" \
     "Manager" "(207)769-5525"


Print Merge File

The following steps explain how to do an automatic merge.

Step 1: Load the template document containing the merge variables.

Step 2: Select the Print Merge command.

Step 3: Select the File option.

Selecting File tells SmartWare that the replacement information is to be received from an input file rather than from interactive input.


 Step 4: Select Draft, Enhanced, or WP-Document.

If you have included graphics or SmartWare-generated filled-area fonts in your document, select Enhanced. If you want faster printing, without these features, select Draft.

WP-Document will create a series of editable Word Processor document files retaining all font and ruler information. If you want to create merge documents that you will need to edit later, select this option. A separate document file will be created for each set of replacement data. These documents will be placed in the data directory and named according to the following convention.

The first 5 letters of the file name will be taken from the template document. The last three letters are replaced with a number beginning with 000 and incremented by one for each data set. The newly created files are given the extension .WMD (Word Processor Merged Document).

For example, if you merge 5 sets of data with the template document "mymerge.doc" the data directory will contain the files: mymer000.wmd, mymer001.wmd, mymer002.wmd, mymer003.wmd, and mymer004.wmd.

If you select this option, you will skip steps 6 and 7.


 Step 5: Enter the name of the input file.

Either select the file from the file prompter, or type in the filename, including extension.


 Step 6: Select Printer or File.

If you specify File, the merged documents will be saved to a disk file for later use. You will be prompted to enter a name for the disk file that will be created. If you select Printer, each merged document will be sent to the printer as it is completed.
IMPORTANT: When the file is written to disk, it will contain printer control codes. This allows it to be printed quickly and easily later. It can even be printed from DOS. If you will be editing this disk file later, use the WP-Document option discussed in Step 4.

Step 7: Enter the number of copies you want of each merged document.

Copies of the letter will be printed until each set of replacement strings have been used.

Merging Database Information

An input file can also be created by extracting information from fields in a SmartWare Database file. Before doing this, you must decide how you will be using this data. If you will only be using it for one print merge, and then never need the data again, you should use Data Send to extract the information. If you will need to use the exact same information multiple times, you must use File Export to extract the data. The following steps take you through both procedures.


Graph View File

Graph View File displays a graph stored on disk. This command is frequently used to view a graph before inserting it into a document. When you select Graph View File, a prompter containing the filenames of all metafiles in the current data path and the prompt Enter the graph name: are displayed. Type the name of the graph file you want to view, or select it from the prompter. To view the last graph sent to SmartWare Word Processor simply press ENTER when the pointer is selecting [default].

When a graph file is selected, the Document Window is temporarily displaced and the graph is drawn on the screen. Press any key to return to the Document Window.


The Data Send Method

Step 1: Enter SmartWare Database.

Step 2: Load the Database file containing the records you need.

Step 3: Select Data Send Wordprocessor Data.

A prompter displaying all available fields is displayed.

Step 4: Use F6 to highlight the fields you want. Then press F10.

Step 5: Enter the name of a project file to be executed after the data is sent to the Word Processor. Press ENTER if no project file is needed.

The data in the selected fields is taken from each record and placed in the input file format. You automatically leave the Database and enter the Word Processor. The screen will be blank. The data sent over from the Data Base is in a temporary file that does not appear on the screen.

Step 6: Load the template document containing the merge variables.

Step 7: Select Print Merge File

Step 8: Select Draft or Enhanced.

If you have included graphics or SmartWare-generated filled-area fonts in your document, select Enhanced. If you want faster printing, without these features, select Draft.

Step 9: When prompted for the input file, simply press ENTER to select the word default.

Step 10: Select Printer or File.

Once you leave the Word Processor, the temporary file you created is erased and cannot be used again.


The File Export Method

Step 1: Enter SmartWare Database.

Step 2: Load the Database file containing the records you need.

Step 3: Select File Export Smart Row-Column.

A prompter displaying all available fields is displayed.

Step 4: Use F6 to highlight the fields you want. Then press F10.

Step 5: Enter a name for the input file this command will create.

The input file will then be created. You must manually leave the Database and enter the Word Processor. Then proceed just like you would with any other input file.


Print Options

Select the Print Options command to display the Current Print Options menu. On this menu are a number of settings that control how your document is printed. These settings affect only the document that was current when Print Options was specified.

You can set up default values for each of these settings by executing Print Preset. This command displays the exact same menu as Print Options. Instead of being tied to the current document however, these settings are attached to all newly created documents. When you create a new document, the values from the Print Preset menu are copied into the Current Print Options menu for that document. If you need to make any changes to these default settings, select Print Options and edit the settings as necessary.

Following is a detailed discussion of options on the Print Options and Print Preset menus.


Headings and Footings

You can specify headings or footings to be printed on some or all pages of your document. The first group of settings on the Print Options menu specifies heading information and the second group specifies footing information. The settings used to specify headers and footers are very similar, so they are discussed together here.


Print Heading/Footing On

Specify which pages of the current section will have printed headings or footings. You can choose to have the headings or footings printed on:
*** all pages of the section
** only the first page on the section
** on all pages except the first page of the section.


Blank Lines after Heading/Footing.

Enter a number between 0 and 3 to specify the number of blank lines that separate the heading from the first line of document text or the footing from the last line of text. Enter a number between 0 and 3.


Use Secondary Heading/Footing

Two types of headings or footings are available: primary and secondary. If you select No, the primary heading or footing is printed on all chosen pages. If you specify Yes, primary headings or footings are printed on odd-numbered pages, and secondary headings or footings are printed on even-numbered pages.


Primary and Secondary Headings/Footings

A maximum of five lines of text can be specified for each type of heading or footing. You may enter up to 255 characters (including control codes and printable characters) for each line. A line is printed if it is not blank or if there is a non-blank line that follows it. If you leave lines one and two blank, and enter text on line three, your heading will consist of two blank lines and one line of text.


Print Control Codes

Print Control codes are special character sequences that can be specified in the headings or footings of a document. The codes are used to control the alignment of information, or are replaced by current data, such as date, time, or page number. The following table lists the printer control codes.

Control Code | Description
%L | Left aligns the text immediately following the control code until a different print control code is encountered, or until the end of the current line.
%C | Centers text the text immediately following the control code until a different print control code is encountered, or until the end of the current line.
%R | Right aligns the text immediately following the control code until a different print control code is encountered, or until the end of the current line.
%P | Replaces the control code with the page number.
%D | Replaces the control code with the current date.
%T | Replaces the control code with the current time.
%F | Replaces the control code with the name of the file being printed.
%[#] | Specifies a font for the text immediately following the control code.(# must be a valid font number.) The font number must be surrounded by brackets and can be followed by B or U to boldface or underscore text.
%S | Replaces the control code with a section number (where "S" is the section number).

Control codes can be used in any combination, with more than one control code appearing on a line. Control codes do not appear in the printed document. Do not separate the control codes from literal information with blank spaces unless you want the blank space printed in your document.

Following are examples of two Print Control Code strings that could be entered as headers or footers and an illustration of the results they would achieve.

Example:
     %L@_@%F@_@%C-%P-%R@_@%D

     filename.ext               -10-                   11-14-90

%L@_@%F causes the name of the current file to be printed at the left margin. %C-%P- causes the current page number to be centered on the line between two dashes. %R@_@%D causes the current date to be printed at the right margin.

Example:
     %LQuarterly Report%CACME Shoes%R3rd Quarter

     Quarterly Report          ACME Shoes             3rd Quarter

%LQuarterly Report causes the text Quarterly Report to be printed at the left margin. %CACME Shoes causes the text ACME Shoes to be centered on the line. %R3rd Quarter causes the text 3rd Quarter to be printed at the right margin.

Primary and secondary headings or footings are allocated equal space on the printed page, even when they are not the same length. The heading or footing requiring the greater number of lines determines the space allocated for both.


Example

The following steps show how to print a heading on every other page.

Step 1: Select All-pages for the Print Heading On: option.

Step 2: Specify Yes to the Use secondary heading option.

Step 3: Leave either the primary or the secondary heading blank.

Depending on the heading you have left blank, headings will be printed on all even pages or all odd pages only.


Page Number Style

If you use the %P print control code to insert the current page number in a header or footer you must specify the how you want that number printed. Select Arabic, Roman-Small (lowercase roman numerals), or Roman-Caps (uppercase roman numerals.)


Lines to Enclose Document

Select None to have no lines enclose document text. Single or Double will place a single or double line below the heading and above the footing, enclosing the document text.


Blank Lines Before or After Enclosing Lines

If you enclose your document with lines, you can specify up to three blank lines to be placed after the top enclosing line or before the bottom enclosing line. Enter the number of blank lines you want before or after the appropriate enclosing line.,


Start Page Number

If you use the %P print control code to insert the current page number in a header or footer, you must enter the page number the current section will start with. Entering a 0 for the start page number instructs SmartWare to add one number to the last page number in the previous section. Careful use of the start page number can control which headers or footers print on which page.


Lines Per Inch

Select 6 or 8 for the number of lines per inch.


Paper Profile

A Paper Profile is made up of the page size and paper path you want to use to print a file. The paper path tells SmartWare where the printer will find the paper for this job, and how it will move it through the printer. For example, you can specify the use of a tractor feed, or manual feed; choose between several paper trays; or specify the use of an envelope or single sheet feeder. Page size tells SmartWare whether you will be printing an 8-1/2 by 11 inch page, an envelope or a custom page size.

This paper profile will control printing of documents and textfiles from within the Word Processor. Printing in the Spreadsheet and Data Base Reports is controlled by Paper Profile settings within each module. Printing from editors, such as the Text-Editor, non-report Database printing, and printing through Project Processing is controlled by the default paper profile on the Hardware Preferences menu.

The following steps explain how to select a paper profile.

Step 1: With the cursor on Paper Profile, press F6.

A two-column, pop-up box is displayed listing available paper paths and sizes. Paths that are appropriate for the current printer are highlighted. As you move the arrow down the list of paths, the appropriate paper sizes for that path are highlighted.

Notice that one path and one paper size are marked by an asterisk. This indicates that these are the default path and paper size as listed in the current descriptor file which you selected on the Hardware Preferences menu.

SmartWare gets information about appropriate selections and the default path and page size from the currently selected printer descriptor file. If you wish to change the default settings, or if you know your printer supports a particular path or size that is not highlighted, you may want to edit the appropriate descriptor file. Read Chapter 8: Editing Descriptor Files in Software System Manual for more information.

Step 2: Use Up-Arrow or Down-Arrow to move the pointer through the path selections. When the arrow points to the appropriate path, press ENTER or Right-Arrow.

To select the default path and paper size, move the arrow to the word DESCRIPTOR at the bottom of the box. To select the same settings you specified on the Hardware Preferences menu, move the arrow to PREFERENCES at the bottom of the screen. If you point to either of these words, the path and page size they represent are highlighted as a reminder.

If you set the paper profiles within each module to the PREFERENCES selection, you can change all the profiles by making changes in one place, the Hardware Preferences menu.

If you do not wish to select DESCRIPTOR or PREFERENCES, select a highlighted path. The arrow then moves to the Page Size column.

Step 3: Select one of the highlighted sizes and press ENTER.

If you select Custom in the SIZE column, a prompt is displayed on the command line. Enter the width and length of the custom paper size in inches. For example, you might enter 7.5 x 9.5 inches. The two dimensions must be separated by a space or "x".

You are returned to the Print Options screen and you selections appear, separated by a comma, at the Paper Profile: prompt. If you select a size or path that is not supported by the current printer, a warning message will be generated when you execute a Print command. You can abandon printing and change to a more appropriate profile, or continue. If you continue the print job, the printer will try to us the same page size, with a different path. If this is still not valid, the "default" profile specified in the printer descriptor will be used.


Orientation

Select Portrait to print the document across the width, or horizontal side, of the page. Select Landscape to print the document "sideways", across the length, or vertical side, of the page. Landscape printing can only be accomplished if your printer supports it.


Use Secondary Borders

Select Yes to be able to set different borders, or margins for even numbered pages in your document. The size of secondary borders are controlled by settings at the Page Border option. Select No if you want odd and even pages to have the same borders.


Page Borders

The Page Border is the margin or amount of white space between the edge of the page and the document text. Some printers, particularly laser printers have "preset hard margins". Your page borders must be wider than the preset hard margins.

Specify a top and bottom margin in inches. Under the Primary option, specify left and right margins in inches. These boundaries will apply to all pages if you have specified no secondary boundaries, or odd numbered pages if you have specified secondary boundaries.

If you selected Yes for the Use of secondary pages you must also specify left and right margins for even pages.


Section Print Options

If you have divided your document into two or more sections, different Print Options can be set for each section. This gives you the flexibility to change paper profiles, headings, footings, numbering styles, or page borders at each section.

To view or edit the print options for a particular section, place the cursor in the section and select Print Options. The title at the top of the menu should reflect the section you are setting options for.

Many times, you may only want to change one or two options from one section to the next. To keep you from having to re-enter all the settings you want to keep the same, you can copy those settings from one section to the next. Press F6 and SmartWare displays the prompt Enter the number of the section to be copied:. Enter the section number for which you have already specified print options. All those print option settings are then copied into the current section's print options menu. You can then change only the settings you need to.


Print Preset

Print Preset is used to specify default print option settings for new documents. Selection of the Print Preset command invokes the display of the Preset Document Definition Menu. This menu contains the same specification items as those found in the Current Print Options Definition Menu; refer to the discussion above for information concerning each specification item.


Graph Commands

The Graph keyword enables graphs that have been created in SmartWare Spreadsheet to be inserted in SmartWare Word Processor documents. Before any Word Processor Graph command can be executed, a graph metafile must have been created and saved in SmartWare Spreadsheet. A graph metafile is identified by the .cgm extension.
NOTE: You may wish to refer to Spreadsheet Manual for more information about creating and editing graphs.


Graph Options

Graph provides the following options:

Insert. Inserts a graph at the current position in the document.
Remove. Removes the current graph from the document.
View. Displays a graph on the screen, temporarily displacing the Document Window.


Graph Insert

The following steps explain how to insert a graph in the current document.

Step 1: Position the cursor on the line in your document where you want the graph to start.

Step 2: Select Graph Insert.

A prompter list of all graph metafiles (.cgm) in the current directory are displayed. Select the graph you wish to insert. If it is in another directory, enter the entire path. If you used the Spreadsheet's Sheet Send Wordprocessor Graphics command to "send" the graph to the Word Processor, you can press Enter to select the "default" graphics file. This causes the last metafile sent from the Spreadsheet to be inserted at the cursor position.


 Step 3: Specify the size and alignment you want for the graph.

Large, medium, or small graphs can be inserted in a document. A large graph extends from the left margin to the right margin. A medium graph extends from either the left or right margin to the middle of the page. A small graph extends from either the left or right margin across one-third of the page. When a medium or small graph size is selected, you must specify whether you want the graph aligned on the left margin or the right margin.

After the graph's size and alignment are selected, a shaded block containing the graph screen filename is inserted into the document at the location specified. Any text that previously occupied the space now occupied by the graph is automatically reformed to surround the graph.

SmartWare Word Processor does not display the actual graph in the document. In addition, due to the size of the display screen, if a large-sized graph is inserted into a document, the shaded block representing the graph is not displayed in its true size. However, the actual graph is printed in the document at print time or can be viewed with the print previewer.
NOTE: You are not required to send the graphic to the Word Processor. Graph Insert will find any metafile in the current data path. However, if you do send the graphic from the Spreadsheet, SmartWare automatically leaves the Spreadsheet, loads the Word Processor and makes the graph you just sent the default graph to be inserted.


Graph Remove

Graph Remove deletes a graph from a document. To delete a small or medium graph, position the cursor in the text adjacent to it before selecting Graph Remove. To delete a large graph, position the cursor on the line directly above or below the graph before selecting Graph Remove.

If you have two graphs in a document separated by a single line and you position the cursor on the line between the graphs before executing Graph Remove, the graph above the cursor is removed.

When Graph Remove is executed, the shaded area in the document that represents the graph is erased and the text is adjusted to compensate for the blank space.


Graph View

Graph View displays a graph that has been inserted into a document or that is resident on disk. When Graph View is selected, the options Document and File is displayed.


Graph View Document

Graph View Document displays the graph at the current cursor position. When Graph View Document is selected, the Document Window is temporarily displaced and the graph is drawn on the screen. Press any key to return to the Document Window.


Graph Convert

The Graph Convert Bmp-To-Cgm and Cgm-To-Bmp commands convert graphic files to and from bitmap and CGM formats.

When you select one of these commands, a prompter containing the possible source filenames in the current path is displayed. Select a file or enter a name at the prompt. Following this you are prompted for the destination filename.

Converting from CGM to BMP format also requests a bitmap width and height; 640x480 is a common screen size. Note that the value for height is an optional entry since it can be calculated by ANGOSS.


Graph From-Clipboard

The following steps explain how to insert a graph in the current document from the clipboard.

Step 1: Position the cursor on the line in your document where you want the graph to start.

Step 2: Select Graph From-Clipboard.


 Step 3: Specify the size and alignment you want for the clipboard graphic.

Large, medium, or small graphics can be inserted in a document. A large graphic extends from the left margin to the right margin. A medium graphic extends from either the left or right margin to the middle of the page. A small graphic extends from either the left or right margin across one-third of the page. When a medium or small graphic size is selected, you must specify whether you want the graphic aligned on the left margin or the right margin.

After the graphic's size and alignment are selected, a shaded block containing the graphic screen filename is inserted into the document at the location specified. Any text that previously occupied the space now occupied by the graphic is automatically reformed to surround the graphic.

SmartWare Word Processor does not display the actual graphic in the document. In addition, due to the size of the display screen, if a large-sized graphic is inserted into a document, the shaded block representing the graphic is not displayed in its true size. However, the actual graphic is printed in the document at print time or can be viewed with the print previewer.


Tools Commands

The Tools command keyword provides various file manipulation capabilities. You can:
** copy, erase, print, or rename files
** manipulate directories
** operate the calculator program
** set preferences for global, Word Processor, or hardware parameters.

Only the Tools Preferences Wordprocessor options are discussed here. Refer to the Tools command discussion in Chapter 13 of Software System Manual for detailed information regarding the other Tools commands.


Tools Preferences

The Tools Preferences commands are used to configure default settings. When you select Tools Preferences, specify whether you want to set Global, Wordprocessor, or Hardware defaults. For information on the Global and Hardware options, refer to Chapter 13 of Software System Manual.


Tools Preferences Wordprocessor

Selection of the Tools Preferences Wordprocessor command displays a definition menu containing settings that control how SmartWare Word Processor performs whenever it is accessed. Any changes that you make to the specifications in the Word Processor Preferences Definition Menu become the performance defaults the next time you enter SmartWare Word Processor. With the exception of changes made to the Default Paragraph Format items, and the Miscellaneous Items that control module entry performance, any changes made via Tools Preferences Wordprocessor become the defaults for the current session.

Each definition menu item is discussed in detail below.


Pagination Options

This definition item determines whether or not SmartWare automatically inserts page breaks into a document. If you select Manual, no page breaks will appear in a document unless you either execute the Layout Newpage Automatic command to toggle on the automatic insertion of page breaks, execute the Layout Newpage Paginate command to paginate the document, or insert hard page breaks throughout the document by repeatedly executing Layout Newpage Insert.
NOTE: This definition menu item establishes the default pagination only. You can override this default setting for the current session by toggling on or off the automatic insertion of page breaks via the Layout Newpage Automatic command.

If you select Automatic, SmartWare inserts page breaks as document text is entered. The positioning of page breaks is determined by the widow/orphan controls specified in the Current Document Options Definition Menu, and any keep areas contained in the document. Numerous items specified in the Current Print Options Definition Menu, such as the use of headings or footings, page size, and top and bottom boundary settings also determine page break placement. You can override these controls for the current session by toggling off the automatic insertion of page breaks via the Layout Newpage Automatic command off.


Character Insertion Mode Options

This item establishes the default insertion mode. When On is selected, existing text is adjusted as new text is inserted. When Off is selected, existing text is "typed over" as new text is inserted.

The Character Insertion Mode: setting is displayed on the Status Line at the bottom of the screen. When the Insertion Mode is on, Insert ON is displayed. When the Insertion Mode is off, Insert OFF is displayed. INS is used to toggle on or off the Insertion Mode and override for the current word processing session the default value established by this definition menu item.


Font Pick-up Mode

This prompt sets the default to determine which font will be used to enter new text. If you set this prompt to On, the Word Processor will "pick-up" the font at the current cursor position and use it for new text. This is particularly useful when you are editing existing text and want the font of the new text to match the existing text.

If you set this prompt to Off, the last Layout Font Select command will be used to determine the font for new text.

While entering text, you can toggle between these two modes with the command Layout Font Pick-Up or the quick key Ctrl-N. You can tell which mode you are in by looking at the status line. If a number appears at the Font: prompt, the latest Layout Font Pick-Up command will be used. If an asterisk appears at the Font: prompt, you are in "pick-up" mode.

In Project Processing, the font mode can be set explicitly with the following commands.

     LAYOUT FONT PICK-UP ON
     LAYOUT FONT PICK-UP OFF


Default Paragraph Format Options

The Default Paragraph Format options contained in the Word Processor Preferences Definition Menu are discussed below.

Alignment. This item specifies whether the document text is aligned on the left margin (left-aligned) or aligned on both the left and right margins (justified).

Ruler Division (characters per inch). Enter a number between 4 and 24 to designate the number of characters per inch. The default value is 10, therefore, ten characters are contained in each horizontal inch.

Left and Right Margins. Enter a number, in inches, for each margin setting.

Indent. Enter a positive number, in inches, to specify how far to the right of the left margin to indent the first line of a paragraph. Enter a negative number, in inches, to specify how far to the left of the left margin to outdent the first line of a paragraph.

Spacing. Enter a number to specify the vertical line spacing to be used during printing.

Tabs. Enter a series of numbers, in inches, to specify the locations for tab stops. Separate each number with a blank space or comma.

Decimal Tabs. Enter a series of numbers, in inches, to specify the locations for decimal tabs. Separate each number with a blank space or comma.


Special Character Display Options

These option items allow you to control the display of special characters in your document. You can override these defaults for the current word processing session by selecting the Document Visible command.

Page Breaks. Select Visible to display hard and soft page breaks and section breaks in your documents. Select Invisible if you do not want any page or section breaks displayed.

Paragraph Marks. Select Visible to display paragraph marks in your documents. Select Invisible if you do not want paragraph marks displayed.

Tab Marks. Select Visible to display tab symbols in your documents. Select Invisible if you do not want these symbols displayed.

Hidden Text. Select Visible to display hidden text in your documents. Select Invisible if you do not want hidden text to be displayed.

Hidden Text Marks. Select Visible to display hidden text marks in your documents. Select Invisible if you do not want hidden text marks displayed.

Keep Marks. Select Visible to display keep marks in your documents. Select Invisible if you do not want keep marks displayed.

Index Marks. Select Visible to display index marks in your documents. Select Invisible if you do not want index marks displayed.

TOC Marks. Select Visible to display table of contents marks in your documents. Select Invisible if you do not want table of contents marks displayed.

Main Ruler. Select Visible to display the Main Ruler in your document. Select Invisible if you do not want the Main Ruler displayed.

Embedded Ruler. Select Visible to display embedded rulers in your document. Select Invisible to not display embedded rulers.


Document Auto-Save Options

SmartWare Word Processor's Document Auto-Save feature can be enabled to ensure that, periodically, a copy of your current document is saved to disk. SmartWare automatically executes a save of the current document when the specified minutes between saves has elapsed. If you are entering text, moving around in the document, or executing a command at that time, SmartWare waits for a pause in keystrokes before executing the save.

Auto-Save Enabled. Select Yes to enable the Auto-Save feature. Select No if you do not want the auto-save feature enabled.

Auto-Save File Extension. Enter a different file extension, if desired. If you specify a DOC extension, SmartWare will automatically overwrite the existing document file stored on disk when the automatic save is executed for the current document. Do not specify a DOC extension if you want to preserve your stored document and not overwrite it.

Minutes Between Auto-Saves. Enter a number from 1 to 60 to indicate the number of minutes that are to elapse between executions of the automatic save.


Dictionary Preferences Options

Here you can enable or disable many of SmartWare Word Processor's Dictionary features.
NOTE: When all of the Dictionary Preferences items are enabled or set to Yes or On, an additional 70K of memory is required to operate SmartWare Word Processor.

Thesaurus Enabled. Select Yes if you want to enable the SmartWare Thesaurus; select No if you do not.

Spellchecker Enabled. Select Yes if you want to enable the SmartWare Spellchecker. Select No if you do not.

Correction Information. Select Yes if you want a list of alternatives automatically displayed when SmartWare Spellchecker highlights a word that may be misspelled. Select No if you do not want this automatic display. If you choose No, you can still display correction information by pressing F8 when SmartWare highlights a potential misspelling.

Auto-hyphenation. Select On if you want the last word on a line to be automatically hyphenated when it does not completely fit on the line. Select Off if you do not want the word hyphenated and instead, want the entire word to wrap to the next line.


Miscellaneous Options

The Miscellaneous Items options contained in the Word Processor Preferences Definition Menu are discussed below.

Data Path. Enter the data path to be used for storing and retrieving files. The data path specified here overrides for this module the data path specified in the Hardware Preferences Definition Menu. Unless another path is specified during a save or load operation, SmartWare always utilizes this data path when storing or retrieving files.

Automatic Load of Macro File. A macro file contains a set of character output redefinitions for one or more keyboard keys. This menu item allows you to specify the name of a macro file to automatically load whenever SmartWare Word Processor is accessed. The macro filename may be preceded by a path if the file is not located on the current path.

Project File to Run on Entry. A project file contains a set of command format statements, including application commands and project commands, that perform some predetermined activity. This menu item allows you to specify the name of a project file to automatically execute whenever SmartWare Word Processor is accessed. The project filename may be preceded by a path if the file is not located on the current path.

Encryption Driver to Use on New Files. Select Standard to use SmartWare's standard encryption driver to encrypt files. Select Alternate to use an alternate encryption driver.
IMPORTANT: Changing the encryption driver could cause document files to become corrupted and unusable. Do not select the Alternate Encryption Driver unless you are thoroughly familiar with the encryption driver and process being used.


Visible

These pulldown options allow you to control the display of special characters in your document.

Hidden Text. Select this to display hidden text in your documents.

Hidden Text Marks. Select this to display hidden text marks in your documents.

Index Marks. Select this to display index marks in your documents.

TOC Marks. Select this to display table of contents marks in your documents.

Page Breaks. Select this to display hard and soft page breaks and section breaks in your documents.

Paragraph Marks. Select this to display paragraph marks in your documents.

Main Ruler. Select this to display the Main Ruler in your document.

Embedded Ruler. Select this to display embedded rulers in your document.

Tab Marks. Select this to display tab symbols in your documents.


Window Commands

The Window keyword is the basis for the command formats that enable you to display multiple windows and documents, and independently color the components of each window.


Window Options

Window provides the following options:

Split. Separates the current Document Window into multiple windows or displays a Footnote Window.
Close. Closes the current split Document Window or the Footnote Window.
Zoom. Enlarges the current split window to fill the Document Window, or returns an enlarged window to its original split size.
Border. Toggles on or off the display of the Document Window border.
Paint. Provides independent coloring of window components.


Window Split

Window Split divides the current Document Window into multiple Document Windows, or to displays a Footnote Window in conjunction with the current Document Window. The screen can be split into a maximum of 50 windows. Each window is automatically numbered when the split is executed.

When you select Window Split, you must specify whether you want to display a Footnote Window or split the Document Window horizontally or vertically.

Moving between windows


Window Split Footnote

Window Split Footnote is used to display a Footnote Window. When you select Window Split Footnote, the prompt Enter row number, or use cursor keys to select location: is displayed. The line number entered represents where the top line of the Footnote Window is to be located. Enter the line number, or position the cursor on the line where you want the split to occur, and press F10 or ENTER to execute the command. The Footnote Window is then displayed. Footnote text appears in the Footnote Window when a footnote reference is displayed in the current Document Window.

Footnote features


Window Split Horizontal

Window Split Horizontal is used to split the current window horizontally at the specified line location. When you select Window Split Horizontal, the prompt Enter the line number, or use cursor keys to select location: is displayed. Each window resulting from the split must be large enough to accommodate one line of text, otherwise the message Marked area is too small to split. is displayed. Enter the line number, or position the cursor on the line where you want the split to occur and press F10 or ENTER to execute the command.

The Document Window is then split, the current document is displayed in both windows, and the cursor remains in window 1, keeping it the "current window." You may move to window 2 (making it the current window) by executing the Document Goto Window command, by pressing F4, selecting the Window option and entering 2 in response to the prompt, or using Alt-F8 to move to the next window.

To display a different, non-active document in the current window, execute the File Load command. To display a different, active document in the current window, execute the Document Goto Document command.

Loading files
Active files, displaying
Moving between documents


Window Split Vertical

Window Split Vertical is used to split the current window vertically at the specified column position. When you select Window Split Vertical, the prompt Enter column number, or use Tab or cursor keys to select location: is displayed. Each window resulting from the split must be large enough to accommodate a width of 12 characters, otherwise the message Marked area is too small to split. is displayed. Use TAB, RIGHT or LEFT to move the cursor to the desired column, or enter the column number where you want the split to occur and press F10 or ENTER to execute the command.

The Document Window is then split, the current document is displayed in both windows, and the cursor remains in window 1, keeping it the "current window." You may move to window 2 (making it the current window) by executing the Document Goto Window command, by pressing F4, selecting the Window option, and entering 2 in response to the prompt, or by using Alt-F8 to move to the next window.

To display a different, non-active document in the current window, execute the File Load command. To display a different, active document in the current window, execute the Document Goto Document command.

Loading files
Active files, displaying
Moving between documents


Window Close

Window Close is used to close the current Document Window or the Footnote Window. When you select Window Close, you must specify the type of window to close.


Window Close Doc-Window

Window Close Doc-Window is used to close the current Document Window. Windows do not have to be closed in the order that they were created using Window Split. When Window Close Doc-Window is executed, the current window disappears and the remaining windows expand to fill the portion of the screen previously occupied by the window you closed.

A window can be closed without first unloading the document displayed in the window. If you close a window without unloading the document, and the document is not displayed in another window, the document is moved to the "background." It can be redisplayed in a different, current window by executing the Document Goto Document command.


Window Close Footnote

Window Close Footnote is used to close the current window's Footnote Window. When the command is executed, the Footnote Window disappears and the current window expands to fill the portion of the screen previously occupied by the Footnote Window.


Window Zoom

Window Zoom is a toggle command used to either enlarge the current, split window to fill the entire screen, or return the enlarged window to its original split size.

Window Split or Window Close cannot be executed when the current window is zoomed. However, when the current window is zoomed, you can display any remaining split windows in zoomed format by executing the Document Goto Window command and specifying the window desired.

The Quick Key for Window Zoom is F7.


Window Border

Window Border is used to toggle on or off the display of the border surrounding the current Document Window. When the border is toggled off, two additional lines of text can be displayed on the screen.

If you are using multiple windows, you can toggle on or off the display of the borders for any of the windows. When borders are toggled on in multiple windows, the current window displays a double-lined border and the other windows display a single-line border.

Splitting windows
Multiple windows, creating

When borders are toggled off in multiple windows, "boundary" confusion can easily result, especially if the Main Ruler is also toggled off in one or more windows. Since the Window Identifier number is located in the upper left corner of the border, when the border is toggled off, the Window Identifier also disappears.


Window Paint

Window Paint allows you to color specified marked text, the window border, and the Document Window independently of each other. This feature is very useful when multiple windows are being used, since each window can be colored differently.

When you select Window Paint, you must specify whether you want to paint the window border, the Document Window, or marked text. If your hardware does not support the 16 available colors, the 16 colors are mapped to the options available with your hardware.


Window Paint Border

Window Paint Border is used to color the double-lined border surrounding the current Document Window. When the command is selected, the prompt Enter foreground color (0 to 15): and a color selection bar are displayed in the Control Area of the screen. Enter the number corresponding to the color desired and press F10 or ENTER. The border is then displayed in the selected color.


Window Paint Marked-Text

Window Paint Marked-Text is used to color the highlighting and text in a document when a marking option (i.e., block-marking, column-marking, line-marking) is being used. The background color is used for the highlighted block. The foreground color is used for the text that appears within the highlighted block.

When the command is selected, the prompt Enter background color (0 to 15): and a color selection bar are displayed in the Control Area of the screen. Enter the number corresponding to the color desired for the highlighted block and press F10 or ENTER. SmartWare then prompts Enter foreground color (0 to 15): and again displays the color selection bar. Enter the number desired for the text appearing in the highlighted block and press F10 or ENTER. The next time a command is selected that invokes marking, the highlighted block and the text within the block are displayed in the selected colors.


Help Commands

The Help commands invoke SmartWare's extensive on-line help information. The following options are available:

On-line help is available through the Help command. For assistance in running the Tutorial, read the following section. For information on the other Help options, select the appropriate related topic.

Help
Help About-Help
Help Contents
Help Index
Help On-Error


Help Tutorial

Help Tutorial invokes the tutorial for the current module. You may use the tutorial in a step-by-step process to learn the entire module, or you may use it to learn about one particular aspect of the module. If the Word Processor tutorial was not installed on your system, use the Changes and Additions option of the Install program to add it at any time.
IMPORTANT: Because SmartWare Tutorials run within the module they describe, it is important that you unload all active files with the File Unload command before entering the tutorial. When you execute Help Tutorial, you will be prompted to unload all files before continuing.

You are then prompted to enter your name. This is optional, however, if you do, the program will keep track of what lessons you have completed.

The Tutorial menu then appears. If you would like a brief lesson in how tutorials work, select Using Tutorials. If you want to select a lesson, use the cursor keys to move the prompter arrow to the lesson you want and press Enter. You can go through the lessons sequentially, or pick a lesson that interests you.

After you complete a lesson, you are returned to the Tutorial menu.


Remember Commands

The Remember keywords allow you to create, edit and run project processing files. Project Processing is an automated method of executing a sequence of commands.

Refer to Project Processing for detailed information on executing the Remember commands.


Quit Commands

The Quit commands allow you to leave SmartWare Word Processor to enter another SmartWare module, or to return to the operating system. Options for Quit include the following:


 Quit. Returns to the operating system.
Main-Menu. Returns to the Main Menu of SmartWare Software System.
Communications. Leaves SmartWare Word Processor and enters SmartWare Communications.
Database. Leaves SmartWare Word Processor and enters SmartWare Database.
Spreadsheet. Leaves SmartWare Word Processor and enters SmartWare Spreadsheet.

If you have selected the Quit keyword and decide that you do not want to leave SmartWare Word Processor, press Escape.


Word Processor Error Messages

     2101  Password must be from 1 to 16 characters long.

You either have entered too few characters (less than 1) or too many characters (more than 16) as the document lock password. Enter a password containing from 1 to 16 characters.

     2102  Textfiles cannot be locked.

You have attempted to assign a lock password to a textfile. To lock-protect the file, you must first convert it to a document file by executing the File File-type command.

     2103  Document is already locked.

You have attempted to assign a lock password to a document file that has already been lock-protected. To assign the new password, you must first remove the existing password by executing the Document Unlock command.

     2104  Document is not locked.

You have attempted to unlock a document that currently has no lock password assigned to it.

     2105  Error initializing the spellchecking driver (filename).

There is not enough available memory to allocate the memory required to operate the spellchecking feature. If you receive this error while working in a document that is paging to disk, you may be able to secure the required memory by unloading the file, enabling the Spellchecker and then reloading the file. Other procedures that may be used to secure memory include unloading background documents, disabling auto-hyphenation and/or the Thesaurus, erasing the copy and delete buffers, and deleting any unused, defined fonts in the document.

     2106  Error initializing the thesaurus driver (filename).

There is not enough available memory to allocate the memory required to operate the thesaurus feature. If you receive this error while working in a document that is paging to disk, you may be able to secure the required memory by unloading the file, enabling the thesaurus and then reloading the file. Other procedures that may be used to secure memory include unloading background documents, erasing the copy and delete buffers, and deleting any unused, defined fonts in the document.

     2107  Error initializing the auto-hyphenation driver (filename).

There is not enough available memory to allocate the memory required to utilize the auto-hyphenation feature. If you receive this error while working in a document that is paging to disk, you may be able to secure the required memory by unloading the file, turning auto-hyphenation on and then reloading the file. Other procedures that may be used to secure memory include unloading background documents, erasing the copy and delete buffers, and deleting any unused, defined fonts in the document.

     2108  Unable to complete the generation of the table of contents .

A memory allocation or paging failure has occurred. Review your document to ensure all formatting and table of contents entries are entered correctly. Save the document and exit the Word Processor; then re-enter the module and reload the document. To secure additional memory, disable the Spellchecker, auto-hyphenation and/or the Thesaurus before attempting to generate the table of contents. You may also secure additional memory by unloading any background document, erasing the copy and delete buffers, and deleting any unused, defined fonts in the document.

     2109  The window is too small for a ruler.

The current window is too small to allow the display of the Main Ruler. You may either continue to display the window without the Main Ruler, or reconfigure the window's size.

     2110  Nothing to compute.

The formula you are attempting to compute is incomplete or entered incorrectly. Check your formula for correct syntax and try again.

     2111  Control pair(s) span section boundary.  Cannot delete existing toc or index.

Since the index or the table of contents was last generated, a control item such as hidden text, an index entry, or a table of contents entry has been inserted into the document. The control item crosses the section break that separates the index or the table of contents from the rest of the document. Remove the control item and try again.

     2112  The maximum number of footnotes has been reached.

You have attempted to exceed the maximum number of footnotes allowed in a single document. Remove any unnecessary footnotes and try again.

     2113  No footnote exists between the cursor and the bottom of the window.

No footnote reference number is currently displayed in the Document Window between the current cursor position and the bottom of the window. Scroll through the document until the footnote reference number for the footnote you want to modify is displayed in the Document Window and re-execute the command.

     2114  A marker name must begin with a letter.

A marker name must begin with a letter, can be a maximum of eight characters and must be unique for the current document.

     2115  The marker name already exists.

The marker name entered is already in use in the current document. A marker name must be unique for the current document.

     2116  Cannot attach a marker to the end of file character.

A marker name cannot be specified for the end of file character. To move quickly to the end of file character, press Ctrl-End from any location in your document.

     2117  No markers found.

You have asked to scroll forward through the document, pausing at each marker. No markers exist between the current cursor position and the end of the document. Reposition the cursor and try again.

     2118  Cannot remove a hidden marker.

Markers that are part of invisible hidden text cannot be removed. Unhide the text containing the marker by selecting Document Visible Hidden-Text and try the Marker Remove command again.

     2119  Marker name not found.

You have entered a marker name that has not been defined for this document. Marker names are case sensitive. Check the spelling and capitalization of the marker name you entered.

     2120  Invalid position.

You have entered an "inches" value that is less than zero or conflicts with existing column boundaries. Check the current column boundaries and enter a different value.

     2121  Not positioned in an MCA.

You must be positioned in a defined Multiple Column Area (MCA) to execute the command. Move the cursor into the MCA and try the command again.

     2122  Not positioned in a column.

You have pressed F3 or F4 to adjust the start or end position of a column; however, you are not positioned inside the defined column boundaries. Move the cursor inside the column boundaries and try again.

     2123  Not positioned on an index item.

You must be positioned on an index item to execute the command. Move the cursor to the index item you want to edit and select the command again.

     2124  Partial spanning of hidden text items is not allowed.

A portion of the text that you have marked as an index or a table of contents item has previously been marked as hidden text. Either all or none of the hidden text must be included in the index or table of contents item.

     2125  Partial spanning of other index items is not allowed.

A portion of the text that you have marked as an index item is already marked as an index item. Either all or none of the existing index item must be included in the text marked as the new index item.

     2126  No marked text to use as a template.

No text characters are contained either in the area you have marked as an index item, or in the index item you are trying to edit. An index item must contain text characters.

     2127  Entered text is too long.

Your index entry exceeds the 132 character maximum that may be entered for a single index entry.

     2128  A single slash is not allowed.

You have entered only a slash (/) as the index entry; this is not an acceptable entry. An index item must contain text characters. A slash is used to separate index entries when you want the marked index item to be referenced in multiple locations in the generated index. For example, if you mark the text "custom dictionary" as an index item in your document and you want it to appear in the generated index as a subordinate entry under the primary entries "creating," "editing," and "spellchecker," enter "creating:/editing:/spellchecker:" for the index entry.

     2129  A leading colon is not allowed.

You have started the index entry with a colon; this is not an acceptable entry. A colon is used to denote a subordinate entry. For example, if you mark the text "custom dictionary" as an index item in your document and you want it to appear in the generated index as a subordinate entry under the primary entry "creating," you must enter "creating:" for the index entry.

     2130  Misused colon.

You have either omitted or misplaced a required colon. Check the syntax of your index entry and edit the entry as required. A colon is used to denote a subordinate entry. The correct use of colons in index entries are shown in the following examples: "creating:" or "creating:/editing:/spellchecker:" "creating:/editing:dictionaries/spellchecker:".

     2131  Maximum depth limit exceeded.

You have exceeded the maximum of subordination levels for a generated index. Subordinate entries are specified by entering a colon (:) as part of the index entry. For example, if you mark the text "custom dictionary" as an index item in your document and you want it to appear in the generated index as a subordinate entry under the primary entry "creating," you must enter "creating:" for the index entry. A maximum of four colons (denoting five levels) may be specified for a single entry.

     2132  Level must be within the range of 1 to 5.

You have entered a level number outside the range of 1 - 5. A maximum of five levels are available for table of contents entries.

     2133  Partial spanning of other table of contents items is not allowed.

A portion of the text that you have marked as a table of contents item is already marked as a table of contents item. Either all or none of the existing table of contents item must be included in the text marked as the new table of contents item.

     2134  Not positioned on an index item.

The cursor was not positioned on an index item when the command was selected. To remove an index item and the index entries associated with that index item, the cursor must be positioned on the index item you want to delete. Move your cursor to the desired index item and select the command again.

     2135  Unable to add the word to the "replace all" list.

You have pressed F2 during an interactive spellcheck, indicating that you want to replace all the subsequent occurrences of a particular word with another specified word. However, you either have entered a "replacement" word that contains more than 60 characters (the maximum word length), or the "replace all" list is full. A maximum of 1000 characters is allowed in a document's "replace all" list. A word pair consists of the existing word and the replacement word.

     2136  Unable to add the word to the "ignore" list.

You have pressed F4 during an interactive spellcheck, indicating that you want to ignore all the subsequent occurrences of a particular word. However, the "ignore" buffer is full. A maximum of 500 characters is allowed in a document's "ignore" buffer. Between spell checking sessions, you can press Alt-F9 to clear the ignore buffer.

     2137  Invalid custom dictionary name.

You have specified an invalid filename or a file extension other than "udc" for the custom dictionary file. Dictionary file extensions must be "udc"; edit the extension as required. Refer to Software System Manual for information regarding filename conventions and restrictions.

     2138  Unable to add to the list of custom dictionaries.

You have pressed F5 during an interactive spellcheck and specified that you want to create a new custom dictionary. However, the maximum of 5 custom dictionaries for the current document already exist. You must access the Current Document Options Definition Menu by selecting the Layout Document-Options Current-Document command and remove one of the specified custom dictionary names before this custom dictionary can be created.

     2139  Error opening the custom dictionary.

You have pressed F5 during an interactive spellcheck and specified a word to add to an existing custom dictionary. However, the custom dictionary you have specified either is in a directory that you do not have access rights to, or a disk error has occurred during the internal operation involved in opening a custom dictionary file.

     2140  Unable to add the word to the custom dictionary.

You have pressed F5 during an interactive spellcheck and specified a word to add to an existing custom dictionary. However, you either have entered a word that contains more characters than the maximum word length of 22 characters, or a disk error has occurred during the internal operation involved in updating the custom dictionary file.

     2142  Dictionary functions are disabled in the demo version.

You are currently operating the demo version of SmartWare Word Processor. No dictionary operations are available for this version of the software.

     2143  The spellchecker is not enabled.

You have selected a spellchecking operation when the spellchecking feature has not been enabled. You must access the Word Processor Preferences Definition Menu by selecting the Tools Preferences Wordprocessor command and set the Spellchecker menu item to "Yes." If you do not have enough available memory to enable the Spellchecker, you can attempt to free-up sufficient memory by disabling auto-hyphenation, unloading any background documents that are currently active, or disabling SmartWare Thesaurus, if you have purchased, installed and enabled the Thesaurus. Other procedures that may be used to secure memory include erasing the copy and delete buffers, and deleting any unused, defined fonts in the document.

     2144  The thesaurus is not enabled.

You have selected a thesaurus operation when the thesaurus feature has not been enabled. SmartWare Thesaurus is an add-on feature that must be purchased and installed before thesaurus operations may be performed. If you have purchased and installed SmartWare Thesaurus, you must access the Word Processor Preferences Definition Menu by selecting the Tools Preferences Wordprocessor command, and set the Thesaurus menu item to "Yes." If you do not have enough available memory to enable the Thesaurus, you can attempt to free-up sufficient memory by unloading any background documents that are currently active, disabling SmartWare Spellchecker and auto-hyphenation, erasing the copy and delete buffers, and deleting any unused, defined fonts in the document.

     2145  The cursor is not positioned on a table of contents item.

The cursor was not positioned on a table of contents item when the command was selected. To remove a table of contents item, the cursor must be positioned on the table of contents item you want to delete. Move your cursor to the desired table of contents item and select the command again.

     2146  Invalid left margin for column (column number).

Via Project Processing or Alt-X you have entered a start position for a column that is either out of range (less than zero or greater than the maximum length of the current line), or that overlaps another column boundary. Check the value entered for the start position of the column indicated and edit as required.

     2147  Invalid right margin for column (column number).

Via Project Processing or Alt-X you have entered an ending position for a column that is either out of range (less than zero or greater than the maximum length of the current line), or that overlaps another column boundary. Check the value entered for the ending position of the column indicated and edit as required.

     2148  Cannot insert an automatic paragraph number in a centered paragraph.

You have attempted to use the automatic method to insert a paragraph number in a centered paragraph. Automatic paragraph numbers are generated according to the number of indent tabs in a paragraph. Since no indent tabs can exist in a centered paragraph, automatic paragraph numbers may not be inserted in a centered paragraph. You may either insert the paragraph number using the fixed method, or you can edit the ruler for the current paragraph, specify left-alignment or justified, and then use the automatic method to insert the paragraph number.

     2149  Cannot insert an automatic paragraph number in a right-aligned paragraph.

You have attempted to use the automatic method to insert a paragraph number in a right-aligned paragraph. Automatic paragraph numbers are generated according to the number of indent tabs in a paragraph. Since no indent tabs can exist in a right-aligned paragraph, automatic paragraph numbers may not be inserted in a right-aligned paragraph. You may either insert the paragraph number using the fixed method, or you can edit the ruler for the current paragraph, specify left-alignment or justified, and then use the automatic method to insert the paragraph number.

     2150  No synonyms, antonyms or root words were found.

You have requested a thesaurus operation for a word in your text that is not contained in SmartWare Thesaurus.

     2151  No antonyms were found.

You have pressed F5 to obtain antonyms for a selected word in your text. However, no antonyms for the selected word are contained in SmartWare Thesaurus.

     2152  Error opening the main thesaurus dictionary (filename).

The thesaurus is either in a directory that you do not have access rights to, or a disk error has occurred during the internal operation involved in opening the thesaurus file, or you have not purchased and installed SmartWare Thesaurus.

     2153  Error reading the main thesaurus dictionary (filename).

A disk error has occurred during the internal operation involved in reading the thesaurus file. Press Escape to abort the command process and execute the File Save command to save your current document. Obtain a fresh copy of SmartWare's thesaurus files, access the Operating System and replace your existing thesaurus files with new copies of the files.

     2154  Error opening the dictionary (dictionary name).

You have specified a data path that either you do not have access rights to, or that does not exist, or contains an invalid path structure.

     2155  Error writing the file (filename).

You have requested that a spelling check be performed and written to disk. Check the path you have specified to ensure you have access rights to the directory. If the directory and path you have specified are available to you, then either there is not sufficient disk space remaining to write the file, or a disk error has occurred during the internal operation involved in writing the file.

     2156  Unable to insert the correct number of indent tabs.

You are attempting to use the automatic method to insert a paragraph number in your document. Either you do not have enough tab positions specified on the Current Ruler to accommodate the paragraph number level requested, or else the current line is too short to accommodate the number of indent tabs required.

     2157  Level number of paragraph is invalid.

You have entered a paragraph number level that is less than 1 or greater than 15. Select the command again and enter a number within the range of 1 through 15.

     2158  The cursor is not positioned in a numbered paragraph.

You have attempted to delete a paragraph number when the cursor is not positioned in a numbered paragraph. Move the cursor to the paragraph containing the number you want to remove and select the command again.

     2159  Unable to complete the generation of the index.

A memory allocation or paging error has occurred during the internal operation performed during the generation of an index. Review your document to ensure all formatting and index entries are entered correctly. Execute the File Save command to save the current document, unload the document, and exit SmartWare Word Processor. You may then re-enter the module, load the document and try the command again. To secure additional memory, disable the Spellchecker, auto-hyphenation and the Thesaurus before attempting to generate the index again. Other procedures that may be used to secure memory include unloading background documents, erasing the copy and delete buffers, and deleting any unused, defined fonts in the document.

     2160  Cannot use "replace all" to replace a word with itself.

You have pressed F2 during an interactive spellcheck, indicating that you want to replace all the subsequent occurrences of a particular word with another specified word. However, you have entered a "replacement" word that is identical to the existing word.

     2161  Controls span entry boundaries.  The block cannot be moved.

You have marked a block to move that splits a control item (i.e., a table of contents or index item, a keep area or hidden text block). Remove the control item or re-mark the block of text to move so that either all or none of the control item is included in the marked block.

     2162  Controls span entry boundaries.  The block cannot be deleted.

You have marked a block to delete that splits a control item (i.e., a table of contents or index item, a keep area or hidden text block). Remove the control item or re-mark the block of text to delete so that either all or none of the control item is included in the marked block.

     2163  The lines across an MCA boundary may not be joined.

Using Delete, you have attempted to delete the last paragraph mark of a linked MCA column entry. MCA entries may not be combined in this manner. You must delete one of the entries and retype it as part of the other entry, or you can combine the text in the two MCA entries by moving the text from one entry into the other entry one column at a time.

     2164  The margins are not wide enough for (number of columns) columns.

The number of columns you have specified cannot fit within the current margins. A minimum of two positions must be allotted per column to accommodate the left and right boundaries for each column. You may either enlarge your current margins or enter a smaller value for the number of columns desired.

     2165  Error adding column (column number).

A memory error has occurred during the internal process performed to add a column. Execute the File Save command to save the current document, unload the document and exit SmartWare Word Processor. You may then re-enter the module, reload the document and attempt the command again.

     2166  Cannot place a new column in an existing column.

You have specified a start or end position for the new column that locates it within the boundaries of an existing column. Either move the existing columns to the right or left to make room for the new column, or specify a new start or end position for the new column.

     2167  Illegal MCA block specification.

Via Project Processing or Alt-X, you have specified an illegal range or nonexistent column number. Edit the range or column number as required and try the command again.

     2168  Cannot define an MCA in the middle of a graph.

You have attempted to define an MCA in the middle of a graph; this is not allowed. Move the cursor out of the graph area and try the command again.

     2169  Not positioned in a linked MCA.

This command is available only when you are working in a linked MCA. You have attempted this command when the cursor is not positioned in a linked MCA.

     2170  MCA spans a section boundary.  Cannot delete the existing toc or index.

When SmartWare is instructed to generate a new index or table of contents, the existing index or table of contents is automatically deleted by SmartWare. Due to modifications that have been made to the document since the index or table of contents was last generated, a portion of the existing index or table of contents currently lies within an MCA. Edit the document to extricate the index or table of contents from the MCA and try the command again.

     2171  Invalid number of columns.

You have entered either a negative number or a zero in response to the "Enter the number of columns:" prompt. Enter a positive number and execute the command again.

     2172  Incorrect number of columns specified.

Via Project Processing or Alt-X you have failed to enter one or more start or end positions for each of the existing columns. The number of start or end positions on the command line must match the number of columns defined in the MCA. Correct the command statement and try the command again.

     2173  Error in boundary parameter.

Via Project Processing or Alt-X you have entered an incorrect syntax for the start and end positions of the defined columns. Start and end positions for each column must be separated by a hyphen (-). Correct the command statement and try the command again.

     2174  An MCA cannot be located at the top of a document.

You either have attempted to delete the paragraph(s) above an MCA, which would move the MCA to the top of the document, or you are attempting to define an MCA at the top of the document. An MCA cannot be located at the top of a document. However, you can place a single, empty paragraph at the top of the document and then locate the MCA directly below the empty paragraph.

     2175  Unable to complete the deletion of the section.

A paging error has occurred during the deletion of the existing index or table of contents. When SmartWare is instructed to generate a new index or table of contents, the existing rendition (if present) of the index or table of contents is deleted before the new version is created. Execute the File Save command to save the current document, unload the document and exit SmartWare Word Processor. You may then re-enter the module, reload the document and try the command again.

     2177  The search text entered is longer than 30 characters.

You have entered more than the maximum of 30 characters in response to the "Enter search text:" prompt. Try the command again and enter 30 characters or less for the search text.

     2179  A locked document cannot be sent.

You have attempted to send a SmartWare document that contains a lock password to another SmartWare module; this is not allowed. You must remove the lock password (using Document Unlock) before the document can be sent.

     2201  Cannot insert an MCA into another MCA.

You have attempted to copy, move or insert (via Undelete) an MCA into the boundaries of an existing MCA; this is not allowed.

     2202  Invalid repeat count.

While attempting to perform a repetitious search for a specified character string, you either have specified a search option value that is outside the range of valid numbers or you have entered two different values (i.e., 10f20). A search option value cannot be a zero or a negative number. Check the command format for the search option value entered and edit as required. Then, try the command again.

     2203  Cannot sort text in an MCA.

You have attempted to sort text in an MCA using the Edit Sort Text command. To sort text in an MCA, you must use the Edit Sort Column command. Refer to the Edit Sort command in Chapter 9 of Word Processor Manual for additional information.

     2204  Cannot sort across a keep area.

You have attempted to include all or part of a keep area in the text you have marked to sort; this is not allowed. Text located within a designated keep area cannot be sorted. You may either delete the keep marks and try the command again, or exclude the keep area from the sort block.

     2205  The delete buffer is empty.

You have attempted to insert the contents of the delete buffer at the current cursor position. However, the delete buffer is currently empty.

     2206  Invalid destination specifier.

While attempting to perform a copy or a move operation, you have entered an invalid specification for the destination location for the copy or move. Check the command format to ensure that the word "point," the character "*" (indicating "current location"), or a valid location specification (i.e., s1p5l10c5) is entered for the destination.

     2207  Invalid copy operation.

You have specified the copy buffer as the location for both the source text and the destination for the copy procedure; this is not allowed. You cannot copy FROM the buffer TO the buffer. Select the command again and specify to copy FROM the buffer to a different destination, or copy from a different location TO the buffer.

     2208  The copy buffer is empty.

You have requested that the contents of the copy buffer be copied or moved to a destination in your document. However, the copy buffer is currently empty.

     2209  No text is marked.

You have attempted to copy, move or export text, however, you have failed to specify the text you want to copy, move or export. Select the command again and mark the text to be used.

     2210  Invalid move operation.

You have specified the copy buffer as the location for both the source text and the destination for the move procedure; this is not allowed. You cannot move text FROM the buffer TO the buffer. Select the command again and specify to move text FROM the buffer to a different destination, or move text from a different location TO the buffer.

     2211  Controls span paragraph boundaries.  The text cannot be sorted.

You have marked an area of text to sort that contains a control item (i.e., a table of contents or index item, a keep area or hidden text block) that spans a paragraph boundary. This is not allowed. To perform the sort, you must first remove the control item.

     2212  Controls span entry boundaries.  The entries cannot be sorted.

You have marked an area of text to sort that contains a control item (i.e., a table of contents or index item, a keep area or hidden text block) that spans an entry boundary. This is not allowed. To perform the sort, you must first remove the control item.

     2213  Invalid column number.

When specifying the column number of the column you want to sort, you entered a number for a column that does not exist. Check the value you entered, then select the command again and enter the appropriate column number.

     2214  The block specification is missing.

While attempting to locate a character string in your document, you selected the "M" (Mark Text) option so that the search would be performed in a specific area of your document. However, you failed to indicate the portion of the document you wanted to search. Select the command again and specify the area of the document to search.

     2215  The "M" (Mark Text) option must be used to search a block.

While attempting to locate a character string in your document, you indicated that you wanted to search a specific portion of your document for the string. However, you failed to include the "M" (Mark Text) option in your command format. Select the command again and include the "M" option as part of your search options.

     2216  The replacement text entered is longer than 30 characters.

You have entered more than the maximum of 30 characters in response to the "Enter replacement text:" prompt. Try the command again and enter 30 characters or less for the replacement text.

     2217  Too many search option characters are specified.

You have exceeded the 10 character maximum for the search options. Select the command again and specify 10 or less search option characters.

     2218  Invalid search option ("search option character").

While entering search option characters, you have specified an invalid character. The following characters are valid search option characters: "F", "B", "G", "I", "W", "M", "C". Refer to the sections entitled Search Options in the discussions of the Document Find and Edit Replace commands in Chapter 9 of Word Processor Manual for additional information.

     2219  Text ("character string") not found.

The character string you entered in response to the "Enter search text:" prompt was not found. Unless otherwise specified by search option characters, SmartWare searches forward through the document from the current cursor position for the indicated search text. Check the text string entered, your cursor position at the time the command was selected, and the search options specified. Modify the string, your location or the search options as required and then try the command again.

     2300  Extensions .bdc and .btx are reserved for use by the SmartWare system.

Do not use the extensions ".bdc" or ".btx" when you assign a name to a file. SmartWare uses these extensions to name files created by the automatic file backup option.

     2301  File not found or invalid filename entered.

You have entered a filename that contains invalid characters, or you do not have access rights to the directory containing the file, or the directory containing the file is not available from your current path. Check your current path, and the filename you entered. Refer to SmartWare Software System for information concerning filename specifications.

     2302  Cannot load a "BDC" or a "BTX" file.

You are attempting to load a backup version of a document or textfile; this is not allowed. If you have the "Automatic File Backup" setting in the Word Processor Preferences Definition Menu set to "Yes," SmartWare automatically retains backup copies for files of certain types. Before one of these backup files can be loaded or imported, you must rename the file, via your operating system utility or the Tools File Rename command, and specify a "DOC" or "TXT" extension for the file.

     2303  A file of that name is already loaded.

You have specified a filename of a file that is already active. To display the file in your current window, select the Document Goto Document command. Refer to the discussion of the Document Goto command in Chapter 9 of Word Processor Manual for additional information.

     2304  Error saving file.

Either a disk error has occurred during the internal operations that are performed during the saving of a file, or you do not have write access to the directory specified. Select the command again and save it to a different location (i.e., a different directory or a floppy disk), specifying a different filename and path.

     2305  The filename is in use.

You have entered a filename for the current file that is already being used by another active document. Specify a unique filename for the current file.

     2306  The file cannot be opened for update.

You have responded "Y" to the message "File of that name exists. Overwrite (y/n)?" Either the file you are trying to write to is currently in use by another station, or you do not have write access to the directory containing the file. Select the command again and specify a new filename and path to save the file.

     2308  Window not found.

You have entered a window number that does not exist. Select the command again and enter a valid window number.

     2309  Cannot go to a hidden marker.

You have entered a marker name for a marker that is currently embedded in a block of hidden text. Make the hidden text visible (using Document Visible Hidden-Text) and then try the command again.

     2310  Document format error.

A processing error has occurred in the format of the document file you have attempted to load. The file is unloadable.

     2311  Convert this document with the utility docupdat.exe before loading.

This document was created by the original Smart 1.0 software. Obtain the utility docupdat.exe from SmartWare Corp. to convert this document to a readable SmartWare format.

     2312  Version 3.10 dictionary files omitted; they are no longer valid.

You have loaded a SmartWare 3.10 file that used a 3.10 dictionary file. SmartWare 3.10 dictionary files were assigned the filename extension "CLM"; SmartWare dictionary files are assigned the filename extension "UDC". To resolve the problem, access SmartWare 3.10 Word Processor, load the "CLM" files, convert the "CLM" files to textfiles and rename the files using a "UDC" extension. The "UDC" file may also need to be sorted using the command Edit Sort Text Ascending to obtain proper ordering. Then re-enter SmartWare Word Processor and try the command again.

     2313  Textfiles do not have passwords.

You have attempted to assign or remove a password from a textfile. Passwords are not stored with textfiles. You may convert a textfile to a document file (using File File-Type) and execute File Password Attach to assign a password to the file. However, the password is not retained until you save the document (using File Save). If you assign a password to a document file and then convert it to a textfile, when the textfile is saved, the password is not retained.

     2314  Automatic hyphenation is not available for this document.

The automatic hyphenation setting in the Wordprocessor Preferences Definition Menu is set to "on" and you have specified a new current document. The hyphenation dictionary used by the document cannot be opened. This message is usually accompanied by another message which specifies the cause of the error. If you have received no other message with this error, access the Current Document Options Definition Menu (by selecting Layout Document-Options Current-Document) and select a valid language in the language item setting.

     2315  Error opening the main hyphenation data file (filename).

You have attempted to set the automatic hyphenation setting in the Wordprocessor Preferences Definition Menu to "on," or you have specified a different language in the Current Document Options Definition Menu, or you have accessed a document that uses a different language. Causes of the error vary, dependent upon the operation you attempted. Either you do not have access rights to the directory containing the appropriate hyphenation data file; the directory is not available from the path you have specified; or, a disk error has occurred.

     2316  Error reading the main hyphenation data file (filename).

A disk error has occurred during the internal process involved in reading a file. Save and unload the current file (using File Save and File Unload). You may need to obtain a new copy of the main hyphenation data file before attempting the command again.

     2317  Error reading the main hyphenation exception dictionary (filename).

A disk error has occurred during the internal process involved in reading a file. Save and unload the current file (using File Save and File Unload). You may need to obtain a new copy of the main hyphenation exception dictionary file before attempting the command again.

     2318  Error reading the secondary hyphenation exception dictionary (filename).

A disk error has occurred during the internal process involved in reading a file. Save and unload the current file (using File Save and File Unload). You may need to obtain a new copy of the secondary hyphenation exception dictionary file before attempting the command again.

     2319  Error closing the previously opened custom dictionaries.

This error has occurred while trying to close custom dictionaries in order to initialize another language. Either you do not have write access to the directory containing the files or a disk error has occurred during the internal process involved in closing a file. Any changes made to the custom dictionary file during this session have been lost. If you are unable to successfully close the file, the contents of the file will be permanently lost.

     2320  Error opening the main dictionary (filename).

Either you do not have access rights to the directory containing the main dictionary; the directory is not available from the path you have specified; or, a disk error has occurred.

     2321  Error reading the main dictionary (filename).

A disk error has occurred during the internal process involved in reading a file. Save and unload the current file (using File Save and File Unload). You may need to obtain a new copy of the main dictionary file before attempting the command again.

     2322  Error reading the temporary custom dictionary.

A disk error has occurred during the internal process involved in reading a file. Save and unload the current file (using File Save and File Unload). You may need to obtain a new copy of the temporary custom dictionary file before attempting the command again.

     2323  Error opening the temporary custom dictionary.

Either you do not have access rights to the directory containing the main dictionary; the directory is not available from the path you have specified; or, a disk error has occurred.

     2324  A locked document cannot be written to disk.

You have attempted to save or export a SmartWare document that contains a lock password; this is not allowed. You must remove the lock password (using Document Unlock) before the document can be saved or exported.

     2326  Graph information lost.

The File Save command is always aborted when this error is issued. You either have insufficient memory or insufficient disk space to execute the command. Or, a fatal disk error may have occurred.

     2327  Internal format error.

The File Save command is always aborted when this error is issued. You either have insufficient memory or insufficient disk space to execute the command. Or, a fatal disk error may have occurred.

     2328  Cannot change the file type of a locked document.

You have attempted to change a locked document file to a textfile. This is not allowed. To convert the document file to a textfile you must first unlock the document, using Document Unlock.

     2329  A locked document cannot be renamed.

You have attempted to change the name of a locked document file. This is not allowed. To change the document name, you must first unlock the document, using Document Unlock.

     2330  No permission to save file under this name.

You have attempted to save a file that is in use at another workstation. Or, you do not have write access to the directory containing the file or to the file itself. Either wait until the file is released by the other workstation to obtain save permission for the file, or save it to a different directory or different filename.

     2401  Insufficient memory to store a custom dictionary name.

You have attempted to enter a custom dictionary name in the Current Document Options Definition Menu. To free-up memory, unload any active background documents, disable the Spellchecker, auto-hyphenation, and Thesaurus. You may also secure memory by deleting the copy and delete buffers and any unused, defined fonts.

     2402  Invalid indent; changed to 0.

Either you have entered an indent value that is out of range or you have changed your margin to a value that has rendered the current indent value invalid. Check your margin and indent values, edit as required and try the command again.

     2403  Invalid source section number.

You have entered a section number that does not exist in response to the "Select section to move:" prompt. Review your section numbers and try the command again.

     2404  Invalid destination section number.

You have entered an invalid section number (less than or equal to zero) in response to the "Select destination section:" prompt.

     2405  Invalid mark type.

Via Project Processing or Alt-X, you have specified a mark type that is not valid for the current function.

     2406  Cannot split a keep area.

The section you have specified to move splits a keep area; this is not allowed. Either all or none of the keep area must be included in the section you have specified to move. Or, you can remove the keep area (using Layout Keep Remove) and then try the command again.

     2407  Cannot split hidden text.

The section you have specified to move splits a block of hidden text; this is not allowed. Either all or none of the hidden text must be included in the section you have specified to move. Or, you can remove the hidden text marks (using Layout Hidden-Text Remove) and try the command again.

     2408  Cannot split an MCA.

The section you have specified to move splits an MCA either at the source or destination location; this is not allowed. Either all or none of an MCA must be included in the section being moved.

     2409  Insufficient memory to update the unnamed document.

You have changed one or more items in the New Document Options Definition Menu, while retaining an active, unnamed document. As SmartWare updates the unnamed document to reflect the definition menu changes, this error is issued if there is insufficient memory to complete the update. To free-up memory, you can disable the spellchecker, auto-hypenation, and/or thesaurus features, unload any active background documents, delete the contents of your copy and delete buffers by pressing Alt-minus, and delete any unused, defined fonts.

     2410  A keep area may not contain a page break.

You have attempted to define a keep area that crosses a page break, or you have attempted to insert a hard page break inside a keep area. Page breaks are not allowed in keep areas. To designate the block of text as a keep area, you must first remove the page break (using Layout Newpage Remove).

     2411  The cursor is not positioned in a keep area.

You have attempted to remove the keep marks from a keep area; however, the cursor is not positioned inside the keep area. Move the cursor into the keep area and select the command again.

     2412  Invalid font value for primary index entries; changed to 0.

In either the Current Document Options Definition Menu or the New Document Options Definition Menu, you have entered an invalid font value (outside the range of 0 to 31) for primary index entries, or you have entered a character other than B, b, U, or u. SmartWare has changed the invalid font value to the default font 0.

     2413  Invalid font value for subordinate index entries; changed to 0.

In either the Current Document Options Definition Menu or the New Document Options Definition Menu, you have entered an invalid font value (outside the range of 0 to 31) for subordinate index entries, or you have entered a character other than B, b, U, or u. SmartWare has changed the invalid font value to the default font 0.

     2414  Invalid font value for alphabetic index headings; changed to 0.

In either the Current Document Options Definition Menu or the New Document Options Definition Menu, you have entered an invalid font value (outside the range of 0 to 31) for alphabetic index headings, or you have entered a character other than B, b, U, or u. SmartWare has changed the invalid font value to the default font 0.

     2415  The cursor is not positioned within hidden text marks.

You have attempted to permanently redisplay a block of hidden text by removing the hidden text marks associated with it. However, the cursor is not positioned within or on the hidden text marks. Move the cursor onto or within the hidden text marks and select the command again.

     2416  Cannot split an index item when hiding text.

The text that you have marked as hidden text splits an index item; this is not allowed. Either all or none of the index item must be included in the text marked as hidden text. Or, you can remove the index item (using Document References Index Remove) and select the command again.

     2417  Cannot split a table of contents item when hiding text.

The text that you have marked as hidden text splits a table of contents item; this is not allowed. Either all or none of the table of contents item must be included in the text marked as hidden text. Or, you can remove the table of contents item (using Document References Toc Remove) and select the command again.

     2418  Cannot split a keep area when hiding text.

The text that you have marked as hidden text splits a keep area; this is not allowed. Either all or none of the keep area must be included in the text marked as hidden text. Or, you can remove the keep area (using Layout Keep Remove) and select the command again.

     2420  Cannot hide text in an MCA.

The text that you have marked as hidden text is located in an MCA; this is not allowed. An MCA cannot contain hidden text.

     2421  No format names exist.

You have attempted to edit, insert, or delete a named ruler when no ruler format names have been defined for the current document. Named rulers are document specific. Rulers that have been named in document X cannot be used in document Y unless they have been defined and saved with document Y.

     2422  Unable to save the new format.

You have attempted to edit or insert a ruler and there is insufficient memory available to perform the operation. To free-up memory, you can disable the spellchecker and/or thesaurus, unload active background documents, delete the contents of the copy and delete buffers by pressing Alt-minus, and delete any unused, defined fonts.

     2423  Unable to name the format.

You have attempted to name a ruler format and there is insufficient memory available to perform the operation. To free-up memory, you can disable the spellchecker and/or thesaurus, unload active background documents, delete the contents of the copy and delete buffers by pressing Alt-minus, and delete any unused, defined fonts.

     2424  Cannot delete the first ruler.

You have attempted to delete the first ruler of the document; this is not allowed. If the ruler settings are inappropriate for your needs, you can change the settings via the Layout Ruler Edit or Layout Ruler Reformat command.

     2425  Invalid increment.

You have pressed F5 to set incremental tabs for the ruler being edited. However, you have entered a negative number; negative increments are not allowed. Select the command again and enter a positive incremental value.

     2426  Invalid format name.

You have entered a ruler format name that does not exist for the current document. Or, you have entered a ruler format name that contains invalid characters or exceeds the maximum of 8 characters. Check the format names available and select the command again.

     2427  Format name already exists.

You have press F8 to assign a name to the ruler format, but you have entered a format name that already exists for the current document. Select the command again and enter a unique format name.

     2428  Cannot split an index item.

The section you have specified to move splits an index item; this is not allowed. Either all or none of the index item must be included in the section you have specified to move. Or, you can remove the index marks (using Document References Index Remove) and select the command again.

     2429  Cannot split a table of contents item.

The section you have specified to move splits a table of contents item; this is not allowed. Either all or none of the table of contents item must be included in the section you have specified to move. Or, you can remove the table of contents marks (using Document References Toc Remove) and select the command again.

     2430  Cannot insert the default ruler into an MCA.

You have attempted to insert the default ruler into an MCA; this is not allowed. Use the Layout Ruler Insert Current command to make the desired changes, or move the cursor out of the MCA and select the command again.

     2431  Cannot insert a named ruler into an MCA.

You have attempted to insert a named ruler into an MCA; this is not allowed. Use the Layout Ruler Insert Current command to make the desired changes, or move the cursor out of the MCA and select the command again.

     2432  Unable to complete all the format changes.

There is insufficient memory available to process all the changes you have made on the ruler line. Save and unload the current document (using File Save and File Unload), and exit SmartWare Word Processor. You may then re-enter the module. To free-up memory, disable the Spellchecker, auto-hyphenation, and the Thesaurus; delete the copy and delete buffers; unload any background documents; and delete any unused, defined fonts. Then, load the document and try the command again.

     2433  Cannot adjust the margins in an MCA.

You have attempted to change the margin settings on the ruler line in an MCA; this is not allowed. To adjust the margins one column at a time, select the Document Columns Edit Boundaries command.

     2434  Cannot delete the first ruler of an MCA.

You have attempted to delete the first ruler of an MCA; this is not allowed.

     2435  Cannot delete the first ruler following an MCA.

You have attempted to delete the first ruler following an MCA; this is not allowed.

     2436  Invalid index margins; changed to 0.5 and 6.5 inches.

In either the Current Document Options Definition Menu or the New Document Options Definition Menu, you have specified values for the index margins that are invalid (i.e., negative values, exceed the line length, or are too close together to allow space for the generated index). Index margin settings must be entered in inches. SmartWare has automatically changed the settings to 0.5 for the left margin and 6.5 for the right margin.

     2437  Invalid indention for subordinate index entries; changed to 0.

In either the Current Document Options Definition Menu or the New Document Options Definition Menu, you have specified an invalid value for the indention setting for subordinate index entries. The indention settings must be entered in inches. SmartWare has automatically changed the setting to 0.

     2438  Invalid table of contents margins; changed to 0.5 and 6.5 inches.

In either the Current Document Options Definition Menu or the New Document Options Definition Menu, you have specified values for the table of contents margins that are invalid (i.e., negative values, exceed the line length, or are too close together to allow space for the generated table of contents). The table of contents margins must be entered in inches. SmartWare has automatically changed the settings to 0.5 for the left margin and 6.5 for the right margin.

     2439  Invalid table of contents indent (level number); changed to 0.

In either the Current Document Options Definition Menu or the New Document Options Definition Menu, you have specified an invalid value for the indention setting for the table of contents level specified in the error message. The indention values must be entered in inches. SmartWare has automatically changed the invalid setting to 0.

     2440  The ruler format name does not exist.

You have specified a ruler format name that does not exist for the current document. Check the ruler formats available for this document, then select the command again.

     2441  Invalid ruler division.

You have specified a ruler division (characters per inch setting) that is outside the range of valid values. Any number from 4 through 24 may be entered for a characters per inch (cpi) setting.

     2442  Font driver failure.

You have pressed Ctrl-B to boldface new text, or Ctrl-U to underscore new text. Since no bold or underscore version of the current font existed, SmartWare tried to create the font. However, there is either insufficient memory to process the font, or a disk error occurred. Save and unload the document (using File Save and File Unload) and exit SmartWare Word Processor. You can then re-enter the module. Free-up memory by disabling the Spellchecker, auto-hyphenation and the Thesaurus; unloading background documents; pressing Alt-minus to delete the contents of the copy and delete buffers; and deleting any unused, defined fonts. After freeing-up memory, try the command again.

     2443  Invalid table of contents (level number) font value; changed to 0.

In either the Current Document Options Definition Menu or the New Document Options Definition Menu, you have specified an invalid value (outside the range of 0 to 31) for the font to be used for the table of contents level specified in the error message. Or, you have entered a character other than B, b, U, or u. SmartWare has automatically changed the invalid font value to the default font 0.

     2444  Cannot insert a section break at the top of a document.

You have attempted to insert a section break at the top of the document; this is not allowed. At least one empty paragraph must be inserted at the top of the document before a section break may be inserted.

     2445  Cannot insert a page break at the top of a document.

You have attempted to insert a page break at the top of the document; this is not allowed. At least one empty paragraph must be inserted at the top of the document before a page break may be inserted.

     2446  A section break or a page break already exists.

You have attempted to insert a section break or a page break where a section break or a page break already exists. An existing page break may be replaced with a section break. However, an existing section break cannot be replaced with a page break. To replace a section break with a page break, you must first remove the section break (using Layout Section Remove) and then insert the page break (using Layout Newpage Insert).

     2447  Graphs may not extend across page or section breaks.

You have attempted to insert a page break or a section break in the middle of an existing graph; this is not allowed. Move the cursor out of the graph area and select the command again.

     2448  A keep area cannot include the end of file mark.

The keep area you have attempted to define includes the end-of-file mark. Add carriage returns (by pressing Enter) to move the end-of-file mark below the last line of text to be included in the keep area.

     2450  The cursor is not positioned above or below a section break.

You have attempted to remove a section break, however, the cursor is not positioned on the line directly above or below the section break. Move the cursor to the line directly above or below the section break and select the command again.

     2451  The cursor is not positioned above or below a page break.

You have attempted to delete a hard page break, however, the cursor is not positioned on the line directly above or below the page break. Move the cursor to the line directly above or below the hard page break and select the command again.

     2452  Invalid left margin.

Via Project Processing or Alt-X, you have entered an invalid left margin setting (i.e., negative value, value larger than the right margin setting) on the ruler line. The left margin setting must be entered in inches. Check the command format statement for the incorrect value and edit as required.

     2453  Invalid right margin.

Via Project Processing or Alt-X, you have entered an invalid right margin setting (i.e., negative value, value smaller than the left margin setting) on the ruler line. The right margin setting must be entered in inches. Check the command format statement for the incorrect value and edit as required.

     2454  Invalid alignment.

Via Project Processing or Alt-X, you have entered an invalid text alignment value on the ruler line. The alignment specification is determined by the character entered in the first position on the ruler line. Four alignment choices are available: "l" (left-aligned), "r" (right-aligned), "j" (justified), or "c" (centered). Check the command format statement for the incorrect alignment specification and edit as required.

     2455  Invalid spacing.

Via Project Processing or Alt-X, you have entered an invalid vertical line spacing value on the ruler line. Line spacing is determined by the values entered in the second and third positions on the ruler line. Any number from 0 through 9 may be entered in the second position on the ruler line. Check the command format statement for the incorrect spacing specification and edit as required.

     2456  Invalid indent.

Via Project Processing or Alt-X, you have entered an invalid indent setting on the ruler line. Indents must be entered in inches. Check the command format statement for the incorrect indention specification and edit as required.

     2457  Invalid tab position.

Via Project Processing or Alt-X, you have entered an invalid tab setting on the ruler line. Check the command format statement for the invalid tab(s) and edit as required.

     2459  Too many ruler format changes to process.

While making changes to the ruler settings, you have exceeded the maximum 255 character limit for the length of a command format statement. Re-evaluate the changes you have made, consolidating or eliminating changes as much as possible.

     2460  Invalid margins.

Via Project Processing or Alt-X, you have entered either a right margin setting that is less than the left margin setting, or the margins are less than an inch apart in a standard text area. (In an MCA, the margins must accommodate two ruler division marks.) Check the command format statement for the incorrect margin setting and edit as required.

     2461  A keep area may not contain a section break.

You have attempted to insert a section break in the middle of a keep area or you have attempted to define a keep area around a section break; this is not allowed. Move the cursor out of the keep area and select the command again.

     2462  Cannot change the ruler divisions (characters per inch) in an MCA.

You have pressed F7 to change the characters per inch (cpi) setting on a ruler line in an MCA; this is not allowed.

     2463  Cannot name a ruler in an MCA.

You have pressed F8 to name the format for the ruler currently being edited or inserted in the MCA; this is not allowed. MCA ruler format name assignments are not available.

     2464  A keep area may not be inserted inside a graph area.

You have attempted to define a keep area inside a graph area; this is not allowed. Move the cursor outside the graph area and select the command again.

     2465  Invalid font number.

While editing a font (using Layout Font Edit) you have entered a negative number or a number larger than 31 as a font number. A font can be assigned any number from 0 through 31. Select the command again and enter a valid font number. While loading or importing a document (using File Load or File Import), a font exists in the text that has not been defined for the document. This could happen as the result of a memory error, a corrupted disk, or a file conversion from another word processing program.

     2466  Invalid font description.

You have entered a font string descriptor that is invalid (i.e., improper spelling, invalid attributes). Check the command format statement and edit as required.

     2467  Error changing font.

A memory error has occurred during the retroactive updating of text using the font you are changing. Save and unload the current document (using File Save and File Unload) and exit SmartWare Word Processor. You can then re-enter the module and free-up memory by disabling the Spellchecker, auto-hyphenation, and the Thesaurus; erasing the copy and delete buffers; deleting any unused, defined fonts; and unloading any background documents.

     2468  Invalid gutter space; changed to 0.5 inches.

You have entered an invalid number for the "Minimum gutter space between quick-define columns" option setting in either the Current Document Options Definition Menu or the New Documents Definition Menu. Enter a number from 0.0 to 10.0 inches.

     2501  The text portion of the page is too short; form length changed to (line number) lines.

You have entered values in either the Current Print Options Definition Menu or the Preset Document Definition Menu for headings, footings, form length, and top and bottom boundaries that have caused an insufficient amount of space to be left for actual text in the document. Review and edit the values specified.

     2502  Insufficient memory to process the print options.

There is not enough memory available to set up the print options. You can free-up memory by unloading any background documents, disabling the Spellchecker, auto-hyphenation, and/or Thesaurus features, erasing the copy and delete buffers, and deleting any unused, defined fonts. Select the command again and specify the changes desired.

     2503  Insufficient memory to process all of the heading/footing changes.

There was not enough memory available to process all of the heading or footing changes specified. A partial updating of the changes may have resulted. Review the settings specified in the Current Print Options Definition Menu. You may free-up memory by unloading any background documents, disabling the Spellchecker and the auto-hyphenation feature, disabling the Thesaurus, erasing the copy and delete buffers, or deleting any unused fonts. Select the command again and specify the changes desired.

     2504  Invalid section number.

You have specified a section number that does not exist when using F6 to copy the options from another section. Review your document for the section numbers used and re-execute the command.

     2505  Invalid merge variable (Sc:#, Pg:#, Ln:#, Ps:#).

An unprintable character, an end of file mark, or a paragraph mark is located between a merge start character () and its corresponding merge finish character (). Review the main document being used for the merge; check for matching start/finish merge characters and unprintable characters. Edit as required and then try the command again.

     2506  Merge variable (Sc:#, Pg:#, Ln:#, Ps:#) is too big.

More than 50 characters are entered between the merge start character () and the merge finish character (); this is not allowed. Review the main document being used for the merge. Edit the specified merge variable as required and then try the command again.

     2507  Merge variable (Sc:#, Pg:#, Ln:#, Ps:#) not found in the input file.

The first line of the input file being used for the merge does not contain all of the merge replacement variable strings used in the main document. Review the input file and the main document for replacement variable string congruence. Edit the files as required and then try the command again.

     2508  Merge file variables must be bracketed by "" or ''.

One or more of the variable replacement strings in the merge input file is missing the required single or double quotes. Each replacement string in the input file must be surrounded by either single or double quotation marks. Review the input file, edit the file as required, and then try the command again.

     2509  The maximum number of merge replacement variables has been exceeded.

More than 50 merge replacement variables have been entered into the main document being used for the merge. A maximum of 50 replacement variables are allowed. Review the main document, edit as required, and then try the command again.

     2510  A changed, locked document cannot be printed.

You have made changes to, and then attempted to print, a document containing a lock password. This is not allowed. To print the document, you must first remove the lock password by selecting the Document Unlock command.

     2511  The default merge file does not exist.

You have attempted to use the "default" merge file for the merge operation, however, no "default" merge file exists. You must access SmartWare Database and send to SmartWare Word Processor the file to be used for the merge, and then try the command again. Or, you can select the Print Merge Screen option and perform an interactive merge, entering the merge replacement data via keyboard input.

     2512  Invalid interface filename.

An invalid filename was entered during the execution of the Send command in SmartWare Database. Exit SmartWare Word Processor, return to SmartWare Database and execute the Send command again.

     2513  An improper number of merge fields exists in the input file.

The number of replacement strings in one of the data lines of your input file does not match the number of merge replacement strings in the first line of the input file being used for the merge. Review the input file, edit as required, and try the command again.

     2514  Internal error; missing a merge variable.

An internal error has occurred while attempting to merge the specified file. If possible, save any active documents you currently have loaded, and then exit SmartWare Word Processor. Re-enter the module and try the command again.

     2515  No merge replacement variables exist in the current document.

You have attempted to perform a merge using a main document that contains no merge replacement variables; this is not allowed. At least one replacement variable must be present in the main document. If your main document contains only formula variables, refer to Merge Variables in Chapter 6 of Word Processor Manual for instructions on inserting a "dummy" replacement variable in your main document.

     2516  Invalid font number in heading, footing, or footnote text in section (section #).

You have specified an undefined font number in the text of a heading, footing, or footnote. Font 0 has been substituted for the undefined font. Review the headings, footings, or footnotes for the invalid font number. Then, either change the number to a defined font number or define the new font, using the Layout Font command before executing the command again.

     2517  '%[' without ']' found in heading, footing, or footnote text in section (section #).

An open bracket indicating the beginning of a font control sequence code was found in the heading, footing, or footnote text, however no corresponding close bracket indicating the end of the control code was located. The attempted font change has been ignored. Review the heading, footing, and footnote text for the document, edit as required, and execute the command again.

     2518  Line (Sc:, Pg:, Ln: ) contains more than 50 font changes.

You have specified more than 50 font changes on one line of text; the maximum is 50. Review the document you are attempting to print or merge, edit as required to reduce the number of font changes to 50 or less, and try the command again. The section, page, and line number are given to help you correct the error.

     2519  Invalid form width; changed to 8.5 inches.

You have specified an invalid number for the form width specification item in either the Current Print Options Definition Menu or the Preset Document Definition Menu. Access the appropriate definition menu and enter a form width from 2.0 to 30.0 inches.

     2520  Invalid right boundary; changed to 0.

You have specified an invalid number for the right boundary specification item in either the Current Print Options Definition Menu or the Preset Document Definition Menu. Access the appropriate definition menu and enter a right boundary specification from 0.0 to 5.0 inches.

     2521  Invalid left boundary; changed to 0.

You have specified an invalid number for the left boundary specification item in either the Current Print Options Definition Menu or the Preset Document Definition Menu. Access the appropriate definition menu and enter a left boundary specification from 0.0 to 5.0 inches.


      2522 The printer you selected cannot print 8 lines per inch.

The printer you have selected in Tools Preferences Hardware does not support the printing of 8 lines per inch. Select a different printer, or change the lines per inch setting on the Current Print Options menu.


      2524 Maximum number of merge documents exceeded.

A maximum of 1000 files can be created in one merge process. You have exceeded this number.

     2601  Unable to view the graph.

This error is issued when a condition other than insufficient memory or a missing graph file prevents the graph from being viewed.

     2602  No graph found.

You have attempted to view a graph, however the cursor was not positioned in the correct location to display the graph desired. For a medium or small graph, the cursor must be positioned beside the shaded area representing the graph when the Graph View Document command is executed. The cursor must be on the line immediately above or below the shaded area representing a large graph when the Graph View Document command is executed. Reposition the cursor and try the command again.

     2603  A graph cannot be inserted into an existing graph.

You have attempted to insert a graph into an existing graph; this is not allowed. Reposition the cursor and try the command again.

     2604  A graph cannot be inserted into an MCA.

You have attempted to insert a graph into an MCA; this is not allowed. Reposition the cursor so that it is not in an MCA and try the command again.

     2605  Missing graphics file.

You have attempted to insert the "default" graph metafile, however, no "default" graph metafile has been sent to SmartWare Word Processor from SmartWare Spreadsheet. You must access SmartWare Spreadsheet and send the metafile that you want to insert in the Word Processor document. Then, return to SmartWare Word Processor and try the command again.

     2606  A large graph cannot be located at the top of a document.

You have either attempted to insert a large graph at the top of a document, or delete an empty paragraph (indicated by a paragraph mark) located at the top of the document, which is immediately followed by a large graph. Neither of these situations are allowed; a large graph cannot be located at the top of a document.

     2607 Insufficient memory to view the graph.

There is not enough memory available to generate the graph you have specified.

     2608  Unprintable graph: page length is (#) and the graph length is (#).

You have attempted to insert a graph that is too large to fit in the page size defined in the page profile on the Current Print Options Definition Menu. You must either change the Print Options settings to expand the page length, or insert a small graph instead.

     2701  The window is too small for a border.

You have attempted to toggle on the display of the Window Border, however, the current window is too small to accommodate a border. Reconfigure the size of the current window and select the command again.

     2702  The Footnote Window is too small to allow a Document Window border.

You have attempted to toggle on the display of the Document Window border, however, the footnote window is too small to accommodate a border. Reconfigure the size of the Footnote Window and select the command again.

     2703  Cannot close a zoomed window.

You have attempted to close a zoomed window. Execute the Window Zoom command to return the window to its original size and then select the command again.

     2704  Only one window exists.

You have attempted to close a window when only one window exists.

     2705  A Footnote Window is already open.

You have requested a Footnote Window, however, a Footnote Window has already been created. Only one Footnote Window is allowed.

     2706  The maximum number of windows is open.

You have attempted to create another Document Window, however, you already have 50 windows open. The maximum number of windows that you may have open at one time is 50.

     2707  The specified area is too small to split.

You have attempted to split a window, however, the resulting window size is too small to allow the split to occur. If you are splitting the window horizontally, each window resulting from the split must be large enough to accommodate one line of text. If you are splitting the window vertically, each window resulting from the split must be large enough to accommodate a width of 12 characters.

     2708  Invalid color selection.

You have entered a number outside the range of available SmartWare colors. Select the command again and enter a number from 0 through 15.

     2709  A zoomed window cannot be split.

You have attempted to split a zoomed window; this is not allowed. To split the current window, you must first execute the Window Zoom command to return the window to its original size, then select the Window Split command again.

     2710  The window cannot be closed.

The configuration of the windows you currently have split renders it impossible to close this particular window. When a window is closed, the remaining windows are enlarged to fill the empty space created by the closed window. However, in this case, the surrounding windows cannot be expanded to fill the space that would be vacated by this window. Close another window first, and then try the command again.

     2800 The custom dictionary is too large to convert.

The custom dictionary you are converting requires too much memory to process. The file size cannot be more than 64K.

     2901  A tab insertion is not allowed in a centered paragraph.

You have attempted to insert a tab in a centered paragraph. This is not allowed.

     2902  A tab insertion is not allowed in a right-aligned paragraph.

You have attempted to insert a tab in a right-aligned paragraph. This is not allowed.

     2903  Insufficient memory to process words.

There is not enough available memory to run SmartWare Word Processor. If you have any memory-resident programs installed, you can delete these programs to free-up memory.

     2904  Invalid margins; changed to 0.5 and 6.5 inches.

You have specified margins in the Wordprocessor Preferences Definition Menu that are out of range or that conflict with each other. The invalid margin settings have been automatically converted to 0.5 and 6.5 inches.

     2905  Invalid auto-save extension in the preferences file; changed to "DAS".

You have specified an invalid extension in the Wordprocessor Preferences Definition Menu for documents created via the Document Auto-Save feature. The invalid extension has been automatically converted to .das.

     2906  Invalid marking range.

Via Project Processing or Alt-X, you have specified a range of marked text that either starts in an MCA and ends in normal text; starts in normal text and ends in an MCA; starts in one MCA and ends in another; or starts in one MCA column and ends in another column of the same MCA. None of these situations are allowed. Check the command format statement and edit as required.

     2907  Invalid marking specification.

Via Project Processing or Alt-X, you have specified a range of marked text that either contains an incorrect character or is entered in the wrong order. Check the command format statement and edit as required.

     2908  Cannot span an MCA with a column mark.

Via Project Processing or Alt-X, you have specified a range of marked text that spans an MCA boundary. A column-marking specification is not allowed to cross into an MCA. Check the command format statement and edit as required.

     2910  Invalid cursor mark index; going to the top of the document.

An internal error has occurred. Save and unload your document (using File Save and File Unload) and exit SmartWare Word Processor. You may then re-enter the module and continue with your work.

     2911  Cannot delete all the characters between two section breaks.

You have attempted to delete all the characters that separate two section breaks; this is not allowed. At least one empty paragraph must be located between two section breaks. To delete all the characters, you must first delete one of the section breaks using Layout Section Remove.

     2912  Fatal error loading merge file; exiting SmartWare.

An internal error has occurred during the print merge procedure. You have been removed from SmartWare Word Processor and returned to the Operating System. Re-enter the module and try the command again.

     2913  A paging error has occurred.

An internal error has occurred. Try to save and unload your document (using File Save and File Unload) and then exit SmartWare Word Processor. If you are unable to save your document, all the characters that you typed since the document was last saved will be lost. After you have exited the module, you may then re-enter the module and continue with your work.

     2914  Error paging in memory.

An internal error has occurred. Try to save and unload your document (using File Save and File Unload) and then exit SmartWare Word Processor. If you are unable to save your document, all the characters that you typed since the document was last saved will be lost. After you have exited the module, you may then re-enter the module and continue with your work.

     2915  A possible loss of text has occurred.

An internal error has occurred. Try to save and unload your document (using File Save and File Unload) and then exit SmartWare Word Processor. It is advisable to try to save your document to a new file (specify a new filename) so that if a total "lockup" occurs during the save, the file that was created the last time the document was saved will remain intact. If you are unable to save your document, all the characters that you typed since the document was last saved will be lost. After you have exited the module, you may then re-enter the module and continue with your work.

     2916  Invalid vertical line spacing; changed to (number).

In the Wordprocessor Preferences Definition Menu, you have specified a value for the vertical line spacing that is out of the accepted range. The invalid number has been converted by SmartWare. To avoid the display of this message at startup, enter a valid setting for the vertical line spacing specification item in the Word Processor Preferences Definition Menu.

     2917  The incorrect character <(character)> exists in the tab specification list.

In the Wordprocessor Preferences Definition Menu, you have specified a value for a tab setting that is invalid. Only digits, decimal separators, and spaces are allowed in the tab specification list. Check the list for a non-digit value and edit as required.

     2918  Changes will affect this session only.

Someone at another workstation within your network group is currently using the definition files (extension ".def"). Any changes you make will affect the current session only and will not be retained after you exit SmartWare Word Processor. Your network administrator can create separate user directories so each user can have a set of definition files that cannot be altered by other users in your network group.

     2919  Error updating the preferences file.

You have attempted to change one or more settings in the Word Processor Preferences Definition Menu. A disk error has occurred during the internal process involved in the updating of the definition file. None of the specified changes have been retained. Exit SmartWare Word Processor, then re-enter the module, and try the command again.

     2920  NOTE: No permission to save file under this name.

You have loaded a file that is in use at another workstation. Or, you do not have write access to the directory containing the file or to the file itself. You will need to save the file under a different filename or to a different directory to retain any changes you make to the file.

     2921  NOTE: Document is locked; changes cannot be saved or printed.

You have loaded a document that has been locked to protect it from permanent, unauthorized modification. You may print or merge the document if you make no changes to it. If you modify the document, it cannot be saved, printed, or merged.

     2922  Insufficient memory to set a project file to run on entry.

In the Word Processor Preferences Definition Menu, you have specified a SmartWare project file that is to automatically execute when SmartWare Word Processor is accessed. However, there is not enough memory available to save the project file name. Free-up memory by disabling SmartWare Spellchecker, the auto-hyphenation feature, and SmartWare Thesaurus. Other procedures that may be used to secure memory include unloading background documents, erasing the copy and delete buffers, and deleting any unused, defined fonts in the document.

     2924  Invalid language.

The language that you have specified in the Spellchecker specification items in either the Current Document Options Definition Menu or the New Documents Definition Menu has been assigned an invalid number by SmartWare during the internal process associated with recording the setting. Save any active documents you have loaded and exit SmartWare Word Processor.

     2925  Unable to complete reform; possible loss of text.

During the reforming of the document text, either an internal processing error has occurred, or there is not sufficient memory available to perform the required reforming. Save the current document, if possible, using a different filename and exit SmartWare Word Processor. You can then free-up memory by disabling SmartWare Spellchecker, the auto-hyphenation feature, and SmartWare Thesaurus. Other procedures that may be used to secure memory include unloading background documents, erasing the copy and delete buffers, and deleting any unused, defined fonts in the document. You may then re-enter the module and attempt the command or procedure again.

     2926  Invalid project filename.

You have specified a project filename in response to the prompt "Enter project file for next application:" during the selection of the Document Send command. However, you have entered an invalid filename; a maximum of 78 characters are allowed when specifying a drive and path in conjunction with a filename. Try the command again and specify a valid project filename.

     2927  Invalid entry project filename in preferences file.

In the Word Processor Preferences Definition Menu, you have specified a SmartWare project file that is to automatically execute when SmartWare Word Processor is accessed. However, you have entered an invalid filename for the project file. A maximum of 78 characters are allowed when specifying a drive and path in conjunction with a filename. Review the filename entered and edit as required.

     2929  Invalid tab position (#) in preferences file.

In the Default Paragraph Format settings in the Word Processor Preferences Definition Menu, you have specified an invalid tab position in the tab specification list. Tab positions must be greater than zero and less than or equal to 30 inches. Review the tab specification list and edit as required.

     2930 No printer driver loaded.  Unable to process words.

If Tools Preferences Hardware specifies a printer for which there is no print driver file, or if the default ascii_pr.pdv and generic.dsc files are not present in the system directory, SmartWare attempts to make a dummy font structure that would allow entry into the Word Processor. The error message is issued when the attempt to make the dummy font fails, probably due to memory constraints. Install (or re-install) the missing files.

     2932 Obsolete bin number encountered, use print options to change page profile.

You have loaded a document created in an earlier version. The current bin number you have selected cannot be translated. Select Print Options and modify the page profile for each section of this document.

     2933 Margin area too large for form length.

The page layout you have specified for this document doesn't leave enough room for document text. The area taken up by the top and bottom margins, headers and footers, lines after headings and before footings and lines to enclose the document must leave at least four lines for document text in the form length. Reduce one or more of these values or increase page length in the Page Profile to fix the problem. NOTE: If you are printing landscape, the page width is considered the form length.

     2934 Warning: Font number <#>, for footnotes, has not been defined.

You have attempted to insert a footnote reference in a font that has not been defined. The font used for footnotes is determined by the Font to use for footnote references: font on the Document Options screen. You can execute Layout Document-Options Current-Document or New-Documents and change the font at this prompt to a font that does exist. Or, you can execute Layout Font Edit Current-Document and define a font for that number.

If you do not correct this problem, your footnote references will be printed in font 0, which is the standard font.


SmartWare Communications Command Reference


Overview

This section of on-line help explains the purpose and format of each SmartWare Communications command. Menu keywords are presented in this section in the same order in which they appear on the SmartWare Communications keyword menu.

Four of the keywords, Tools, Help, Remember, and Quit, are applicable to all SmartWare modules. Discussions of these keywords are general, with details being limited to Communications usage. For more information on the use of these commands, refer to Software System Manual and Project Processing.

If you have not used a communications package before, we suggest that you read the Communications Manual and that you also use the Communications Tutorial.


Set-Terminal Commands

The Set-Terminal commands in SmartWare Communications are used to control configurations of your local computer and modem.

Set-Terminal provides the following options:

Duplex. Changes the Duplex setting.
Filters. Filters out unwanted characters.
Goto. Switches between voice and data communications.
Keyboard. Creates and deletes keyboard definition files.
Edit-Modem. Creates and modifies modem definition files.
Paint. Modifies the color of your communications screens.
Settings. Changes the current communications profile settings.


Set-Terminal Duplex

The Set-Terminal Duplex command is used to change the Duplex setting. Generally, duplex refers to whether communication is one-way (half) or two-way (full). In SmartWare Communications, the Duplex setting refers to whether locally typed characters are echoed to the screen during a communications session. You can select either Half or Full Duplex.


Duplex Full

If you select Set-Terminal Duplex Full, no characters that you type will be echoed to your screen. You will be able to see characters only if the remote computer echoes them to your screen. When SmartWare Communications is in Terminal Mode and you notice that every character you type appears on your screen twice, execute the Set-Terminal Duplex Full command. Duplex Full is generally used by the originating computer.


Duplex Half

If you select Set-Terminal Duplex Half, the characters that you type on your computer will be echoed to your terminal screen. If every character you type does not appear on your screen, but the characters the remote computer is sending do appear on your screen, execute the Set-Terminal Duplex Half command. Duplex Half is generally used by the answering system.

The Quick Key Alt-U displays the Half/Full Duplex option on the menu.


Related Profile Settings

The Forced local echo: setting in the Advanced User Settings section of the Communications Profile Menu will force character echoing to the terminal screen of your computer if it is set to on. Some remote computers may not echo characters properly, so you can always use this setting in combination with Duplex commands to get the correct character echoing.

Set-Terminal Settings


Set-Terminal Filters

Select Set-Terminal Filters to identify characters that you do not want captured or displayed. The Filter commands allow you to edit the filter tables that are used to filter incoming characters. Filter tables stop unwanted characters from being displayed or captured.
NOTE: Editing the filter tables does not activate the filters. You must select the Set-Terminal Settings Edit command and enable the filter.

The tables that you edit with these commands are attached to the currently loaded settings. Once you've edited a filter table, you must use the Set-Terminal Settings Save command to save the changes you've made. The saved filter table will always be associated with the profile that was loaded at the time of the save. Whenever you load that profile, the filter table will also be loaded.

Options for Set-Terminal Filters include Capture and Terminal.


Filters Capture

Select Set-Terminal Filters Capture to edit the Capture Filter Table. This filter table is used to filter characters that are captured to a buffer, file, or printer. The Capture Filter Table is explained in the section titled Filter Tables.


Filters Terminal

Select Set-Terminal Filters Terminal to edit the Terminal Filter Table. This filter table is used to filter characters that are sent to the terminal screen. The Terminal Filter Table is explained in the section titled Filter Tables.


Filter Tables

When you select the Set-Terminal Filters Capture command, the Capture Filter Table is displayed. When you select the Set-Terminal Filters Terminal command, the Terminal Filter Table is displayed. Both tables display the characters, or their values, that your system supports. The default screen for editing the filter table lists the decimal values of the character set (0 -- 255).

Two other screens display the same filter table in different formats. Press F3 to display another format. The two other formats include a hexadecimal table of characters and the displayable characters themselves.

To select the characters you do not want captured or displayed, press the arrow keys until a desired character is enclosed by the brackets. The F2 key acts as a toggle to turn highlighting on or off. Highlighted characters are filtered out. Characters that are not highlighted are captured or displayed.

If you wish to stop editing the filter tables without saving changes, you can press Escape to abort. To complete the changes you make to the filter table, press F10 and then select the Set-Terminal Settings Save command. Remember that the filter table will not be saved to disk until the settings are saved with the Set-Terminal Settings Save command.

Data Capture
Data Receive
Set-Terminal Settings


Set-Terminal Goto

Select Set-Terminal Goto to switch between voice and data communications. Options for Goto include Carrier and Voice.

The Quick Key F4 allows you to start execution of the Set-Terminal Goto command.


Goto Carrier

Use Set-Terminal Goto Carrier when you wish to exchange any type of data through SmartWare Communications. When you execute this command, SmartWare waits for a carrier signal to respond. You and the remote computer operator should coordinate execution of this command as much as possible. When you select Set-Terminal Goto Carrier, the message Issuing carrier, hangup phone. Escape to cancel carrier appears.


Goto Voice

Use Set-Terminal Goto Voice when you must interrupt a communications session to talk to the remote computer operator. Once your conversation is complete, you can switch back to carrier (data) mode to resume data transmission. This command works only when both systems are running SmartWare Communications.

If you initiate a request for voice communication, you see the message Voice request in progress, awaiting reply. Escape to cancel. Next, you and the respondent, in this case the remote computer operator, both see the message Press F10 to go to voice. Escape to cancel. Once you press F10, the other party has three seconds to pick up the phone before the connection is broken.

After completing the conversation, you may return to data communications by selecting Set-Terminal Goto Carrier.
NOTE: If you wish to switch the current communication link to voice communication, a telephone must be connected to the modems at both ends of the link.

Connection Dial


Set-Terminal Keyboard

The Set-Terminal Keyboard command is used to create and erase keyboard definition files. These files have two functions. First, they allow keyboard keys to be redefined while SmartWare Communications is in Terminal Mode. This is useful when you need to emulate other terminal keyboards. In addition, keyboard definition files allow the Attention, Break, and Switch keys to be redefined. Keyboard definition files are used in conjunction with a communications profile.

A specific keyboard definition is used only when a profile is loaded that specifies that definition filename in the Keyboard Definition section. If you wish to define a keyboard definition for a profile that is already loaded, the profile must be edited to specify the new definition filename. The changes take effect immediately, but you must save the profile if you wish to reload the new keyboard definition later.

The Quick Key Alt-J begins execution of Set-Terminal Keyboard, displaying the options Define and Undefine.


Keyboard Define

Select Set-Terminal Keyboard Define to define a keyboard for terminal emulation. When you execute this command, you are prompted to enter a key definition filename. Enter a new filename (a definition you wish to create) or an old filename (a definition you wish to edit), and press Escape. The Keyboard Definition menu appears. All keyboard definition files have a .key extension.
NOTE: Database key files also use a .key extension, so make certain you have created separate subdirectories for each module, as described in Software System Manual.


Keyboard Definition Menu

After you have selected a keyboard definition file to edit, the Keyboard Definition menu is displayed.

Use the same keys to edit the Keyboard Definition menu as you would to edit any definition menu in SmartWare. Refer to Software System Manual for information about SmartWare definition menus.

There are four ways to define a key:

Literal. To specify literal characters, type them in at the key designation, enclosing them in quotation marks. For example, at the Down: setting type abcd. Once the specified keyboard definition file is loaded, every time Down-Arrow is pressed the letters abcd are transmitted while SmartWare Communications is in Terminal Mode.

Decimal. To specify characters with decimal representation, enter them as numbers corresponding to the ASCII decimal code. For example, at the Home: setting, if you typed 13, Home would be redefined to produce a carriage return every time it is pressed.

Hexadecimal. To specify characters with Hexadecimal representation, enter them as numbers preceded by an H. The number should correspond to the ASCII hexadecimal code. For example, the definition Home: H0D (H zero D) would redefine Home to produce a carriage return when it is pressed.
NOTE: If you reenter the Keyboard Definition menu later, any hexadecimal characters you defined will be in decimal format.

System Key Word. To redefine the three special system keys used in SmartWare Communications, use ATTENTION, BREAK, and SWITCH. The default keys for dumb terminals only are as follows: Escape equals ATTENTION; Alt-B equals BREAK; and F3 equals SWITCH. As an example, if you wish to redefine the Attention Key from Escape to Ctrl-A, simply use F3 to delete the word ATTENTION next to the Escape: designation and then type ATTENTION next to the Control-A: designation.
NOTE: Except for System Key words, you can mix two types of character representations in the same keystroke definition. For example, to redefine Tab to the ANSI erase screen code, at the Tab: option type 27 "[2J".


Keyboard Undefine

Select Set-Terminal Keyboard Undefine to erase a previously created keyboard definition. When you execute this command, you are prompted for a definition filename. Enter a filename to be erased.

Settings


Set-Terminal Edit-Modem

Select Set-Terminal Edit-Modem to create or modify modem definition files for modems not currently supported by SmartWare.
IMPORTANT: Use this command only if your modem is not supported and you understand the internal operation of your modem. Do not use this command to change configurations on existing modems. Also, do not use this command unless you have a manual for your modem that lists all of the codes your modem uses.


Modem Definitions

Select Set-Terminal Edit-Modem to create a modem definition file. When you select this command, a prompter is displayed showing any modem definition files you have previously created. Select a file on the prompter or enter a filename for a new definition file. You are then prompted to enter the name of your modem. The Modem Definition menu is then displayed.


Modem Definition Menu

The settings on the Modem Definition menu are used to create a new modem definition file. The modem definition file allows you to redefine a modem to work with SmartWare.

The first prompt on the Modem Definition menu is Modem Name:. This prompt allows you to define a name for the modem you want to use. The modem name can contain up to 40 characters.

The remainder of the Modem Definition menu is divided into four sections: Result Code Definitions, Modem Wakeup Sequences, Modem Command Definitions, and Modem Control Parameters.


Result Code Definitions

Result code definitions are text strings sent from the modem to the computer to signal that modem commands were executed properly. Although some communication programs do not use result codes, SmartWare requires you to at least set connect result codes to answer incoming calls. For best results in using your modem, you may also wish to specify additional result codes in your modem definition to ensure correct operation of your modem.
Comment: Select Tools Preferences Communications to gain access to the Communications Preferences menu.

All result code strings that you enter on the Modem Definition menu are sent by the modem to your computer system to signal that the modem has received and executed a valid modem command. If you have set Display Modem Commands/Results: to yes on the Communications Preferences menu, a box will be displayed on the Status Window showing any discrepancies between the expected result and the actual result.

There are three ways of specifying modem definition codes:

NOTE: Two types of character representation can be mixed in the same setting. For example, a setting for a wakeup sequence might be "ATX1"13, which would represent the characters ATX1 and a carriage return.
Literal | To specify literal characters, enter the characters, enclosing them in quotation marks.
Decimal | To specify characters with decimal representation, enter them as numbers corresponding to the ASCII decimal code.
Hexadecimal | To specify characters with hexadecimal representation, enter them as numbers preceded by an H. The number would correspond to the ASCII hexadecimal code (e.g., H0D represents a carriage return).

Result code definitions include the following:

Acknowledge. This code signals that the modem has received and executed a valid modem command.

Connect 1200 baud. (also Connect 2400, 4800, 9600, and 14400 baud) This code signals connection with another modem at the correct baud rate. This result code and the other connect result codes are required for SmartWare Communications to connect at these baud rates. SmartWare Communications evaluates the codes sent by the modem to determine the baud rate at which the modem is running. If a match to one of the connect codes specified here is found, SmartWare switches to the baud rate being used.

Ring Detected. This code is sent by the modem each time the phone line rings.

No Carrier. This code is sent by the modem when a connection is expected but does not occur.

Error. This setting contains the string that is sent by the modem when a command is expected but is not executed correctly.

Response from "Go Local" command. This code is sent by the modem when it switches from the on-line state to the local command state. (It is usually the same as the acknowledge code.)

Result Code Wait (.01 sec). This setting is used to define, in 1/100 of a second, how long SmartWare Communications waits before looking for a result code. For example, if you specify 200, SmartWare waits 2 seconds after connection when you select Connection Answer before looking for the connection baud rate.


Modem Wakeup Sequences

This section contains nine settings used to specify modem commands, result codes, and wait times, which together are called the wakeup sequence. The wakeup sequences are issued by SmartWare when the modem name, state (answer or originate), or the Seconds to wait for carrier: specified in the communication profile have changed.

Both a command and a result must be specified if you want SmartWare to indicate when a command fails. If you do not specify a result code, there will be no way for SmartWare Communications to verify that the modem command executed properly.

When SmartWare Communications issues a command to the modem, it then follows these steps:
1. SmartWare clears both the transmit and receive queues; that is, it verifies that no characters are waiting to be received from a previous command and none of the previous command is left to be transmitted.
2. SmartWare transmits the command string to the modem.
3. SmartWare pauses for the duration of time specified in the Wait: length.
4. SmartWare checks the receive queue.
5. SmartWare compares the characters it found in the receive queue to the result code specified in the modem definition. If the two strings match, SmartWare Communications has verified that the command was executed correctly. If the result received and the result code specified in the modem definition do not match, SmartWare repeats steps 1 through 5 three times. If there is still no match on the third try, SmartWare Communications indicates that the command has failed.
NOTE: For commands that issue a guard sequence, there is an additional delay between steps 1 and 2.

The first nine commands, Wakeup 1 through Wakeup 9, are used to set initialization sequences for the modem. For best results with your modem, you should use commands that accomplish the following:
1. Clear the modem of any stored settings so that it always responds the same way during initialization. This command should be stored in the first wakeup sequence (Wakeup 1).
2. Force the result codes to match those defined in the Result Codes settings in the modem definition (i.e., words/verbose vs. numbers/terse).
3. Instruct the modem to respond to commands. (Some modems use a command that prevents them from responding.)
4. Instruct the modem to treat received characters as commands when Go Local commands are issued.
5. Instruct the modem to not automatically answer the phone if the modem switches are not already set to No Auto-Answer (unless you select the Answer Phone command on the Modem Definition menu.)


Modem Command Definitions

The second part of the modem command definitions include commands that SmartWare Communications sends to the modem to instruct it to perform certain functions. Like wakeup sequences, these commands also include a result code and a wait time.

Before Dial. This command is issued each time you dial another system. After you select Connection Dial, but before the command is actually executed, the Before Dial command is sent to the modem. The Before Dial command should be used to turn the modem speaker on until the connection is established and to set the duration that the modem should wait before hanging up if the carrier is lost. Five to ten seconds is generally sufficient.

Answer Phone. This command instructs the modem to answer the phone to establish a connection.
NOTE: SmartWare Communications does not generally use the "auto-answer" feature supplied by most modems because it would be incompatible with the profile setting specifying that SmartWare answer after a certain number of rings.

Abort Answer. This command is issued if you press Escape to abort the Connection Answer command. It also sets the modem to no auto-answer.

Before Answer. This command is issued to the modem immediately before the Connection Answer command is issued. It is issued at the baud rate specified in your communications profile settings to allow high speed modems to transmit at the highest baud rate possible.

Goto Carrier (Originate). This command is issued after you select the Set-Terminal Goto Carrier command in Originate State. It causes the modem to switch to on-line state and to issue the proper originate frequency.

Goto Carrier (Answer). This command is issued after you select the Set-Terminal Goto Carrier command in Answer State. It causes the modem to switch to on-line state and to issue the proper answer frequency.

Goto Voice. This command prevents disconnection while you and the remote computer operator pick up the phone when going to voice communication.

Hangup (modem control method). This command is issued when you select Connection Hangup and the modem control parameters have been set to use the modem control method.

Set Wait for Carrier. This command is issued whenever the wakeup commands (1-9) are issued and sets the amount of time the modem waits for a carrier signal before disconnecting. It is related to the amount of time specified in your communication profile under the Seconds to wait for carrier: setting (under Originate).

Go Local from Answer State. This string is issued when you are answering a call to instruct the modem to interpret characters as commands rather than as data.

Go Local from Originate State. This string is issued when you are originating a call to instruct the modem to interpret characters as commands rather than as data.

Before Go Local from Originate State. This command is issued whenever the wakeup sequence is issued in Originate State. It's function is to set the guard sequence while originating a call. The guard sequence instructs the modem whether to process data or commands.

Before Go Local from Answer State. This command is issued whenever the wakeup sequence is issued in Answer State. It's function is to set the guard sequence while answering a call. The guard sequence instructs the modem whether to process data or commands.

Legal Dial String Characters. Setting this command is optional. It is provided so you can extend the character set allowed by SmartWare Communications to accommodate your modem. The string you specify for this command is compared to the string you specified for the Dial Phone command.


Modem Control Parameters

The Modem Control Parameters are used to specify how and when the commands defined in the Modem Command Definitions are used.

Issue Wakeup (initialization sequence). These three parameters allow you to specify additional times when the wakeup sequence is sent to the modem. Currently, all predefined modem definitions set these parameters to no. They include After Hangup:, Before Dial:, and Before Answer:.

Hangup via removal of DTR (hardware method). If you specify yes for this setting, SmartWare Communications attempts to hang up the phone by removing the DTR signal for approximately one second. Currently, the predefined modem definitions are all set to yes. If you specify no, SmartWare issues the appropriate Go Local command followed by a Hangup command.

Sync Port to Connect Baud Rate. If this command is set to yes, after a connection is established SmartWare looks for a connect result code and will then switch to the baud rate specified by that result code. This allows SmartWare to more readily connect to multiple speed modems.

Initialize Modem Using Current Baud Rate. This parameter is set to no for all current predefined modem definitions. When this parameter is set to no, SmartWare issues all modem commands sent during the initialization sequence at 300 baud, 8 data bits, no parity, and 1 stop bit. If it is set to yes, SmartWare sends the initialization sequence at the baud rate, data bits, parity, and stop bits specified in the communication profile that is loaded. This parameter may be useful when using a high speed modem.

Allow Modem to Auto-Answer Phone. This parameter is set to no for all current predefined modem definitions. If you specify yes, SmartWare Communications will not issue the answer commands specified in the modem definition. For example, the setting for answering after a specified number of rings is ignored. Instead, SmartWare will expect the modem to automatically answer.
NOTE: If you set this parameter to yes, you may have to modify the wakeup commands.


Modem Undefine

The Set-Terminal Modem Undefine command erases a modem definition you have created with the Set-Terminal Modem Define command. When you execute this command, you must specify the modem definition to erase from a file prompter menu or type a modem definition filename and press Enter. You can identify modem definition files by the .mdv file extension.


Set-Terminal Paint

If you are using a color monitor, you can select Set-Terminal Paint to modify the colors of the Status and Terminal Windows.

The colors you select with these commands are stored with a communications profile. When the profile is loaded, the colors that were saved with it become the current colors. The current colors are saved when Set-Terminal Settings Save is executed.


Paint Status-Window

Select Set-Terminal Paint Status-Window to change the colors of the border, settings, or window area of the Status Window.


The Set-Terminal Paint Status-Window Border command changes the window border and settings borders to the specified color. You are prompted for a foreground color only. This command changes the color of all boxes on the Status Window.


The Set-Terminal Paint Status-Window Settings command changes the color of values you have specified in the current profile settings. You are prompted for a foreground color only.


The Set-Terminal Paint Status-Window Window command changes the color of the window background and settings titles or labels. You are prompted for a background color to change the window and a foreground color to change the settings titles.


Paint Terminal-Window

The Set-Terminal Paint Terminal-Window allows you to change the foreground and background colors of the Terminal Window.


Set-Terminal Settings

The Set-Terminal Settings commands are used to define, edit, load save, or undefine (delete) the current communication profile. For more information about settings in the Communication Profile menu, see the help section entitled Communication Profile Settings.


Settings Define

The Set-Terminal Settings Define command allows you to create or edit a profile using the Communication Profile definition menu. Any changes or edits to settings are saved to a file when you exit the Communication Profile menu by pressing F10.


 When you begin executing this command you are prompted for a profile filename. Enter a new filename at the prompt or select a profile to edit from the file prompter menu. You can identify a profile by its .ucp file extension.


Settings Edit

Set-Terminal Settings Edit allows you to change the current communication profile settings. Once you've executed this command, the Communication Profile definition menu is displayed. Use this menu to change the current profile settings.
IMPORTANT: Any settings that you change will not be saved to a file until you execute the Set-Terminal Settings Save command.

The Quick Key Alt-S allows you to execute the Set-Terminal Settings Edit command, displaying the Communication Profile menu.


Settings Load

When you select Set-Terminal Settings Load, you are prompted for a filename for a previously defined profile. The file prompter menu is displayed if the current directory contains any previously defined profiles. Select a profile with the arrow keys, or specify a profile that is in another directory and press Enter.

The Quick Key Alt-L allows you to start execution of the Set-Terminal Settings Load command.


Settings Save

The Set-Terminal Settings Save command saves the current settings into a file. When you execute this command you are prompted for a filename. Enter the filename and press Enter. If a profile is currently loaded, simply press Enter at the prompt, and the file will be updated with the current settings and any changes that may have been made.


Settings Undefine

The Set-Terminal Settings Undefine command deletes a profile that has been created previously.


Communication Profile Settings

After you select either the Set-Terminal Settings Edit command (editing the currently loaded settings) or the Set-Terminal Settings Define command (editing stored settings), the first screen of the Communication Profile definition menu is displayed.

To move between settings, move the pointer at the left side of the screen up or down using the arrow keys. There are several pages of profile settings. As you move the pointer down to the bottom of the screen, it automatically advances to the next page. You can also press Page-Up and Page-Down to move to different pages of the profile settings. Once you've moved the arrow to the setting you wish to select or edit, either type in a response, or for those settings that include options, press the Spacebar until the desired option is highlighted.

The six categories of settings are General, Originate, Answer, Modem, Text File Transmission, and Advanced User.


General Settings

The general settings are used in both Originate and Answer state. The items appear here as they do on the screen.

Name or Prompt. This setting has two functions, depending on which state SmartWare Communications is in. In Originate, it serves as a short description of the settings. If the settings are to be used when calling another computer, you can leave this option blank or type a short description of the settings. In Answer, this setting is sent to the calling system as a greeting.

State. The State setting allows you to choose Originate if you are calling another computer (using the Connection Dial command) or Answer if you are receiving calls from another computer (using the Connection Answer command).

If you load settings with Originate selected, you will be unable to execute the Connection Answer command because Originate is used only with the Connection Dial command. The opposite is true of Answer. If you load settings with Answer selected, you will be unable to execute the Connection Dial command.

Add Linefeeds. This setting allows you to specify whether an automatic linefeed should be executed after every carriage return received. Select yes at this setting for computer systems that do not send a linefeed at the end of a line.

This setting can be changed, after you connect, with the Set-Terminal Settings Edit command. If received lines overwrite each other, set this option to yes. If received lines are double spaced, set this option to no.

New Line Mode. This is related to the Add Linefeeds: setting. Select yes to add a carriage return to incoming linefeeds.

Autowrap. Select yes to move the cursor to the left margin of the succeeding line when characters overflow the right margin. Select no if you want characters to overwrite each other when they reach column 80.

Select Emulation Type. This setting specifies which type of terminal is emulated when the Terminal Window is displayed. The choices for this setting are:

1) Dumb Terminal. A "generic" terminal that performs no processing of received or transmitted signals.

2) ANSI Terminal. The ANSI terminal option recognizes the supported ANSI control sequences that are received and performs the appropriate terminal operation. This type of terminal emulation can display some graphics characters and colors.

3) VT100/102 and
4) VT52. These are terminals that are widely used in industry for various types of multi-user (mainframe) computers.

Keyboard Definition File. This setting is used to specify a keyboard redefinition and can be used in connection with the terminal emulation option. It allows the keys on your keyboard to be more closely matched to a familiar terminal or necessary keyboard layout.

Once the Keyboard Definition filename is entered, it will be loaded whenever this group of settings is loaded. The Keyboard Definition file must be created using the Set-Terminal Keyboard Define command.

Mask incoming data to seven bits. This setting specifies whether the high bit is set to zero on incoming characters. Select no if you want the characters to pass through unchanged. Select yes if you want all characters to be masked before passing through the Terminal filter or the Capture filter. This process is also referred to as high bit masking. This setting has no effect on the Xmodem protocol.

Enable XON/XOFF. This setting specifies whether SmartWare Communications uses XON/XOFF protocol. XON/XOFF protocol stops and starts the flow of data to prevent it from flowing faster than the receiving computer can process it. If this setting is enabled, your system watches for an XOFF character when it is sending data. If your system finds one, it stops transmitting until an XON character is received. Also, if characters are being received faster than your system can process them, SmartWare sends an XOFF character to the other system. It then sends an XON character as soon as it catches up. If this parameter is disabled, no special processing is done during sending or receiving. Normally, you should select yes for this setting.

Tab Spacing. This setting determines spacing when a tab character is received. You can enter any value between 3 and 20; the default is 8.

Terminal-Filter on. This setting allows the terminal filter to be turned on or off. If the filter is on, any characters selected on the terminal filter table are not displayed on your screen. If the filter is off, all received characters are passed directly to the screen.

Capture-Filter on. This setting allows the capture filter to be turned on or off. If the filter is on, any characters selected on the capture filter table are not captured. If the filter is off, all received characters are captured.

Dead time limit (seconds). This setting specifies the maximum time that a connection will be maintained when no activity occurs. Any value between 30 and 9,999 seconds may be entered. The dead time limit is used to detect when the other computer is no longer sending data. This setting can be particularly useful during project execution; if two computers are communicating automatically (using two projects), and one stops processing but stays on-line, this parameter disconnects the phone lines after the specified dead time limit.


Originate Settings

The originate settings are used when you are placing a call to another computer system. The items appear on the screen in the order shown below.

Number. The Number: setting is the phone number of the computer you are going to call. The number may include up to 40 characters. Currently, the characters 0123456789TPRtp,*#()-; can be included in this setting. This setting is not needed if your system will be answering another computer's call.

Originate Password. While originating a call, SmartWare Communications interprets receipt of a Ctrl-E (decimal value 5) from the answering system as a request for a password. SmartWare then answers with the string you specify in this setting.

Dial Prefix. This setting allows you to specify a different dial prefix. A dial prefix is the sequence of characters that is sent to the modem before the phone number is sent. This setting can be used to alter the dial prefix for activities such as pulse dialing, rather than tone dialing. It can also be used to define a dial prefix for a non-supported modem. A vertical bar (|) may be used to indicate a carriage return.

Dial Suffix. The Dial Suffix: setting allows you to specify a different dial suffix. A dial suffix is the sequence of characters that is sent to the modem after the phone number is sent. The vertical bar (|) may be used to indicate a carriage return.

Seconds to wait between redials. This setting specifies the number of seconds SmartWare Communications will wait before trying to dial a number again. It is used in conjunction with the Maximum number of re-dial attempts: setting. Any value between 0 and 9,999 may be entered.

Maximum number of re-dial attempts. This setting specifies the number of times the program will re-dial a busy number before terminating the Connection Dial command. Any value between 0 and 9,999 may be entered.

Seconds to wait for carrier. This setting specifies the number of seconds the program will wait to receive a carrier signal after a number is dialed. Any value between 1 and 255 seconds may be entered.


Answer Settings

The Answer Settings are used when you are receiving a call from another computer system. The items appear on the screen in the order shown below. These settings are ignored when you originate a call to another computer.

Receive/Transmit Password.
Receive Password.
Transmit Password.
Connect-Only Password. These four passwords are used to determine the originator's rights when SmartWare is in Remote Command Mode. If a password has been specified here, when the answering computer answers the phone the caller is prompted to enter a password. The password that is entered determines what rights the caller will have. Receive-only allows the caller to download files. Transmit-only allows the caller to upload files. Transmit/Receive allows the caller to upload or download files. Connect-only allows the caller to enter the system but not to upload or download files. If the passwords are left blank, the originator is not prompted.

In the absence of a password, Receive/Transmit access is granted, and the caller has access to all available remote commands. If there is password-protection, the answering computer grants the appropriate access level based on the password the originating computer sent when the phone was answered. Once access to the system is granted, the caller is allowed to execute a single command.

The following table shows each command with its shorthand format and the access level that permits it to be executed. Use the shorthand format of each command to simplify executing remote commands.

Command Format | Shorthand | Access Levels
Data Transmit Text-File (filename) | TT (filename) | T, R/T
Data Transmit Xmodem (filename) | TX (filename) | T, R/T
Data Receive Text-File (filename) | RT (filename) | R, R/T
Data Receive Xmodem (filename) | RX (filename) | R, R/T
Tools Directory Display (specification) | DI (specification) | R, T, R/T
Help | ? | C, R, T, R/T

The commands used to transmit and receive are the same as those used in Command Mode. The Tools Directory Display (DI) command displays the names of the files, the date and time they were created, their sizes, and their transmission times. The file specification may include an optional path or wild cards.

The Help command displays a summary of the commands available in Remote Command Mode.

After the remote command has been executed, the system returns to normal Terminal Mode. Another remote command may be executed by repeating the procedure.

See the section called Remote Command Mode in the Communications Manual for additional information.

Number of rings. This setting is used only in Answer state. It designates how many rings are needed before SmartWare Communications answers the phone. Any number between 0 and 10 may be entered. This setting will be ignored if you have set your modem to automatically answer in the modem definition file.

Connection time limit (minutes). This setting specifies the maximum time that the system will remain on-line after answering the phone and is used to prevent one caller from tying up the system. Any value between 1 and 9,999 minutes may be entered.


Modem Settings

The modem settings are used to specify the modem type and corresponding parameters. The items appear on the screen in the order shown below.

Select Modem Type. This setting allows you to select the type of modem you are using from a prompter when you press F6. Select Null Modem if your computer is directly connected to another computer by a serial cable.

Modem Port. This setting defines which communication port is to be used. Select either Serial-1 or Serial-2 depending on the port to which your cable is connected.

Baud Rate. The Baud Rate: setting determines how fast the data is sent. The terms "baud rate" and "bits per second" are equivalent. Bits per second describes how many computer digits (1s and 0s) are being transferred per second. The baud rates of two systems communicating with each other must be the same, or your screen may begin filling up with "garbage" characters. Normally, it is best to set the baud rate at the highest speed that your modem supports. With most modems, if a faster baud rate modem connects to a slower modem, the faster modem will automatically adjust its speed downward to match the slower modem's baud rate. If not, and you begin receiving garbage, change the baud rate and re-connect.

Data Bits. The Data Bits: setting allows you to change the number of data bits sent for each character. Use the data bit setting required by the remote computer.

There is no general rule for how many data bits to use, however, if you plan to use parity checking, you must generally choose 7 data bits or less. Check with the manuals or operator of the computer system you are going to be communicating with for additional information.

Parity. Parity is a form of error checking that can be performed on each byte that is sent. Many computer systems ignore the parity bit, although some systems require it. Check with the manuals or the operator of the remote computer for the correct settings, if necessary.

Stop bits. This setting allows you to set the number of stop bits sent after each byte. Normally, you would use 1 stop bit.

Duplex. The Duplex: setting specifies which computer system is responsible for echoing the typed characters. The general rule is that the originating computer uses full duplex, and the answering computer uses half duplex. You can also use the Quick Key Alt-U to change the duplex.


Text File Transmission

These options affect only the Data Transmit Text-File command. The items appear on the screen in the following order:

Expand tabs. This setting determines whether tabs within the text file are transmitted as tab characters or as spaces. If you select yes for this setting, tabs in the text file are transmitted as spaces (ASCII value 32); if you select no, tabs are transmitted as tab characters (ASCII value 9). This setting also specifies that transmitted tabs be expanded to the tab width selected in the Tab Spacing: option of the General Settings.

Pad blank lines. This setting specifies whether to pad blank lines with a space before transmitting them. Padding is required by some mainframe computer systems. If you select yes for this setting, any blank lines transmitted in a text file will have a space inserted before the carriage return. If you select no, blank lines are transmitted as carriage returns, with or without linefeeds, as determined by the Filter Linefeeds: setting.

Filter Linefeeds. In a standard text file created in SmartWare, each line is terminated with a combination of two characters, a carriage return and a linefeed. The linefeed filter setting specifies whether linefeeds are filtered out of transmitted data. Some computers expect only a carriage return, rather than a linefeed and a carriage return, in which case linefeeds must be filtered out. If you select yes for this setting, linefeeds are not transmitted in text files. If you select no, linefeeds are transmitted.

Select Character Delay. Use this setting to specify the amount of time SmartWare Communications waits between transmitting characters to the remote computer. Some computer systems are not able to accept characters as fast as your system can send them, so you should select a character delay. The No Delay option bypasses all character delays and is the default setting. The Wait for Echo option causes the program to wait until the previous character is echoed back before transmitting the next character. The selections for character delay are:
*** 0 -- No delay between characters. Your computer will send them as fast as it can.
** 1 -- Wait for echo. Your computer will wait for the last character it sent to be echoed (sent back) by the remote computer before it sends the next character.
** # -- A delay time period that you select. If a number greater than 1 is entered, it represents the number of tenths of a second to delay after each character. For example, if 10 is entered, the program pauses one second between the transmission of each character.

Select Line Delay. The Line Delay option specifies how much time SmartWare Communications waits after a complete line is transmitted.
*** 0 -- No delay. There will be no delay between the transmission of each line. Your computer will send each line as fast as it can.
** 1 -- Wait for CR. When you select this option, your computer will wait for the remote computer to send a carriage return before sending the next line.
** 2 -- Wait for User. When you select this option, your computer stops after each line and waits for the you to press a key.
** 3 -- Wait for Prompt. The Prompt option stops after each line and waits for the remote computer to send a specified prompt. If you select this option you must also specify the prompt in the Prompt to Wait For: setting. You can make this prompt contain non-printable characters by entering them with a preceding backslash, followed by the ASCII value (decimal) of the character.

Example:

     \10 waits for a line feed character (ASCII 10)
     \92\13\10 waits for backslash (ASCII 92), carriage return (ASCII 13), linefeed (ASCII 10)
     \109 waits for "m" (ASCII 109)
*** # -- Delay Time in 1/10 second. The Delay option allows you to enter a number representing how many tenths of a second to delay after each line is sent.

End of File delay time (seconds). Use this setting to specify how long SmartWare Communications waits before terminating the Data Transmit Text-File command when no characters are being received.


Advanced User Settings

Debug Mode. This setting is used for debugging communications problems. When the program is in debugging mode, the Terminal Filter and the high-bit mask are disabled. Incoming data is displayed in decimal, hexadecimal, or character format.

Off is the normal setting. The remaining three options are used when debugging mode is desired. The Character option displays incoming data as characters. The Decimal option displays incoming data as decimal numbers. The Hex option displays incoming data as hexadecimal numbers.

Forced Local Echo. When set to on, this setting forces the data you are transmitting to be echoed to the screen, regardless of the duplex setting specified.

Maximum number of Xmodem retries. This setting is for Xmodem protocol only. Enter a number between 9 and 9,999 to specify the number of errors that will be tolerated during an Xmodem file transfer before transmission is cancelled.

Break signal length (in hundredths of second). Use this setting to specify the length of a break signal (Alt-B is the default Break Key). Enter the duration of the break signal in hundredths of a second; the default break signal length is one character frame. The Break Key is definable in a Keyboard Definition.
NOTE: To edit settings, use the Set-Terminal Settings Edit command. If you want to save any edited settings, use the Set-Terminal Settings Save command to store these settings in a file for later use.

Set-Terminal Duplex
Set-Terminal Filter
Set-Terminal Keyboard
Set-Terminal Modem
Connection Answer
Connection Dial
Data Receive
Data Transmit


Connection Commands

The Connection commands are used to control the connection of your local computer to the remote computer.

Options for Connection include:

Answer. Answers incoming calls.
Dial. Dials a remote computer system.
Hangup. Disconnects a communication link.


Connection Answer

Select Connection Answer to answer an incoming call from a remote computer system. Before selecting this command, you must have loaded a communication profile that contains the appropriate answer settings. You can also use the Quick Key Alt-A to immediately execute the Connection Answer command.

Once you've selected Connection Answer, your system will be ready to receive an incoming call. Press {Escape} to cancel Connection Answer.

Connection Answer automatically forces SmartWare Communications into half duplex so the caller can see what is typed. If this is not suitable, you may select the Set-Terminal Duplex Full command after the phone has been answered to change to full duplex.


Related Profile Settings

Connection Answer must be used in conjunction with a communication profile. The General communication profile settings that affect operation of Connection Answer include Name or Prompt: and State: (Originate or Answer). The Answer settings that affect operation include the four password settings, Number of rings:, and Connection time limit:. For specific information about these settings, see the help section on the "Set-Terminal Settings" commands.

Connection Dial
Hangup
Set-Terminal Settings


Connection Dial

Use Connection Dial to originate a call to a remote computer system. Before selecting this command, you must have loaded a communication profile that contains the appropriate Originate settings, including a modem selection other than Null Modem.

Options for Connection Dial include Carrier and Voice.


Dial Carrier

Use the Connection Dial Carrier command when you expect a computer to answer with a carrier signal. When you execute this command, you are prompted for a number to dial. If you have specified a number in the communication profile, simply press Enter to begin the call. If there is no number specified in the profile, you will see the message There is no number to dial in the current profile. You must then type in a number.

The Quick Key Alt-D allows you to execute the Connection Dial Carrier command, using the number currently contained in the settings. If no number has been specified, you must select Dial from the menu and supply a number at the prompt or edit the current profile.


Related Profile Settings

Connection Dial Carrier must be used in conjunction with a communication profile. The General communication profile setting that affects operation of Connection Answer includes State:. The Originate settings that affect operation include Number:, Originate Password:, Seconds to wait between re-dials:, Maximum Number of re-dial attempts:, and Seconds to wait for carrier:. For specific information about these settings, see the help section on the "Set-Terminal Settings" commands.


Dial Voice

Use the Dial Voice command when you wish to talk with the remote computer operator before making a data connection. Once you've selected Dial Voice, you are prompted for a phone number. Both you and the person you are calling must have voice phones connected to your modems.

If you have loaded a profile that initializes the modem, you can switch to data transfer after the connection is established by selecting the Set-Terminal Goto Carrier command.


Related Profile Settings

Connection Dial Voice must be used in conjunction with a communication profile. The General communication profile setting that affects operation of Connection Dial includes State:. The Originate settings that affect operation include Number:, Seconds to wait between re-dials:, and Maximum Number of re-dial attempts:. For specific information about these settings, see the help section on the "Set-Terminal Settings" commands.

Connection Answer
Set-Terminal Settings


Connection Hangup

Select the Connection Hangup command to disconnect a communication link with another system. The Quick Key Alt-H allows you to immediately execute the Hangup command.

Connection Dial
Connection Answer


Data Commands

Use the Data commands to control data that you are transmitting or receiving.

Data provides the following options:

Capture. Retrieves incoming data and sends it to the buffer, a file, or a printer.
Receive. Receives data files from another system.
Transmit. Sends data files to another system.
Get. Takes the next character or line that is received from the Terminal Window and places it into a project variable.
Match. Halts a project file until a specified sequence of characters is received.
Output. Sends a specified set of characters directly to the modem port.
Send. Sends files received with SmartWare Communications to other SmartWare modules.
Format. Define or undefine a file containing a specified conversion format for text.
Xfer-Time. Estimates time to transmit a file at the current baud rate.


Data Capture

Select Data Capture to "trap" incoming text into a buffer (temporary storage), file, or printer.

All characters are filtered through the capture filter if it is enabled in the current settings. A capture filter is attached to each profile.


Capture Buffer

Select Data Capture Buffer to capture incoming data and store it in a buffer. The buffer is memory that is available for storing data temporarily. The Quick Key F5 works as a toggle so you can choose to capture to the buffer or not.

The following options are available for Data Capture Buffer:


 Begin. Select this option to begin capturing data to the buffer. The Status Line at the bottom of the screen indicates the buffer status and shows the amount of memory left for data storage.

If the buffer becomes full while capturing data, a message appears indicating that the buffer is full. You are asked whether to save the data in the buffer. You can then choose to clear the buffer by typing n, or you can type y to save the data to a file. You must then enter a name for a file where the data can be saved. If you name a file that already exists, you can choose to overwrite the file by typing o, or you can append the buffer data to the file by typing a. Press Escape to abort the command, if necessary.


 Clear. Select Clear to erase the contents of the buffer. If there is currently data stored in the buffer, the prompt Save buffered text (y/n), appears.

If you type n in response to the prompt, the data in the buffer will not be saved and the buffer will be cleared. If you type y, you are prompted to enter a filename. If you name a file that already exists, you can choose to overwrite the file by typing o, or you can append the buffer data to the file by typing a. Press Escape to abort the command, if necessary. In either case, after clearing the buffer, data capture is turned off. You can begin saving to the buffer again by selecting Data Capture Buffer Begin.


 End. Select this option to stop saving text to the buffer. Data capture is suspended when you select this option, and no additional incoming text is added to the buffer until you execute Data Capture Buffer Begin.


 Save. Select this command to store the current buffer contents into a file. When you execute this command, you are prompted to enter a filename. If you name a file that already exists, you can choose to overwrite the file by typing o, or you can append the buffer data to the file by typing a. Press Escape to abort the command, if necessary.


 View. Select View to display the current contents of the capture buffer on your screen. You can scroll through the contents of the buffer by pressing Page-Up, Page-Down, Up-Arrow, or Down-Arrow. Press Escape to stop viewing the contents of the buffer. Press the Quick Key Alt-V to immediately execute the Data Capture Buffer View command.


Capture File

Select Data Capture File to capture data to a file. The Quick Key F7 works as a toggle so you can choose to capture to a file or not. Options for this command are Begin and End.


 Begin. Select Data Capture File Begin to begin saving captured data to a file. You are prompted to enter a filename. You can choose to append new data to the last file captured by pressing Enter instead of entering a filename. However, if no file has been captured to since you entered SmartWare Communications, you will see an Invalid Filename message. Press any key to clear the message. Select Data Capture File Begin again and enter a valid filename, including a full path name if you want to save the file somewhere other than the current directory. If you do not enter a path name, the file will be saved in the current directory.

If you name a file that already exists, you can choose to overwrite the file by typing o, or you can append the data to the file by typing a. Press Escape to abort the command, if necessary.


 End. Select this option to stop capturing data to a file. You can continue capturing to the same file by selecting Data Capture File Begin and pressing Enter at the Enter filename prompt. You can also continue by pressing F7.


Capture Printer

Select Data Capture Printer to control the capture of incoming text to a printer. The Quick Key F6 acts as a toggle so you can choose to capture to a printer or not. Options include Begin and End to start or stop data capture.

Set-Terminal Filters
Set-Terminal Settings


Data Receive

Use Data Receive to receive a file sent from another computer system. The Quick Key Alt-R allows you to start execution of the Data Receive command. Options for this command include Text-File and Xmodem.


Receive Text-File

Select Data Receive Text-File to receive a file in text file format, also known as standard ASCII file format. Text files contain only printable characters. Once you've received a text file, you can convert it into a SmartWare document, worksheet, or data-file within each SmartWare module. Text files can be edited using SmartWare's text-editor, found by selecting the Tools Text-Editor command.


 Once you've selected the Text-File protocol, you are prompted to enter a filename for the incoming file. The filename can also include a path, if necessary. You can select a filename that is different from the name under which the file is stored at the transmitting computer. The name that you enter here does not change the file's name at the transmitting computer. If you enter a filename that already exists, you can choose to overwrite the current file with new data, or append the new data to the end of the current file. Type o to overwrite the file; type a to append data to the end of the existing file.


 After you name the file and press Enter, you are prompted to Wait for expression:. Entering an expression is optional. You can enter an expression (a string of characters) that will be sent to the transmitting computer. The receiving computer will not accept a transmitted text file until the expression has been echoed back to it from the transmitting computer. This allows you to know whether the transmitting computer is ready to transmit the text file.

Expressions can contain any valid SmartWare expression that evaluates to a text string. If you enter a string, be certain to enclose it in quotation marks. For more information about expressions, refer to Formula Reference Manual.

If you do not enter an expression, SmartWare begins receiving data immediately. SmartWare Communications saves received data under the filename you specified until an "end-of-file" marker (typically a CTRL-Z) is received from the transmitting computer.

During execution of the Data Receive Text-File command, the capture filter can be used to filter any unwanted characters. If the high-bit mask is turned on (in the current settings), any characters above ASCII decimal 127 are stripped of their highest bit. To receive files containing eight bit data, use the Data Receive Xmodem command, or make sure that the high-bit mask is disabled in the current settings.


Receive Xmodem

Select Data Receive Xmodem to receive files containing any type of data, for example, binary files, executable files, SmartWare documents, worksheets, and text files.

Xmodem protocol checks all data being received for errors. If errors are detected, the data is transmitted again until an error-free transmission occurs. The Xmodem protocol should be used most of the time because of its error checking and correcting capabilities.


 Once you've selected Data Receive Xmodem, you are prompted to enter a filename for the incoming file. The filename can also include a path, if necessary. You can select a filename that is different from the name under which the file is stored at the transmitting computer. The name that you enter here does not change the file's name at the transmitting computer. If you enter a filename that already exists, the prompt File already exists. Overwrite it (y/n) appears. Type y to overwrite the existing file with new data. Type n to stop execution of the command. If you still want to receive the incoming file while retaining the old file, you must enter a different name for the incoming file.

When the file is being received, the following information appears on the status screen:

        Receiving file: text.doc
        Current block   a
        Errors
           Current block   b
           Total   c

The current block being received is indicated by "a"; "b" is the number of errors that have been detected in the current block; and "c" is the number of total errors that have been detected in the received file. If errors are detected, the block is retransmitted until an error-free block is received.

If no transmission is received within two minutes after the Data Receive Xmodem command is executed, the command is halted.
NOTE: SmartWare Communications checks for errors using Xmodem checksum.

Data Receive Xmodem always receives with 8 data bits, no parity, and 1 stop bit. It automatically switches to those settings regardless of the number of data bits defined in the current settings. When the file is received, the original settings are returned.
IMPORTANT: Both the transmitting and receiving computers must be using the same transmission protocol.

Set-Terminal Settings


Data Transmit

Use Data Transmit to transmit a file to another computer system. The Quick Key Alt-T allows you to start execution of the Data Transmit command. Options for this command include Text-File and Xmodem.


Transmit Text-File

Select Data Transmit Text-File to transmit a file in text file format, also known as standard ASCII file format. Text files contain only printable characters. If you want to transmit a SmartWare document, worksheet, or data-file, you must first convert it to a text file before transmitting it using Text-File protocol.


 Once you've selected the Text-File protocol, you are prompted to enter the name of the file you want to transmit. The filename can also include a path, if necessary. Enter the filename and press Enter to begin transmission.


Transmit Xmodem

Select Data Transmit Xmodem to transmit files containing any type of data, for example, binary files, executable files, SmartWare documents, worksheets, and text files. Enter the name of the file to transmit.

Xmodem protocol checks all data being transmitted for errors. If errors are detected, the data is transmitted again until an error-free transmission occurs. The Xmodem protocol should be used most of the time because of its error checking and correcting capabilities.

When a file is being transmitted with the Xmodem protocol the following information appears on the Status Window:

        Sending file: text.doc

        Xmit time (mins.):   a
        Total blocks:   b

        Current block:   c
        Complete:   d

The estimated number of minutes needed to send the file is represented by "a"; "b" is the total number of blocks; "c" is the current block being sent; and "d" is the percentage of the transmission completed.

Data Transmit Xmodem always transmits with 8 data bits, no parity, and 1 stop bit. It automatically switches to those settings regardless of the number of data bits defined in the current settings. When transmission has been completed, the original settings are returned.


Related Profile Settings

The Maximum Number of Xmodem Retries: option under the Advanced User Settings on the Communication Profile definition menu controls the total number of times a Data Transmit Xmodem command will attempt to retransmit blocks during transmission. The number of retries can be between 9 and 9,999. If the number of retries exceeds the number that you enter here, the command will be aborted. Transmission will also halt if the number of errors for one block exceeds the maximum of 9 errors per block.
NOTE: The number of retries is the total number for all blocks allowed during a single Xmodem file transfer.

If you cannot obtain an error-free transmission of a given file after the number of re-tries specified in the current settings, there may be severe noise on the line.
IMPORTANT: Both the transmitting and receiving computers must be using Xmodem checksum.

Set-Terminal Settings
Data Xfer-Time


Data Get

The Data Get commands are used primarily in Project Processing. Data Get takes the next character or line that is received from the Terminal Window and places it into a project variable.

For example, you could create a project file that calls Dow Jones and searches for a particular stock price. You could then use Data Get Line to put that stock quote into a project variable that can then be used in a project file designed to track stock trends.
IMPORTANT: If a Remote Command Mode request, Ctrl-C, is received while your system is gathering characters or lines into a project variable, the Data Get command is suspended and all data gathered up to that point is lost. The remote command is then executed. Once the command is executed, the Data Get command begins again. You can abort operation of a Data Get command by pressing Escape locally.

The Quick Key Alt-G allows you to start execution of the Data Get command. Options include Character and Line.

The syntax for the Data Get commands is as follows:

     Data Get Character variable <varname>
     Data Get Line variable <varname>

where <varname> is a project variable.


Get Character

The Data Get Character commands indicate that the next character that is received on the Terminal Window should be placed in a variable. Data Get Character stops once the next character is detected. The variables you can use are described in the section titled Variables.


Get Line

The Data Get Line commands indicate that the next line that is received on the Terminal Window should be placed in a variable. Data Get Line stops after a carriage return is detected or when it receives 254 characters, which is the maximum number of characters a variable can contain. The carriage return is included in the variable. The variables you can use are described in the section titled Variables.


Variables

After selecting the Character or Line option, you are prompted to Enter a variable name. Enter the name of a project file variable that is used in the project being constructed.

Refer to Project Processing for more information about project files and variables.

Data Match
Data Output


Data Match

The Data Match command is normally used in Project Processing. This command causes the project to pause until the specified sequence of characters is received. Project execution continues only when the specified characters are received.

When you select Data Match, you are prompted to Enter a character expression to match. Expressions can contain any valid SmartWare parseable expression that evaluates to a text string. If you enter a string, be certain to enclose it in quotation marks. For more information about expressions, refer to Formula Reference Manual.
IMPORTANT: If a Remote Command Mode request, Ctrl-C, is received while your system is searching for characters to place into a project variable, the Data Match command is suspended and all data gathered up to that point is lost. The remote command is then executed. Once the command is executed, the Data Match command begins again. You can abort operation of a Data Match command by pressing Escape locally.

Be aware that although the Data Match command has suspended command execution, capturing to the buffer, printer, or a file does continue.

The Quick Key Alt-M allows you to start execution of the Data Match command; you are prompted for character(s) to match.


Related Profile Settings

If you have set the Terminal-Filter: setting to on in the current profile, all characters are filtered through the Terminal Filter table before being checked by the Data Match command.
NOTE: Make certain that the Data Match command is not searching for a filtered character or a character that will be changed by the high-bit mask. If either of these situations exists, the match will never occur.

Data Get
Data Output


Data Output

Data Output sends a specified set of characters directly to the serial port configured as your modem port. It is normally used in Project Processing to allow an unattended computer to send text (e.g., an access code or a password) to the other system. It is very useful in creating automatic login projects.
Comment: Data Output can be used to send special characters to the remote computer; for example, Data Output chr(27) sends Escape. This is useful if Escape or other keys are defined as command keys.

The Quick Key Alt-C allows you to start execution of the Data Output command.


 When you select Data Output, you are prompted to Enter a character expression to output. Expressions can contain any valid SmartWare expression that evaluates to a text string. If you enter a string, be certain to enclose it in quotation marks.

If you press Enter without entering a text expression (no characters are entered), a carriage return is sent to the serial port.

Data Get
Data Match


Data Send

Select Data Send to send data from SmartWare Communications to another SmartWare module. If you have purchased and installed all of SmartWare, your options include Database, Spreadsheet, and Wordprocessor. Once you've selected the option for the destination module, specify whether you are sending data that is currently stored in the capture buffer or in a file.


 The data may be sent unformatted (in the same format it currently exists in the file) or formatted in a standard SmartWare format. You are then prompted to Enter project file for next application. You can enter the name of a project file in the application to which you are sending. Project files can be used to automate your data handling. If you enter the name of a project created in the next application, it will be executed when the data is transferred. For more information about project files, see Project Processing. If you are not using a project file, simply press {Enter} at the prompt.


 Un-Formatted. Select this option to send data as a standard text file. This is most often used when sending to SmartWare Word Processor.

Data Format
Remember


Send module Buffer

Select the Data Send module Buffer commands to send data currently in the buffer to the specified module.


 Formatted-By. This option allows you to specify a formatting definition to be used in translating the data as it is sent. This option can only be used with files that have a fixed format, such as a file produced by printing a report to a text file. It is most often used when sending to SmartWare Database or SmartWare Spreadsheet. The format file must have been previously defined using the Data Format Define command. When you select this option, you are prompted to Enter format filename. You can include a path name.


 Un-Formatted. Select this option to send data as it appears in the buffer. This is most often used when sending to SmartWare Word Processor.


Send module File

Select Data Send module File to send data from a file to the specified module. You are prompted for a filename.


 Formatted-By. This option allows you to specify a formatting definition to be used in translating the data as it is sent. This option can only be used with files that have a fixed format, such as a file produced by printing a report to a text file. It is most often used when sending to SmartWare Database or SmartWare Spreadsheet. The format file must have been previously defined using the Data Format Define command.


 When you select Data Send module File Formatted-By, you are prompted to Enter format filename. You must type the filename of a format definition or select a filename from the prompter list and press Enter. You can include a path name with the filename.


Data Format

Select Data Format to define or undefine a file containing a specified conversion format for text. The conversion format translates a text file into database fields and records or worksheet rows and columns. This conversion format is used in conjunction with the Data Send command. Options for Data Format include Define and Undefine.
NOTE: Your data is formatted as it is sent, but your stored file is not permanently altered.


Format Define

When you select Data Format Define, you are prompted for a format definition filename. Enter a new filename (a format definition you wish to create) or select an existing filename (one you wish to edit) from the prompter list and press Enter. The Format Definition menu is then displayed.


Format Definition Menu

The Format Definition menu consists of 25 groups of data format specifications. You can think of each format specification as a rule that is applied to the text being sent. Each group consists of five specifications:

           Field start column:
           Field end column:
           Field type:  Ignored  Text  Value

           Read next input line:  Yes  No
           Start new output line:  Yes  No

For each group you must define the starting and ending column of each field in the text file with Field start column: and Field end column:. Each prompt can contain a number from 1 to 255.
NOTE: The values you specify at these two prompts must be between 1 and 255; if you select anything other than a number in that range, an error message will be displayed. To change a value select {F2} to edit the field.

Next, you can specify the field type to be either value or text, or you can ignore it.

The last two options, Read next input line: and Start new output line:, specify how the text file will be divided into rows or records.

Three formats can be defined, as follow:
1. Convert each line into one spreadsheet row or one database record.

For this format, always set both the Read next input line: and Start new output line: prompts to No.
2. Convert each line into two or more spreadsheet rows or database records.

For the second format, set the Start new output line: prompt to Yes after specifying the number of columns to convert.

For example, if you have 15 columns in a text file, and you want it divided into three records per line, you would set the Start new output line: prompt to Yes on the fifth and tenth groups. Here is an example of the first line of the text file:

     100_AAA_200_BBB_300_110_CCC_210_DDD_310_120_EEE_220_FFF  320

After this example line is converted, the format looks like this:

     100  "AAA"  200  "BBB"  300
     110  "CCC"  210  "DDD"  310
     120  "EEE"  220  "FFF"  320

The format definition is shown here:

     (1)   Field start column:  1
           _Field end column:  4
           _Field type:  Value

           Read next input line:  No
           Start new output line:  No

     (2)   Field start column:  5
           _Field end column:  7
           _Field type:  Text

           Read next input line:  No
           Start new output line:  No

     (3)   Field start column:  8
           _Field end column:  12
           _Field type:  Value

           Read next input line:  No
           Start new output line:  No

     (4)   Field start column:  13
           _Field end column:  15
           _Field type:  Text

           Read next input line:  No
           Start new output line:  No

     (5)   Field start column:  16
           _Field end column:  20
           _Field type:  Value

           Read next input line:  No
           Start new output line:  Yes

     (6)   Field start column:  21
           _Field end column:  24
           _Field type:  Value

           Read next input line:  No
           Start new output line:  No
3. Convert one or more text lines into one spreadsheet row or one database record.

For the third format set the Read next input line: prompt to Yes after each group of columns that make up a row.

For example, if your text file has five columns, and you want each row to consist of a group of three lines, you would set the Read next input line: prompt to Yes on the fifth and tenth groups. Following is an example of the first nine lines of a text file.

     100  AAA  300  BBB  500
     110  CCC  310  DDD  510
     120  EEE  320  FFF  520
     140  GGG  340  HHH  540
     150  III  350  JJJ  550
     160  KKK  360  LLL  560
     170  MMM  370  NNN  570
     180  OOO  380  PPP  580
     190  QQQ  390  RRR  590

Here is what a portion of each line will look like after these lines are converted:

     100_"AAA"_300_"BBB"_500_110_"CCC"_310_"DDD"_510_120_"EEE"
     140_"GGG"_340_"HHH"_540_150_"III"_350_"JJJ"_550_160_"KKK"
     170_"MMM"_370_"NNN"_570_180_"OOO"_380_"PPP"_580_190_"QQQ"

The format definition for this format follows:

     (1)   Field start column:  1
           _Field end column:  4
           _Field type:  Value

           Read next input line:  No
           Start new output line:  No

     (2)   Field start column:  5
           _Field end column:  7
           _Field type:  Text

           Read next input line:  No
           Start new output line:  No

     (3)   Field start column:  8
           _Field end column:  12
           _Field type:  Value

           Read next input line:  No
           Start new output line:  No

     (4)   Field start column:  13
           _Field end column:  15
           _Field type:  Text

           Read next input line:  No
           Start new output line:  No

     (5)   Field start column:  16
           _Field end column:  19
           _Field type:  Value

           Read next input line:  Yes
           Start new output line:  No

     (6)   Field start column:  1
           _Field end column:  4
           _Field type:  Value

           Read next input line:  No
           Start new output line:  No


Sending Formatted Data

When you select Data Send <module> Formatted-By,the data formatting specifications are used in sequential order on the text file specified.

The first line of text is read; next, all 25 data format specification groups are used to format the output line, which is written to a temporary file. The next line of text from the file is read in and the process is repeated until all 25 data format specification groups are used. This continues until all lines of the text file have been read and formatted. At that point, the SmartWare module the file was sent to is activated.

You should remember the following information when you define a format for sending data. Each line or group of lines must have the same column spacing, and each column must contain the same data type. Columns in the line can be processed twice. Read next input line: is used when a group of items (a record) is contained on multiple lines and you wish to combine the items into one unit of information (record) in the output. By default, a new line is read and a new output line is started during each cycle of the Send operation. Start new output line: is used when the input text has multiple units of information (e.g., multiple records) on one line.


Format Undefine

This command removes a previously created format definition. When you execute this command, you are prompted for a format definition filename. Enter a filename to be erased.

Data Send


Data Xfer-Time

Select Data Xfer-Time to calculate the approximate minimum time required to transmit a file. The calculation is based on the current baud rate and the byte size of the file.


 When you execute Data Xfer-Time, you are prompted for a filename. Enter a filename and path, if necessary. The approximate time required to transmit that file (in minutes) will be displayed on your screen.

The Quick Key Alt-Q allows you to start execution of the Data Xfer-Time command.

Transfer time can be approximated with the following SmartWare formula:

     round((( (<file size> * <packet>) / <baud rate>) / 60), 2)

Where:

<file size> = The size of the file in bytes.
Comment: If you want Xmodem times use 8 data bits, 1 stop bit, and no parity (i.e., <packet> = 10).

<packet> = (1 + data-bits + parity-bit + stop-bits). Data-bits and stop-bits correspond to the values being used in your settings. If your parity is none, parity-bit = 0. If your parity is even, odd, mark, or space, parity-bit = 1.

<baud rate> = The current baud rate setting of the currently loaded settings.

This formula calculates the transfer time at a given baud rate, assuming there are no errors or retransmissions. Be sure to use the correct baud rate for your system. The file size is multiplied by <packet> to yield bits and divided by bits per second (baud). This gives the time for transfer in seconds. Seconds divided by 60 equals transfer time in minutes.
NOTE: The calculated times will be approximate.

Data Transmit


Tools Commands

The Tools commands provide various file manipulation capabilities. You can copy, erase, print, or rename files; manipulate directories; or set preferences for global, hardware, or Communications preferences. You can also use the Tools Calculator or define macros.

Only the Tools Preferences Communications commands will be discussed here. Refer to Software System Manual for detailed information on using the other Tools commands.


Tools Preferences

The Tools Preferences commands are used to configure default settings. When you select Tools Preferences, you must specify whether you want to set Communications, Global, or Hardware defaults. For information on the Global and Hardware options, refer to the Software System Manual.


Preferences Communications

When you select Tools Preferences Communications, SmartWare displays the Communications Preferences definition menu, containing specification items that control how SmartWare Communications performs whenever it is accessed. Any changes that you make to the specifications on this definition menu become the performance defaults the next time you enter SmartWare Communications.

Access the Communications Preferences definition menu to change the following Communications settings.

Communications Data Path. Enter the data path to be used for storing and retrieving files. The data path specified here overrides the data path specified in the Global Preferences Definition Menu. Unless another path is specified during a save or load operation, or by selecting Tools Directory New-Directory, SmartWare always utilizes the Communications data path when storing or retrieving files.

Automatic Load of Settings. Use this setting to automatically load a communications profile whenever you enter SmartWare Communications.

Automatic Load of Macro File. A macro file contains a set of character output redefinitions for one or more keyboard keys. This menu item allows you to specify the name of a macro file to automatically load whenever SmartWare Communications is accessed. The macro filename may be preceded by a path if the file is not located on the current path.

Default Keyboard Definitions. Select the Keyboard Definition that will be used as a default when SmartWare Communications is using terminal emulation.

Display Modem Commands/Results. This setting allows you to see the command code sequences that SmartWare Communications sends to your modem and can be used in conjunction with the Set-Terminal Modem Define command. When you select yes for this setting, the following information is displayed on the screen as the modem is initialized:

        <Command sequence sent to modem>
        <Expected results>
        <Actual results>
        <Wait times>

When the command is finished the screen is restored to normal.
NOTE: If the command executes properly, lines 2 and 3 are the same. If the command does not execute properly, lines 2 and 3 will not be the same.

On-line Clock. This option determines if the on-line clock is displayed in the lower right corner of you terminal screen. When the clock is displayed it shows how long the current connection has existed. The clock is reset when you hang up or otherwise break the connection.

Project File to Run on Entry. A project file contains a set of command format statements, including application commands and project commands, that perform some predetermined activity. This menu item allows you to specify the name of a project file to automatically execute whenever SmartWare Communications is accessed. The project filename may be preceded by a path if the file is not located in the current directory.


Help Tutorial

Help Tutorial invokes the tutorial for the current module. You may use the tutorial in a step-by-step process to learn the entire module, or you may use it to learn about one particular aspect of the module. If the Communications Tutorial was not installed on your system, use the Changes and Additions option of the Install program to add it at any time.

At the Okay to unload files without saving to run the tutorial? (y/n) prompt, type n and press Enter if you have files that need to be saved first. Otherwise, type y and press Enter.

Enter your name at the prompt Ask for Name:.

To use the tutorial as a step-by-step process, select the first option on the tutorial's main menu. If you want to learn about something specific, select the appropriate topic.

Refer to the on-line tutorial information for additional instructions.


Remember Commands

The Remember keywords allow you to create and run Project Processing files. Project Processing is an automated method of executing a sequence of commands.

Refer to Project Processing for detailed information on executing the Remember commands.


Quit Commands

The Quit keywords allow you to leave SmartWare Communications to enter another SmartWare module or to return to the operating system. Options for Quit include the following:


 Main-Menu. Returns to the Main Menu of SmartWare.


 Database. Leaves SmartWare Communications and enters SmartWare Database.


 Spreadsheet. Leaves SmartWare Communications and enters SmartWare Spreadsheet.


 Word Processor. Leaves SmartWare Communications and enters SmartWare Word Processor.

If you have selected the Quit keyword and decide that you do not want to leave SmartWare Communications, press Escape.


Communications Error Messages

     4010 Invalid number of stop bits with selected data bits.

If you specified 1.5 stop bits, you must select 5 data bits. If you specified 2 stop bits, you cannot select 5 data bits.

     4011 Already saving to the buffer.

You have selected the Data Capture Buffer Begin command while capturing to the buffer is already in progress.

     4012 Nothing to view; memory buffer is empty.

You selected the Data Capture Buffer View command while the buffer is empty. There is nothing to view.

     4013 Cannot find the profile specified in preferences. Loading default profile.

The profile specified on the Communication Profile definition menu was not found. The default profile, CMDEF.DEF, was loaded instead. Check to see that the specified profile exists and that it is stored in the communication data path. You do not have to specify a path or extension if the profile is stored in the communication data path or if the default extension .UCP is included.

     4014 The capture buffer is empty. You cannot save an empty buffer.

You have selected the Data Capture Buffer Save command when the buffer is empty. Normally, this command would save the contents of the buffer into a file.

     4015 Invalid text expression.

This error occurs when you select Data Output and specify an expression. SmartWare could not parse the expression. Make certain the text string is enclosed in double quotation marks. If quotation marks are not included, SmartWare treats the expression as a number.

     4016 Invalid character for Match command.

This error occurs when you select Data Match and specify an expression. SmartWare could not parse the expression because it contains an illegal character. Make certain that text strings are enclosed in double quotation marks. If quotation marks are not included, SmartWare treats the expression as a number.

     4020 Already saving to a file.

You selected Data Capture File Begin while data is already being saved to a file. You cannot capture data to two files at once. Select Data Capture End, then select Data Capture File Begin and enter a new filename.

     4021 There is not enough memory to start saving to the disk.

You selected Data Capture File Begin, but you do not have enough memory left in your system to handle the overhead required to save to a file.

     4023 Parity is defined with 8 data bits.

When you selected Set-Terminal Settings Edit or Define to edit a profile, you defined 8 data bits and odd or even parity. Since a character can include a maximum of only 8 bits, there is no room for a parity bit.

     4024 There is an error writing an update to the file.

This error occurred when you tried to save or define a profile or a keyboard definition. The disk may be full, or you may not have write privileges.

     4025 The default profile was not found. Please reinstall.

The default Communications profile, CMDEF.DEF, was not found in either the system directory or the directory specified on the Communication Preferences definition menu. You will have to reinstall it. Make certain this file resides in the system directory.

     4026 There is an error reading a definition file.

The system cannot read the modem or keyboard definition file or profile you selected. The file is either lost or damaged. You will have to reinstall it.

     4028 Modem definition not found.  Check path name and/or modem name.

The modem definition file you specified in the current profile is invalid. This error occurred when you selected Set-Terminal Settings Edit to edit the profile or when the profile specified in the Communications Preferences was loaded. Check to see that the modem definition exists and that the full path name is included.

     4042 No default file found for transfer.

This error occurred when you selected the Data Transmit command, but no spreadsheet graph file or interface file was found in the specified directory.

     4043 Receiving computer has not responded. The transfer has been canceled.

When you transmit an Xmodem file, the receiving computer has one minute to respond. Either the computer did not respond soon enough, or there were ten consecutive errors in the same block, and the transfer was halted.

     4044 File transfer has been canceled by the receiving computer.

The receiving computer has halted Xmodem transmission but is still on-line with your system.

     4045 Too many Xmodem errors. The transfer has been canceled.

There were ten consecutive errors in the same block, or the number of errors allowed in the Maximum number of Xmodem retries setting on the Communication Profile menu was exceeded.

     4046 The sending computer has not responded. The transfer has been canceled.

When you selected Data Receive Xmodem, the sending computer did not respond within the one-minute time limit, or no block was received within the allotted time.

     4047 Transmission failure while sending a block. Transfer has been canceled.

The failure may have occurred because of a problem with the phone line or with your modem. If you retry the transmission and still get an error, check your equipment.

     4048 That file already exists. Command has been canceled.

You selected the Data Receive command via Remote Command Mode. The filename you entered at the prompt already exists.

     4049 Xmodem transfer has been aborted.

This error occurs when you select either Data Transmit Xmodem or Data Receive Xmodem and the transfer is interrupted. An interruption can occur if Ctrl-Z is pressed during project file execution; if a connection timeout occurs, as specified in the current profile; if you press the Escape key; or after another error message.

Error messages that might precede this message include the following for Xmodem transmission:

     4925  The file cannot be read
     4043  Receiving computer has not responded.  The transfer has been canceled
     4044  File transfer has been canceled by the receiving computer
     4047  Transmission failure while sending a block.  Transfer has been canceled

If you are receiving an Xmodem transmission, you may have received the following error messages first:

     4045  Too many Xmodem errors.  The transfer has been canceled
     4046  The sending computer has not responded.  The transfer has been canceled

     4050 Parsing error in after expression.

You entered an expression to be echoed back from the transmitting computer when you selected Data Receive Text-File, but the expression was not parseable. If you entered a text expression, make certain you enclosed it in quotation marks.

     4101 Color value must be between 0 and 15.

When you executed the Set-Terminal Paint command, you selected a background or foreground color that was not displayed at the bottom of the screen. Color values must be between 0 and 15.

     4104 There is not enough memory to load VT100 emulator.

You selected the Set-Terminal Settings command. You do not have enough memory on your computer system to run VT100 terminal emulation. If you are using the -r option to reserve memory when you enter SmartWare, try entering without the -r option, and then run SmartWare Communications. Also, make certain you are not currently capturing to the buffer or that you do not have any other memory-resident programs loaded. If you are capturing to the buffer, save the buffer contents and then select Data Capture Buffer End to stop capturing to the buffer. If the error persists, you may need to upgrade you computer's memory.

     4105 Cannot find default keyboard (filename).

This default keyboard definition file was not found in a search during start-up or after selecting the Tools Preferences Communications command. Enter the filename in the system directory.

     4106 Cannot load new keyboard definition.

You selected the Set-Terminal Settings command. The keyboard definition file specified is not valid. If this file is specified in the profile, make certain the name is correct by comparing to those listed on the Communications Preferences menu, or make certain the file listed in the profile is a .KEY file.

     4107  Duplicate Break-Key definitions.

The Break Key was defined twice in the keyboard definition file that is currently being edited. Only one key may be defined as the Break Key.

     4108 There is no Break-Key defined. Please define one.

No Break Key was defined during a keyboard redefinition. There must be a Break Key defined.

     4109 No Switch-Key has been defined. Please define one.

No Switch Key was defined during a keyboard redefinition. There must be a Switch Key defined.

     4110 No Attention-Key has been defined. Please define one.

No Attention Key was defined during a keyboard redefinition. There must be an Attention Key defined.

     4111 Duplicate Switch-Key definitions.

The Switch Key was defined twice in the keyboard definition file that is currently being edited. Only one key may be defined as the Switch Key.

     4112 Duplicate Attention-Key definitions.

The Attention Key was defined twice in the keyboard definition file that is currently being edited. Only one key may be defined as the Attention Key.

     4114  There is a syntax error in the control code.

When you selected Set-Terminal Keyboard Define, one of the keys was defined incorrectly. You might have exceeded the maximum of 50 characters in a key definition or included a quoted text string without a trailing quotation mark. Remember also that the only valid characters you can include without double quotation marks are hexadecimal and decimal numbers, spaces, and the characters + / - \ ; : ,

     4120 There is an illegal character in the dial sequence.

This error occurred when you selected the Set-Terminal Settings command or Connection Dial. A user-defined modem may have a different character set for legal characters in a dial string. For Hayes compatible modems, the legal characters include 0123456789TPRtp,*#()-; and spaces.

     4121 The phone number is too long.

The maximum number of characters is 40.

     4205 There is no number to dial in the current profile.

Either a number must be available in the current profile, or you must enter one when you select Connection Dial.

     4206 This computer is already connected.

This error occurs when you try to dial a number or answer the phone while the system is already on-line.

     4207 Cannot delete the file. File may be read only; check its status.

This error occurred when you tried to delete a file. The file specified may not exist, or the file may be read only. Try again, making certain you specify the full path and filename. If you are working on a multi-user system, you may not have the access rights necessary to delete the file.

     4208 Modem is not responding. Is the modem on? Are the switches set correctly?

The modem did not respond in the time allowed. This indicates one of the following situations: the switches are set incorrectly, the modem is connected improperly, the modem is connected to the wrong serial port, the modem is incompatible with the Modem Type selected on the Communication Profile menu, or the modem is turned off. When this error occurs, SmartWare Communications changes the modem selection to a null modem.

     4209 That command is invalid with a null modem.

A command was executed that is not allowed with a null modem. You selected either a Connection command or Set-Terminal Goto Carrier or Voice. These commands can be used only with a phone line connection to another modem.

     4210 State setting in profile must be set to Originate to dial.

You selected Connection Dial while an answer profile was loaded. Load a profile with the State setting set to Originate and with the appropriate Originate settings specified. Make certain Duplex is set to Full.

     4211 State setting in profile must be set to Answer.

You selected Connection Answer while an originate profile was loaded. Load a profile with the State setting set to Answer and with the appropriate Answer settings specified.

     4212 Lost carrier signal.

You selected the Connection Dial Carrier command. The communications link was disconnected when the carrier signal was lost. This error occurs only when a project file is being executed or when Connection Dial has failed to establish a connection.

     4220 Time limit specified in profile has been exceeded; disconnecting.

Your system has been connected for the amount of time specified in the user profile for Connection Time Limit. When the time limit has been exceeded, SmartWare Communications disconnects.

     4700 No response from remote computer's modem.

You selected Set-Terminal Goto Voice, but the other computer did not respond in the specified time limit.

     4701 Field end less than or equal to field start. Field ends before it starts.

A field start column you specified on the Format Definition menu contains a value that is greater than the field end column value. Press any key and the cursor will be positioned on the line containing the error.

     4702 The file format is invalid.

The format file is corrupt. Erase it using the Data Format Undefine command, and then redefine it. See your system administrator if you are working on a multi-user system.

     4704 The filename for the file you are sending is invalid.

An invalid filename was specified for the data file to send to another SmartWare module. There might be an invalid character in the filename, the file might not exist, or you may not have read/write privileges to the file. If you are working on a multi-user system, see your system administrator.

     4706 The buffer is empty; there is nothing to send.

You selected the Data Send <module> Buffer command, but the buffer is currently empty and cannot be sent.

     4707 That format definition filename is invalid.

An invalid filename was specified for the format file to send to another SmartWare module. There might be an invalid character in the filename, the file might not exist, or you may not have read/write privileges to the file. If you are working on a multi-user system, see your system administrator.

     4709 Error in format definition file. The file may be corrupted.

You selected the Data Send command and specified a format definition filename. Either the format filename was invalid, or the file is corrupt. Enter a valid .CSF filename. If the error occurs again, erase the format definition by selecting Data Format Undefine and then redefine it. See your system administrator if you are working on a multi-user system.

     4711 That project filename is invalid.

This error can occur upon entry to SmartWare Communications or when a project filename is entered during execution of a Data Send command. An invalid project filename specified under the Project file to run on entry setting on the Communications Preferences menu will cause this error to occur on entry. For either situation, make certain the project file has been compiled and that the filename is valid. The project file should be available in the path specified on the Communications Preferences menu.

     4712 Could not open interface file. Check status of destination directory.

When you attempted to send a file, the program could not create an interface file. Either the directory is full, or you do not have permission to create a file in this directory. If you are working on a multi-user system, see your system administrator.

     4713 The file being sent has been truncated.

This error occurred when you selected Data Send and included a format definition filename. The end of the buffer or file you specified was reached before all the defined data items were used.

     4714 Error writing interface file. Check the status of destination directory.

This error occurred while the program tried to write an interface file to disk during a Data Send operation. Your disk could be full or have bad sectors, or it might be write-protected. If you are running on a multi-user system, you may not have access rights.

     4715 Error reading the file to be sent. Check its status.

This error occurred while a file was being sent from SmartWare Communications to another module. The specified file cannot be read. Make certain this file has read-only status.

     4716 Formatted output line is too long.

The maximum line length of 4000 characters was exceeded when you attempted to send a file. Modify the Start new output line settings in your format definition file to decrease the output line length.

     4718 Cannot delete CMMODEM.MDV.

This file is located in the system directory and contains the predefined default modem definitions provided in SmartWare. You cannot delete these definitions.

     4802 Changes will affect this session only.

This error occurs when you select Set-Terminal Settings Load or Tools Preferences Communications. In a multi-user environment, you may have read-only privileges for certain files. You can specify definition settings during this session, but the settings cannot be saved. A set of definition files (extension .DEF) and the appropriate screen and printer driver files should be installed in each user's sub-directory. Normally, the procedure is handled by a system administrator.

     4803 Note:  No permission to save file under this name.

You can load the file, edit it, and view the revised version on the screen, but you cannot save it. Either someone is currently using the file, or you do not have write privileges.

     4804 No permission to save file under this name.

In a multi-user environment, another user might be using the same file. Also, some operating systems allow you to grant read and write privileges to files. A file that does not have save permission can be modified in memory, but cannot be saved.

     4901 No asynchronous communication board in this computer.

There is no serial port in this computer. You cannot use SmartWare Communications without a serial port.

     4902 There is not enough memory to run Communications.

If you are using the -r option to reserve memory when you enter SmartWare, try entering without it and then run SmartWare Communications. If the error persists, you may need to upgrade you computer's memory.

     4903 Failure to receive after expression.

You entered an expression to be echoed back from the transmitting computer when you selected Data Receive Text-File, but the expression was not received. Make certain the system is on-line, and verify the expression with the transmitting operator.

     4905 File must contain ASCII characters for text file transmission.

The text file being transferred contains characters outside of the printable ASCII character set. SmartWare document files must be changed to text file format before transmitting. You may use the Xmodem option to retain document control characters.

     4906 Communications preferences file is missing. Reinstall.

The CMPREF.DEF file is not in the system directory.

     4908 Error opening capture file.  Abandoning capture to disk.

This error occurred while the program tried to open a file during execution of a Data Capture File command. On a multi-user system, you may not have access rights to this file.

     4910 Error writing capture file.  Abandoning capture to disk.

This error occurred while the program tried to write a file to disk during execution of a Data Capture File command. Your disk could be full or have bad sectors, or it might be write-protected. If you are running on a multi-user system, you may not have access rights.

     4912 Unable to load communications driver file. Reinstall.

This error indicates that the communications driver file IBM.CDV or TANDY.CDV was not found or has been damaged. Reinstall the file in the system directory and then select it on the Hardware Preferences menu using the Tools Preferences Hardware command.

     4920 That filename is invalid.

The filename you typed in has illegal characters or does not exist.

     4921 The file cannot be created.

You were prompted to enter a filename in a Data command format or Set-Terminal command format. You might not have permission to create a file in this directory. If you are working on a multi-user system, see your system administrator.

     4922 Cannot find that file.

The filename you specified in a Data Xfer-Time, Data Transmit, or Set-Terminal Settings Load command could not be found. The file might not exist, or you might not have rights to this directory if you are working on a multi-user system.

     4924 The file cannot be opened.

On a multi-user system, you either do not have read privileges, or someone else is trying to save the file.

     4925 The file cannot be read.

You selected the Data Transmit command, but the specified file cannot be read. The file might be empty, or there might be a problem with your hardware. Check to see if the floppy drive door is open or if your hard disk has failed. If you are working on a multi-user system, check to see whether the network has failed.

     4926 Error in writing to the file.

You selected the Data Format or Data Receive command, but the specified file cannot be saved. The disk might be full, or there might be a problem with your hardware. Check to see if the floppy drive door is open or if your hard disk has failed. If you are working on a multi-user system, check to see whether the network has failed.

     4940 Unknown command.  Type Ctrl-C ? to get help.

This error occurs when SmartWare Communications is in Answer state and a caller types Ctrl-C followed by an invalid command. The only valid Ctrl-C commands are DI, RT, RX, TT, TX, and ?.

     4941 Bad syntax.  Please try again.

If you selected Data Transmit Textfile, this error was generated because a closing bracket was not included. If you selected Set-Terminal Modem Define, this error was generated because of an improperly entered text string on the Modem Definition menu. Make certain the text string is enclosed in double quotation marks. If quotation marks are not included, SmartWare treats the expression as a number. The following is an example of a correctly entered text string: "ATS10=30" 13.

     4942 Too many modem names to display; displaying as many as possible.

You have more modem definitions than can be displayed in the prompter box. You may want to consider deleting any modem definitions you no longer use. If you know the exact name of the modem you wish to load, you can type in the name without seeing it on the prompter.