3. Program Control

Applications written in Thoroughbred Basic, or any other programming language, accomplish their tasks through the execution of programs. These programs represent the translation of desired operations into computer-recognizable commands. The programming language attempts to provide an easy path for the human programmer to tell the computer system just what is needed and how it should be accomplished. Programs are stored as files on disk, just as data is stored, but are maintained through the use of the Thoroughbred Basic Interpreter rather than a file maintenance application system.

The creation, maintenance, and actual execution of these programs are referred to as program control. This chapter discusses how to build a program, how to save it, how to change it, and some general understanding of what happens within execution of the program (e.g. what gets done first, how does the programmer control execution processes, and so on).

Sequence within programs is maintained through the use of program line numbers. These numbers range from 00001 to 65534 in release levels beginning with 7.0, and from 0001 to 9999 in earlier releases.

Total program size cannot exceed 5*1024*1024 (5,242,880) bytes. Releases from 8.0 through 8.3.1 limit total program size to 64,000 bytes. Releases prior to 8.0 limit total program size to 32,768 bytes.

Program modes

In dealing with programs, there are two major modes of operation:

Thoroughbred Basic Console Mode: The program mode, which allows interactive conversation between the programmer and Thoroughbred Basic for the purpose of maintaining program, files.
Thoroughbred Basic Run Mode: The program mode, which allows the actual Thoroughbred Basic, programs to execute and control the interactive conversation between the computer system and the user or programmer.

When in Thoroughbred Basic Console Mode, executing a RUN directive places the task in Thoroughbred Basic Run Mode. From Thoroughbred Basic Run Mode, execution of an END or STOP directive places the task in Thoroughbred Basic Console Mode. Additionally, Thoroughbred Basic Run Mode operation may be interrupted, placing the task in Thoroughbred Basic Console Mode, with the execution of the ESCAPE directive or through keyboard intervention by pressing the Escape key. When Thoroughbred Basic Run Mode is interrupted in this way, the environment within the user task is left unchanged; files that were open are still open and variables contain the data they had at the time of interruption.

Statement labels

You can name any Thoroughbred Basic statement number with a statement label, and then refer to that label in any directive or function where a statement number is used (except the PGM function). This feature is generally available starting with release level 8.1B2.

Statement labels, like long variable names, can help to make your program more readable. Statement labels allow you to identify and refer to routines by name rather than by line number. For example, if your date routine starts at line 1000, you can name this line with a label, such as SETUP_DATE, and then refer to this label anywhere in the program that references line 1000. Instead of using GOSUB 1000, you can use GOSUB SETUP_DATE. Label names also provide improved performance over line numbers when a program branch uses the label name.

To be able to reference a label name in a Thoroughbred Basic statement, the label must be declared somewhere in the program. Label names must be unique; a label name can be declared only once in a single program.

Any Thoroughbred Basic statement number can contain a label declaration as shown in the following syntax:

linenum lblname: directive

linenum: is a valid Thoroughbred Basic line number.
lblname: is the name of the label followed by a colon. The label name must begin with an uppercase letter, can be up to 32 characters long, and can contain any combination of uppercase letters (A-Z), numbers (0-9), and _ (the underscore character).
directive: is any valid Thoroughbred Basic directive.

Example:

09500 ERROR_IN_OUTPUT: PRINT(EIO_ERROR_MSG$)

The label declaration is handled as an integral part of the line number, must immediately follow the line number, and cannot be declared in the middle of a statement.

When referencing statement numbers in Thoroughbred Basic commands, either the line number or the label name can be used in any syntax that refers to a Thoroughbred Basic statement number. For example, either a line number or a label name can be used for line-ref in the GOTO line-ref syntax.

If you reference a label name that has not been declared, or declare a duplicate label name, an ERR=21 results. If you reference an undeclared label name in LIST or DELETE, an ERR=45 results.

Label names are stored in the program symbol table (see the PFL and PFP functions).

Thoroughbred Basic Console Mode

This is generally the starting point for all programming activity. Thoroughbred Basic Console mode can be attained in several ways:

The IPLINPUT file, which is part of environment control, can designate that a task is to begin in Thoroughbred Basic Console Mode.
The programmer can select the entry on the Thoroughbred Basic Utilities Menu, which places the task in Thoroughbred Basic Console Mode.
A program may exit into Thoroughbred Basic Console Mode by executing an END or STOP directive.

Once in Thoroughbred Basic Console Mode, you may work with whatever program is currently in your user task area, you can LOAD a different program and work on it, you can build a new program from scratch, or you can enter Thoroughbred Basic Console Mode directives to perform specific functions interactively.

To leave Thoroughbred Basic Console Mode and return to the operating system you can type RELEASE and press the Enter key.

Entering Program Code

Communication with Thoroughbred Basic from Thoroughbred Basic Console Mode is accomplished by entering a command terminated with a carriage return. If a number precedes the command, it is interpreted as a line of Thoroughbred Basic program code and is checked for proper syntax and placed in the user task program area. If a number does not precede the command, Thoroughbred Basic attempts to execute the command directly rather than assume it is to be placed in the user task program area.
Although Thoroughbred Basic does not require spaces when entering commands, care should be taken to avoid misinterpretation, especially in long variable names.

Example:

Entering 0100 PRINT DAY adds line 0100 to the user task program space, writing over any previous line 0100, containing the PRINT directive as shown.

Entering PRINT DAY causes Thoroughbred Basic to print, on the next line of the terminal, the contents of this task’s DAY system variable (e.g. 10/25/19).

Entering 0000 PRINT DAY causes Thoroughbred Basic to treat this command as if it had no line number. Line number 0000 indicates a Thoroughbred Basic Console Mode command. If a syntax error were made in a Thoroughbred Basic Console Mode command, Thoroughbred Basic displays the error using line number 0000. For example:

Entering PIRNT DAY results in the following response from Thoroughbred Basic:

*ERR V
0000 PIRNT DAY

Indicating that Thoroughbred Basic was unable to understand this statement, and that the first point of difficulty was at the I in PIRNT. Although Thoroughbred Basic executes programs in line number sequence (unless directed otherwise), program commands need not be entered in line number order. The line number at the beginning of the command entered determines where Thoroughbred Basic places the program line.

Shorthand Notation

Starting with release level 8.2, a colon is now allowed to immediately follow the = to substitute the left side of the = for the colon. For example:

LET ABC$[2]=:+“X” becomes LET ABC$[2]=ABC$[2]+“X”.

Note: This is only a shorthand notation for input. The code still lists the expanded way.

Editing Program Code

Now that you can enter a line of program code, how do you change what you have entered?
Thoroughbred Basic offers the following ways to change programs:

You can retype the line, which overwrites the previous contents of that line number.
You can change the line by using the EDIT directive for a single program line number (see EDIT line directive).
You can change the line by using the full-screen EDIT directive (see EDIT full-screen directive), which provides line editing with a full-screen display.
You can change the line by using the EDITF directive, which provides full program editing using a formatted display of the program.
You can change the line by using Thoroughbred Source-IV, which provides program maintenance and source control.

The single-line EDIT directive is a carry-over from older versions of comparable Business BASIC systems and is somewhat cumbersome to use. The full-screen EDIT directive allows the use of text editing keys to change program lines. The EDITF directive allows you to edit a formatted display of the program and provides many helpful features, including text-editing keys, the ability to select the level of formatting (structured or unstructured) and an interface to the Thoroughbred Basic on-line documentation system. With each increase in capability from EDIT line to EDIT full-screen to EDITF, there is a corresponding increase in the amount of memory used and you may also perceive some difference in the speed of operation.

Statement Stepping

Thoroughbred Basic offers additional interactive editing and debugging capabilities available from Thoroughbred Basic Console Mode. They are . (period), ; ( semicolon), and ;n. These options are discussed below:

Type . and press the Enter key. Thoroughbred Basic displays the next line of program code to be executed. The . also finishes any line that has been semicolon into. This feature is generally available starting with release level 8.0.
Type ; and press the Enter key. Thoroughbred Basic displays the next directive to be executed. The currently displayed line or directive is executed. This feature is generally available starting with release level 8.2.
Type ;n, where n is the number of directives you want to trace, and press the Enter key. Thoroughbred Basic lists the first directive to be executed, then executes the directive portion that is placed between the semicolons on the line of code. It repeats this procedure n times.

These debugging operations function even within public programs, a feature not normally found among comparable BASIC languages. When coupled with PRM LONG-PROMPT in the IPLINPUT file (see System Files in the Thoroughbred Basic Customization and Tuning Guide), which places the name of the program and the last error code encountered in the prompt, debugging becomes much easier.

After the execution of each numbered statement, you can look at the value of variables as the result of execution. When you are in public programs, the variables you see are those of the public program (see Public programs later in this manual).

Note:: These debugging options do not function on encrypted programs.

Saving Program Code

When you are finished with a program, the next logical thing to do is to save the program on disk. This is accomplished with the SAVE directive to simply save the program, or the PSAVE directive, which provides for saving the program with an encryption technique that does not allow anyone else to look at program lines above line number 100 unless they know the password that you used when executing the PSAVE directive. Thoroughbred Basic provides the ability to protect the source of your programs. The PSAVE directive is an example. Additional protection features are discussed under the ENCRYPT directive and the SSN system variable.

Long Variable Names

Starting with Thoroughbred Basic 8.0 which offers long variable names instead of the well-known short variable names such as A1 or D1$, you have the option to choose which mode you are in when entering lines of program code in Thoroughbred Basic Console Mode.

In the IPLINPUT file, you can enter the PRM SHORTVAR or PRM LONGVAR statement, which establish the default program control environment for syntax checking. If PRM SHORTVAR was set as the default, then long variable names and Thoroughbred Basic syntax that was not available before release level 8.0 causes syntax errors when entered in Thoroughbred Basic Console Mode as lines of program code. PRM LONGVAR permits the entry of long variable names. For more information on these PRM statements, please refer to the Thoroughbred Basic Customization and Tuning Guide.

This default setting from the IPLINPUT file can be overridden by a Thoroughbred Basic Console Mode command. Thus, entering SHORTVAR in Thoroughbred Basic Console Mode changes the syntax checking facility of Thoroughbred Basic to allow only short variable names. This setting can be changed back to long variable name syntax and pre-8.0 release level syntax with a LONGVAR directive, whether in Thoroughbred Basic Console Mode or Thoroughbred Basic Run Mode.

A more complete description of these two directives is contained in the LONGVAR and SHORTVAR entries in the Thoroughbred Basic Language Reference.

Program Code Syntax

Now that you know how to enter lines of program code, modify them, and save a program, let’s spend some time on the actual commands within those lines of code. First, a program line can contain one command or several commands. Individual commands are separated by the ; (semicolon). The Thoroughbred Basic term for a command is a directive. A directive tells Thoroughbred Basic to do something, go somewhere, test something, read or write something, and so on.

All programs need data, and Thoroughbred Basic provides for data definitions in a variety of ways. The most complete definition of the various types is covered in the chapter on Data Representation. In general, you may have numeric or string constants, numeric or string named-variables, system defined variables, system defined functions, and programmer defined functions. As with most versions of the BASIC language, it is not necessary to define named-variables in advance; their usage is normally sufficient to define them. You may choose to define them in advance and preset their value with either a LET or DIM directive, which represent the commands to assign values to variables or dimension those variables to specific, sizes and values.

Communication

Thoroughbred Basic communicates with other tasks or devices such as a disk or terminal keyboard through channels, which it opens (with an OPEN directive), closes (with a CLOSE directive), listens to (with EXTRACT, FIND, FINPUT, INPUT, or READ directives), and talks to (with PRINT and WRITE directives).

The purpose of these communications is to transfer data from the program to somewhere, or from somewhere to the program. All data is transferred into named variables or out from named variables or constants. Channel 0 (zero) is reserved for special communications. In the case of a regular task, this is the channel for normal keyboard and terminal communications. For a program being run as a ghost task, this channel is the inter-task communication channel for talking with other programs and other tasks (see Ghost tasks later in this chapter).

Each task or device has a name. Disks are named differently from printers, which have different names from other tasks, which have different names from files. The System Files chapter in the Thoroughbred Basic Customization and Tuning Guide discusses the IPLINPUT file, which establishes the names for disks, printers, tasks, and other devices.

Files are contained on disk, and their names are kept in what is called a logical disk directory. This provides the capability, within Thoroughbred Basic, to have more than one logical disk per physical disk, and to separate files into logical groups by placing them in one logical disk directory or another. By convention, Thoroughbred Basic utilities are located on logical disk directory 0, which is called by the device name D0, and referred to by the directory name of UTIL or UTILS. Files represent the only storable method for keeping data. There are several different file types, each representing a different method of data organization or access (remember that programs are maintained as files). Further discussion of the different types of tasks, devices, or files is contained in the chapter on Input/Output Processing.

Before leaving our discussion of Thoroughbred Basic Console Mode, it should be noted that some directives are Thoroughbred Basic Console Mode-only commands, and some directives are only available in Thoroughbred Basic Run Mode. These restrictions are noted in the Thoroughbred Basic Language Reference.

Thoroughbred Basic Run Mode

This is the mode used to execute programs. Thoroughbred Basic Run Mode can be launched in several ways:

The IPLINPUT file, which is part of environment control, can designate that a task is to begin with a specific program, which is run when the task is initialized.
The programmer can enter the RUN directive from Thoroughbred Basic Console Mode, which places the task in Thoroughbred Basic Run Mode and executes the program in user task memory.
The programmer, or a program, can issue a CALL directive, which places the task in Thoroughbred Basic Run Mode within a public program.

In Thoroughbred Basic Run Mode, communication between Thoroughbred Basic and the terminal/keyboard are terminated, and the program that is running now has control over those lines of data transfer. Execution of the program specified by the RUN directive begins at the lowest line number in the program (lowest possible line number is line number 00001).

Unless program execution is transferred to another line with one of the transfer directives (such as GOTO or GOSUB) or conditional transfers (such as SETERR, SETESC, DOM=, ERR=, and so on), the next sequential line number is executed after the first line number is finished. Line numbers need not start with 1 and need not follow a specific number differential. It is not unusual for programs to start with 10, incrementing each succeeding line by 10. This provides for several line numbers between the existing ones should additional program code need to be inserted. It is not unusual, either, for a programmer to follow a simple numbering scheme such as:

00010-00099 Program description area
00100-00999 Data initialization area
01000-05999 Program mainline
06000-07999 Major subroutines
08000-08999 Error processing routines
09000-09999 Program exit logic

Thoroughbred Basic imposes very few restrictions on structure, but offers several tools to help construct good programming structure and conventions. The next few topics show how programs can be grouped, constructed, and organized to provide more performance with less program space and greater maintainability; all desirable qualities in programs.

Mainline routines, subroutines, and functions

When building a program and generating lines of program code, as long as each line or group of lines of code are unique, the fastest and easiest way to create the necessary code is what we refer to as straight mainline. This is the simple approach of sequentially coding line after line until the desired result is accomplished.

In a more organized approach, however, we find the need to repeat some operations more than once. The straight mainline method then ends up with redundant code that takes more time to write, more space to hold (in memory and on disk), and possibly more time to execute. When a simple loop is desired, that is conditioned on a specific number of occurrences or reaching a specific set of conditions, it can be coded using a FOR/NEXT directive or the WHILE/WEND directive. If we want to perform some operation, whether it is a FOR/NEXT, WHILE/WEND situation or not from varying points in our mainline program, we need to employ another approach.

Thoroughbred Basic provides the ability to execute a group of program code from somewhere else and return back when finished. This type of program structure is normally referred to as subordinate routines, or subroutines. The syntax structure simply involves the execution of a GOSUB directive to get to the subroutine’s starting line number and the execution of a RETURN directive, which returns execution to the next directive after the GOSUB directive. The subroutine itself is no different from other program lines with the exception of the RETURN directive at the end of its group of program lines.

If and when a particular operation becomes needed by more than one program at the same time, it is not necessary to duplicate the subroutine in each program. The logical approach may be to break out the necessary lines of code into a separate program and make that program available to anyone who wants to use it. This tactic involves the use of public programs.

Public programs

Public programs look very much like regular programs. In fact, it is possible to create a single program that can act either as a public program or as a regular program. What, then, differentiates the two? Simply stated, a regular program is RUN while a public program is CALLed.

Public programs were originally designed to be, in somewhat academic terms, fully re-entrant routines, which could be used by multiple tasks, each with a different set of data and/or conditions, simultaneously. However, in some operating system environments, the facility may not exist to provide simultaneous use with fully re-entrant characteristics. To the Thoroughbred Basic programmer, however, these differences are transparent and of no consequence.

Public programs are, essentially, remote subroutines. Since they are remote, they do not share the data environment of the parent program that CALLed them. It is necessary for the parent program to pass the needed data to the public program, and for the public program to return its results to the parent. This exchange is accomplished by the CALL and ENTER directives. The parent program issues a CALL to the public program with a list of variable names and/or constants. The status of open files and devices is automatically passed from the parent to the public program, including all file and record pointers and any locked records or files in effect at the time of the CALL.

Execution then passes to the public program. When the public program encounters it’s ENTER directive, the variable names and/or constants from the parent program are passed into the public program’s data environment. When the public program wishes to return to the parent program it executes an EXIT directive, which passes back the variables to the parent program with the values from the public program at the time of the EXIT. Although difficult to describe in narrative form, the CALLing of public programs is very common in applications that involve multiple programs with a need for common routines or operations among them. For more information on the CALL, ENTER, and EXIT directives, please refer to descriptions in the Thoroughbred Basic Language Reference.

Thoroughbred Basic realizes that, in larger applications environments, it also becomes necessary for public programs to require common subroutines as well. To that extent, public programs can be CALLed from other public programs which can be called from other public programs, and so on, to a nested depth of 127 or the extent of available memory, whichever is encountered first.

CALLing public programs automatically passes the status of open files and all record and file
information and allows for the static passing of data.

Ghost tasks

Ghost tasks, a term carried forward from older versions of comparable Business BASIC languages, are programs that run in a background mode, without their own keyboard and terminal. This makes them impossible to see through the normal terminal interface; somewhat ghostlike in operations.

Due to the nature of the MS-DOS environment, ghost tasks are not available with Thoroughbred Basic for MS-DOS.

Ghost tasks are independent programs, which, unlike public programs, do not share environments with other tasks. They have different task names (G0 through G9, GA through GZ, and Ga through Gz) and do not have a terminal or keyboard with which to communicate. They communicate through their channel 0 (zero) to other tasks, both regular tasks and other ghost tasks. A regular task, with its own keyboard and terminal, communicates with a ghost task by issuing an OPEN directive for the ghost task on one of its regular channels (other than zero). The ghost task completes the communication connection through its own channel 0 (zero), which does not require an OPEN directive. Thoroughbred Basic provides for 62 ghost tasks.

Enter number of ghosts to add or <CR> to end:
You can specify the number of ghost tasks that will be available to Thoroughbred Basic. Valid values are 1 through 62. Type a valid value and press the Enter key.

Since the ghost task has only one channel 0 (zero), it cannot communicate with more than one regular task at a time. Also, a ghost task is linked to the regular task until the regular task closes its channel to the ghost task. It is possible, however, for one ghost task to communicate with another. This is accomplished when a ghost task opens a second ghost task< using one of the first ghost task’s standard channels.

There is a utility, *GPSD, supplied with Thoroughbred Basic that is specifically designed to communicate with ghost tasks that are running on a given system. Refer to the Thoroughbred Basic Utilities Manual for more information about this capability.

Since ghost tasks do not have access to the data environment or file environment of other tasks, and since they have such a limited communication capability with the outside world, what purpose could they serve? They provide the ability to start up a background program, which runs continuously, performing functions that do not need intervention from a terminal but should be constantly monitored. Examples include de-spooling programs for spooled printer output, which constantly monitor the system for output files that are to be printed. Another example is for clocked operations; in UNIX there is the cron task that performs predetermined operations based on date and time. Ghost tasks provide the ability to implement the same features within Thoroughbred Basic.

The capabilities and uses of background tasks such as ghost tasks are limited only by the imagination of the developer. They are simply another application development tool made available through Thoroughbred Basic to the programmer or developer.

Program Execution

As stated earlier, all program commands exist as numbered program lines. These lines are executed in sequential order, starting with the lowest numbered line, unless this order is interrupted by a Thoroughbred Basic directive that transfers execution to another place in the program.

Thoroughbred Basic maintains a stack of addresses of places to go. This Return Address Stack is designed to remember, with certain directives, the point of return to which to transfer execution when an associated directive or condition is encountered. For example: the loop control of the FOR/NEXT directive places an address on the stack when the FOR clause is executed that points to the command that immediately follows the FOR clause. When the appropriate NEXT clause is encountered, Thoroughbred Basic knows where to go for the next cycle through the loop. When the loop conditions are satisfied, execution of the NEXT clause causes this address to be removed from the stack. This explanation is given only to help in the understanding of those directives, which change the normal sequence of command execution.

The following directives change the normal sequence of command execution, without regard to previous addresses remembered on the Return Address Stack:

CALL: Transfers execution to a public program with no change to the stack; return from the public program continues with the stack unchanged.
END: Terminates Thoroughbred Basic Run Mode, clears all addresses from the stack, and points to the first line of the program as the next line to be executed.
EXIT: From a public program, terminates execution of the public program, clearing any remaining addresses on the public program's stack, and returns to the CALLing program.
EXITTO: Transfers program execution to the program line specified and removes the topmost address from the stack, regardless of what directive or condition placed it there.
GOTO: Transfers program execution to the program line specified and does not change the address stack.

The following directives change the normal sequence of command execution, but are sensitive to the Return Address Stack:

NEXT: If the FOR/NEXT loop condition is not fully satisfied, changes execution to the directive immediately following its matching FOR clause; if satisfied, removes the topmost address from the Return Address Stack.
GOSUB: Transfers program execution to the program line specified and adds an address to the stack that points to the next statement after the GOSUB directive.
RETRY: Attempts execution of the last instruction executed based on the address placed on the Return Address Stack by an error condition.
RETURN: Transfers execution to the topmost address on the stack, presuming it to be the return point added to the stack by execution of GOSUB or an Escape Key interruption.
WEND: Transfers execution back to the directive immediately following its associated WHILE clause based on the address on the stack placed there by execution of the WHILE.

Unless specified otherwise, an error condition or pressing the Escape Key causes a program to go into Thoroughbred Basic Console Mode at the point of error or interruption. Thoroughbred Basic provides directives and clauses to help control this:

SETESC: This directive specifies a line number to which to go whenever the Escape key is pressed.
SETERR: This establishes the default line number to go to whenever an error occurs in Thoroughbred Basic Run Mode.
DOM=: This I/O option in Input/Output directives indicates the line number to go to if a duplicate or missing key is detected.
END=: This I/O option indicates the line number to go to if the end of a file is detected during the execution of the associated directive.
ERR=: This optional clause specifies the line number to go to if this specific directive generates an error.
ERC=: This optional clause enables programmers to define and manage processing errors that occur within a directive. It provides a structured programming alternative to the ERR= clause. ERC= is valid anywhere ERR= is valid.

The full complement of Thoroughbred Basic directives offers complete control of program execution under almost every circumstance except total system failure. Should a Thoroughbred Basic program get in an irrecoverable loop (loop condition can never be satisfied, no system errors exist, and a SETESC directive prevents program interruption with the Escape key), there remains one back door available to the developer. Thoroughbred Basic can be abnormally terminated with the Ctrl-b (hold down the control key and press the b key) keystroke sequence. This is known as the QUIT character. This, too, can be controlled through use of the PRM QUIT= statement in the IPLINPUT file.

For more information on the PRM QUIT= statement and the IPLINPUT file, please refer to the chapter on System Files in the Thoroughbred Basic Customization and Tuning Guide.

Thoroughbred Basic Windows

Thoroughbred Basic, beginning with release level 8.1, offers the concept of windows to the Thoroughbred Basic programmer/user. In its simplest terms, a terminal/keyboard device is normally a window of about 80 characters width and some 23 or more rows from top to bottom. Current applications have shown us that it is very convenient to be able to bring up small amounts of information on a portion of the entire screen without fully erasing the entire screen and restoring it when done with the ancillary task.

Under Thoroughbred Basic Windows, you have the ability to create, modify, manipulate, and delete windows from within a Thoroughbred Basic program. The Thoroughbred Basic Windows Manager keeps track of screen data that is overlaid by a window and replaces that data when the window is removed.

Before an application program can use the Thoroughbred Basic Windows Manager, the terminal must be properly configured within Thoroughbred Basic. You must first tell Thoroughbred Basic that this terminal is a windowing terminal by using a type 5 for the DEV T0 line in the IPLINPUT file for this task. Next, you must be sure that you have described your terminal type to be a windowing terminal using the *NPSD utility. For more information on the *NPSD utility please refer to the Thoroughbred Basic Utilities Manual. For more information on the IPLINPUT file, please refer to the chapter on System Files in the Thoroughbred Basic Customization and Tuning Guide.

The TCONFIGW file, which enables you to use Thoroughbred Basic Windows, differs from TCONFIG8 in that it contains special mnemonic codes for the Thoroughbred Basic Windows Manager. If your terminal type does not appear in the TCONFIGW file, you can configure a windowing interface table for it provided that you have the necessary technical reference information on the terminal and follow the instructions in the *NPSD utility.

It is important that you include the A and G series mnemonics when configuring your table. The G series tells the Thoroughbred Basic Windows Manager what codes are used for Business Graphics when you specify a window border of line graphics (BORDERATR=LG). The A series tells the Thoroughbred Basic Windows Manager, how to change the attributes on this particular terminal. Please note that there is one series for ANSI terminals and one for non-ANSI terminals. You should define only one of these two sets in your table. For more information on the A and G mnemonics, please refer to the Thoroughbred Basic Customization and Tuning Guide.

Using Thoroughbred Basic Windows

The use of windows for presenting help text, file or data lookups, option lists, pull-down menus, pop-up windows, and so on, enhances an application and provides a very robust development tool for a more pleasing interface between the software and the user.

To better understand the potential use of windows and the rules governing them, it is best to think of the entire terminal screen as a window. When you type beyond the end of a line, your cursor normally falls to the first character position of the next line. When you type past the last line on the bottom of the window, the entire window normally scrolls up one line and places the cursor at the beginning of the now blank last line. When you refer to the position of the cursor, you normally talk about row 0, column 0 as the upper left corner of the window.

When you define a Thoroughbred Basic Window (for example) of 40 columns width and 10 rows height, the cursor movement is subject to the new width and height. The end of the line wrap occurs after only 40 characters, screen/window scroll occurs after the 10th line of characters, and column 0, row 0, is the upper left corner of the 40 by 10 window. When you are outputting to or inputting from the window, the rest of the physical screen remains unaffected. When you finally eliminate the window, whatever screen characters there were on the previous window that were covered up reappear, and your cursor operations are once again controlled by the entire screen capacity.

Thoroughbred Basic Windows can be placed on top of other Thoroughbred Basic Windows. You do not have to delete a Thoroughbred Basic Window to return to a previous Thoroughbred Basic Window. The previous Thoroughbred Basic Window can be selected, which brings its contents onto the physical screen and places all input/output operations within its borders. A full understanding of Thoroughbred Basic Windows requires review and use of the WIN functions and WINDOW directives. For more information on these functions and directives, please refer to the Thoroughbred Basic Language Reference.

Notes on Thoroughbred Basic Windows

If you choose to define your own windowing interface table for your particular terminal, you should note that *NPSD asks several questions about each mnemonic code that you define. For A and G series mnemonics, you should respond to the prompt for the code to be transmitted to the terminal with the proper code sequence. The remaining questions for that mnemonic can be answered with the number 0 (zero) or by pressing the Enter key, which defaults to zero.

The Thoroughbred Basic Windows Manager assumes that terminals don’t automatically wrap to the next line when output goes off the right edge of the window/screen. The Thoroughbred Basic Windows Manager uses a cursor positioning sequence to bring the cursor to the beginning of the next line. Most terminals allow the user to turn off auto-wrap, and this is the recommended approach. For those terminals, which do not provide this ability, you must define the A6 mnemonic, whether this is an ANSI or non-ANSI terminal, and set the value to any code. The Thoroughbred Basic Windows Manager does not use this code, it simply senses the presence of “A6” and treats the terminal properly.

If the terminal type takes a space on the window to change a window attribute, then the A8 mnemonic should be defined. This provides for limited use of terminals such as the Wyse 50 and Televideo 950. If the A8 mnemonic is defined for a terminal, which does not take a screen position for attributes (such as the Wyse 60), then output may not display properly. The table must match the terminal for proper performance. Previous releases of other Thoroughbred products were built to handle both types of terminal conditions (with and without the space for attributes) by placing an extra space in the mnemonic codes for non-space terminals. Since the Thoroughbred Basic Windows Manager differentiates between these two conditions, it is important that terminal tables configured for non-space terminals not contain an extra space in their mnemonic codes.

If the Thoroughbred Basic Windows Manager does not find the terminal type that you told it to use in TCONFIGW, it looks in TCONFIG8 before indicating an error. If the Thoroughbred Basic Windows Manager does not find the necessary A or G series mnemonic codes in the table for your terminal, it attempts to simulate the necessary operations. The best solution, however, is to have a properly configured terminal table for your terminal type in TCONFIGW.

For more information

You should now have some level of understanding of the Thoroughbred Basic programming environment. The Thoroughbred Basic Language Overview chapter gives a list of Thoroughbred Basic directives, numeric functions, string functions, and system variables. It is very helpful in providing a quick overview of all the commands at your disposal in creating Thoroughbred Basic programs.

As with all programming languages, it is also helpful to look at some functioning programs to get a better understanding of just how things fit together. Although complex in some cases, the utilities that are provided with Thoroughbred Basic are examples of working programs which can be printed out using the *KPSD utility or viewed on the terminal screen using the *HPSD utility. We recommend that you do not attempt to change the utilities in any way, but they do provide some insight into actual program construction.

The next chapter, Input/Output Processing, provides insight into the different ways data can be stored and retrieved as well as how to communicate between devices and tasks, and among separate tasks.

From the Thoroughbred Basic Developer Guide, version 8.9.1. Open this page in the PDF