Commands

User Interface

? | ??	Display one or more values to the console
@…BOX	Draw a box on the screen
@…CLEAR	Clear a rectangular region of the screen
@…GET	Build a new Get object and display it to the screen
@…PROMPT	Paint a menu item and define a message
@…SAY	Display data at a specified screen or printer row and column
@…TO	Draw a single- or double-line box
ACCEPT*	Place keyboard input into a memory variable
CLEAR TYPEAHEAD	Empty the keyboard buffer
DISPLAY	Display records to the console
INPUT*	Enter the result of an expression into a variable
KEYBOARD	Stuff a string into the keyboard buffer
LIST	List records to the console
MENU TO	Execute a lightbar menu for defined PROMPTs
READ	Activate full-screen editing mode using Get objects
RESTORE SCREEN*	Display a saved screen
SAVE SCREEN*	Save the current screen to a buffer or variable
SET BELL	Toggle sounding of the bell during full-screen operations
SET COLOR*	Define screen colors
SET CONFIRM	Toggle required exit key to terminate GETs
SET CONSOLE	Toggle console display to the screen
SET CURSOR	Toggle the screen cursor on or off
SET DECIMALS	Set the number of decimal places to be displayed
SET DELIMITERS	Toggle or define GET delimiters
SET ESCAPE	Toggle Esc as a READ exit key
SET FIXED	Toggle fixing of the number of decimal digits displayed
SET FORMAT*	Activate a format when READ is executed
SET FUNCTION	Assign a character string to a function key
SET INTENSITY	Toggle enhanced display of GETs and PROMPTs
SET MESSAGE	Set the @…PROMPT message line row
SET SCOREBOARD	Toggle the message display from READ or MEMOEDIT()
SET TYPEAHEAD	Set the size of the keyboard buffer
SET WRAP*	Toggle wrapping of the highlight in menus
TEXT*	Display a literal block of text
WAIT*	Suspend program processing until a key is pressed

Database

APPEND BLANK	Add a new record to the current database file
APPEND FROM	Import records from a database (.dbf) file or ASCII text file
AVERAGE	Average numeric expressions in the current work area
CONTINUE	Resume a pending LOCATE
COPY STRUCTURE	Copy the current .dbf structure to a new database (.dbf) file
COPY STRUCTURE EXTENDED	Copy field definitions to a .dbf file
COPY TO	Export records to a database (.dbf) file or ASCII text file
COUNT	Tally records to a variable
CREATE	Create an empty structure extended (.dbf) file
CREATE FROM	Create a new .dbf file from a structure extended file
DELETE	Mark records for deletion
DELETE TAG	Delete a tag
FIND*	Search an index for a specified key value
GO	Move the pointer to the specified identity
INDEX	Build an index file
JOIN	Build new database file by merging from two work areas
LOCATE	Search sequentially for a record matching a condition
PACK	Remove deleted records from a database file
RECALL	Restore records marked for deletion
REINDEX	Rebuild open indexes in the current work area
REPLACE	Assign new values to field variables
SEEK	Search an order for a specified key value
SELECT	Change the current work area
SET AUTOPEN	Toggles automatic opening of a structural index file
SET AUTORDER	Defines the default controlling index for automatically opened index files
SET AUTOSHARE	Defines network detection for shared file access
SET DELETED	Toggle filtering of deleted records
SET DESCENDING	Change the descending flag of the controlling order
SET EXCLUSIVE*	Establish shared or exclusive USE of database files
SET FILTER	Hide records not meeting a condition
SET INDEX	Open one or more order bags in the current work area
SET MBLOCKSIZE	Change the block size for memo files
SET ORDER	Select the controlling order
SET RELATION	Relate two work areas by a key value or record number
SET SCOPE	Change the boundaries for scoping keys in controlling order
SET SCOPEBOTTOM	Change bottom boundary for scoping keys in controlling order
SET SCOPETOP	Change top boundary for scoping keys in controlling order
SET SOFTSEEK	Toggle relative seeking
SET STRICTREAD	Toggles read optimization for database access
SET UNIQUE*	Toggle inclusion of non-unique keys into an index
SKIP	Move the record pointer to a new position
SORT	Copy to a database (.dbf) file in sorted order
SUM	Sum numeric expressions and assign results to variables
TOTAL	Summarize records by key value to a database (.dbf) file
UNLOCK	Release file/record locks set by the current user
UPDATE	Update current database file from another database file
USE	Open an existing database (.dbf) and its associated files
ZAP	Remove all records from the current database file

Program Execution

CANCEL	Terminate program processing
DO*	Executes a function or procedure
QUIT	Terminate program processing
RUN	Execute a OS command or program
SET KEY	Assign a procedure invocation to a key
NOTE*	Place a single-line comment in a program file
SET PROCEDURE*	Compile procedures and functions into the current object file

Variable Management

CLEAR ALL*	Close files and release public and private variables
CLEAR GETS	Release Get objects from the current GetList array
CLEAR MEMORY	Release all public and private variables
CLEAR SCREEN	Clear the screen and return the cursor home
RELEASE	Delete public and private memory variables
RESTORE	Retrieve memory variables from a memory (.mem) file
SAVE	Save variables to a memory (.mem) file
STORE*	Assign a value to one or more variables
SET EXACT	Toggle exact matches for character strings

Device, Files & Folders

CLOSE	Close a specific set of files
COMMIT	Perform a solid-disk write for all active work areas
COPY FILE	Copy a file to a new file or to a device
DELETE FILE	Remove a file from disk
DIR*	Display a listing of files from a specified path
ERASE	Remove a file from disk
RENAME	Change the name of a file
SET ALTERNATE	Echo console output to a text file
SET DEFAULT	Set the application default drive and directory
SET DEVICE	Direct @…SAYs to the screen or printer
SET PATH	Specify the CA-Clipper search path for opening files
TYPE	Display the contents of a text file

Printer

EJECT	Advance the printhead to top of form
SET MARGIN	Set the page offset for all printed output
SET PRINTER	Toggle echo of output to printer or set the print destination

Label / Report

LABEL FORM	Display labels to the console
REPORT FORM	Display a report to the console

Date & Time

SET CENTURY	Modify the date format to include or omit century digits
SET DATE	Set the date format for input and display
SET EPOCH	Control the interpretation of dates with no century digits

All

C5DG-9 Terminal Drivers

Clipper 5.x – Drivers Guide

Chapter 9

Alternate Terminal Drivers

Clipper supports a driver architecture that allows Clipper- compiled applications to use alternate terminal drivers. This architecture provides support for nonstandard video hardware and ANSI output devices, allowing your applications to run in a wider variety of environments.

The following terminal drivers are supplied as part of the Clipper Development System and are discussed in this chapter:

. The ANSITERM driver provides ANSI terminal support for systems that require it

. The NOVTERM driver causes Clipper applications to execute faster when run on some nondedicated network server software

. The PCBIOS driver provides direct BIOS calls rather than direct screen writes for systems requiring this form of I/O

In This Chapter

This chapter discusses how Alternate Terminal Drivers fit into the overall Clipper architecture as well as how to install and use each of the supplied terminal drivers. The following major topics are discussed:

. The Alternate Terminal Driver Architecture

. The ANSITERM Alternate Terminal Driver

. The NOVTERM Alternate Terminal Driver

. The PCBIOS Alternate Terminal Driver

The Alternate Terminal Driver Architecture

In Clipper, communication with I/O devices is controlled by a multilayered terminal system. At the lowest level is the terminal driver which controls screen and keyboard activity. It consists of a screen and keyboard driver that communicates directly with the I/O device (operating system or hardware). It is the device specific part of the Clipper terminal system.

There is, then, a higher level system that communicates with terminal drivers. This system is known as the General Terminal (GT) system and provides general services that create Clipper screen and keyboard commands and functions. The following figure demonstrates:

                   +—————————————–+

                   | CA-Clipper screen and keyboard commands |
                   |              and functions              |
                   |-----------------------------------------|
                   |        General Terminal (GT.OBJ)        |
                   ------------------------------------------|
                   |             Terminal Driver             |
                   |-----------------------------------------|
                   |          Screen   |   Keyboard          |
                   +-----------------------------------------+

The default terminal driver, designed for IBM PC and 100% compatibles, is supplied as a library file (TERMINAL.LIB) installed into your \CLIPPER5\LIB directory. This driver links into each program automatically if you specify no alternative terminal driver provided that you do not use the /R option when you compile. An alternate terminal driver is supplied as a separate library (.LIB) file that links into an application program in place of the default terminal driver if you specify it on the link line.

All alternate terminal drivers work through the General Terminal layer as supplied in the file GT.OBJ. The Clipper installation program installs this file in the \CLIPPER5\OBJ subdirectory on the drive that you specify, so you need not install the driver manually.

The ANSITERM Alternate Terminal Driver

The ANSITERM terminal driver supports the ANSI screen mode for all screen display from Clipper programs.

This screen mode is installed by specifying ANSI.SYS in the user’s CONFIG.SYS. ANSI.SYS replaces the default DOS CON device driver for video display and keyboard input. Once installed it supports ANSI escape sequences to erase the screen, set the screen mode, and control the cursor in a hardware-independent way. Most modern DOS programs, however, do not use it and write either directly to the video hardware or use BIOS routines for enhanced screen performance.

Use the ANSI screen mode for Clipper programs that run on hardware that does not support either writing to video hardware or BIOS calls for screen display. This is the case when using alternative display hardware to support the blind.

Note: The ANSITERM terminal driver fully supports all screen and keyboard functionality of the default terminal driver. This includes the ability to save and restore screens and support for all keys on the standard 101-key keyboard.

Installing ANSITERM Terminal Files

The ANSITERM terminal driver is supplied as the file ANSITERM.LIB. The Clipper installation program installs this file in the \CLIPPER5\LIB subdirectory on the drive that you specify, so you need not install it manually.

Linking the ANSITERM Terminal Driver

To link the ANSITERM alternate terminal driver into an application program, you must specify both GT.OBJ and ANSITERM.LIB to the linker along with your application object (.OBJ) modules.

1. To link with .RTLink using positional syntax:

C>RTLINK <appObjectList> GT,,, ANSITERM

2. To link with .RTLink using freeformat syntax:

C>RTLINK FI <appObjectList>, GT LIB ANSITERM

3. To link with .RTLink using ANSITERM.PLL and freeformat syntax:

C>RTLINK FI <appObjectList> /PLL:ANSITERM

Note: These link commands assume you have set the LIB, OBJ, and PLL environment variables to the standard locations. They also assume that the Clipper programs were compiled without the /R option.

Important! You cannot link the ANSITERM driver with BASE52.PLL. An application linked with both ANSITERM.LIB and BASE52.PLL may cause the computer to freeze upon execution.

The Runtime Environment

Using ANSITERM.LIB requires that ANSI.SYS be installed on the user’s computer. To accomplish this, include the following statement in the user’s CONFIG.SYS:

DEVICE=ANSI.SYS

Performance Concerns

Because the ANSITERM terminal driver uses buffered screen writes for all screen painting, some operations, especially those that scroll the screen, are slow. These include:

1. All box drawing commands and functions

2. All console commands and functions when scrolling

3. All clear screen commands and functions

4. All restore screen commands and functions

5. Standard out functions (OUTSTD() and OUTERR()) whether the screen is scrolling or not

Note: Overall performance of Clipper programs is slower since the ANSITERM terminal driver must spend more time polling for user events than the standard Clipper terminal driver.

Screen Output from C and Assembly Language

The ANSITERM terminal driver overwrites all output from C and Assembly Language when it refreshes the screen from the screen buffer. As a consequence, you should perform all screen output from Clipper.

The ANSITERM terminal driver also virtualizes the cursor. This means that BIOS functions that report the location of the hardware cursor will not always return the correct value. To obtain the cursor position, use Clipper’s ROW() and COL() functions instead.

Other Incompatibilities

1. ISCOLOR() always returns false (.F.).

2. When you load DBU, the default color mode is monochrome unless you specify DBU with the /C command line option.

3. The first time you invoke the Debugger, the default color mode is also monochrome unless you set the Options:Mono display off.

4. When an application linked with the ANSITERM terminal driver terminates, the last color set in the application becomes the DOS color. This happens since colors set with ANSITERM are global to DOS and Clipper cannot query DOS for the current screen colors as the application loads.

5. Nondisplaying ASCII characters are presented as a space by the ANSITERM terminal driver. These include BELL (CHR(7)), BS (CHR(8)), TAB (CHR(9)), LF (CHR(10)), CR (CHR(13)), and ESC (CHR(27)).

The NOVTERM Alternate Terminal Driver

The NOVTERM terminal driver is a special-purpose driver that circumvents an incompatibility between some nondedicated network server software and Clipper. This incompatibility causes printers connected to the server to slow to an unusable rate.

Clipper applications and nondedicated servers compete for resources. Clipper applications make use of the time between keystrokes to perform various system tasks. This greatly improves the application’s overall performance by limiting its idle time. Certain nondedicated servers only attempt to print within an application’s idle time. Since a Clipper application is seldom idle, this greatly slows printing.

Important! The NOVTERM terminal driver corrects the incompatibility by preventing the Clipper application from using idle time. Because this can severely hamper performance, you should only use the NOVTERM terminal driver when necessary, and then you should link it only into those applications that are physically running the nondedicated server.

Note: The NOVTERM terminal driver fully supports all screen and keyboard functionality of the default terminal driver. This includes the ability to save and restore screens and support for all keys on the standard 101-key keyboard.

Installing NOVTERM Terminal Files

The NOVTERM terminal driver is supplied as the file NOVTERM.LIB. The Clipper installation program installs the driver file in the \CLIPPER5\LIB subdirectory on the drive that you specify, so you need not install it manually.

Linking the NOVTERM Terminal Driver

To link the NOVTERM alternate terminal driver into an application, you must specify both GT.OBJ and NOVTERM.LIB to the linker with your application object (.OBJ) modules.

1. To link with .RTLink using positional syntax:

C>RTLINK <appObjectList> GT,,, NOVTERM

2. To link with .RTLink using freeformat syntax:

C>RTLINK FI <appObjectList>, GT LIB NOVTERM

3. To link with .RTLink using NOVTERM.PLL and freeformat syntax:

C>RTLINK FI <appObjectList> /PLL:NOVTERM

Note: These link commands assume you have set the LIB, OBJ, and PLL environment variables to the standard locations. They also assume that the Clipper programs were compiled without the /R option.

Important! You cannot link the NOVTERM driver with BASE52.PLL. An application linked with both NOVTERM.LIB and BASE52.PLL may cause the computer to freeze upon execution.

Performance Concerns

Overall performance of Clipper programs is slower since the NOVTERM terminal driver must spend more time polling for user events than the standard Clipper terminal driver and since the program will not use its idle time for other tasks.

Screen Output from C and Assembly Language

The NOVTERM terminal driver overwrites all output from C and Assembly Language when it refreshes the screen from the screen buffer. Therefore, you should perform all screen output from Clipper.

The NOVTERM terminal driver also virtualizes the cursor. This means that BIOS functions that report the location of the hardware cursor will not always return the correct value. To obtain the cursor position, use Clipper’s ROW() and COL() functions.

The PCBIOS Alternate Terminal Driver

The PCBIOS terminal driver uses BIOS calls instead of direct screen writes. It is designedd for applications that trap BIOS calls to redirect output over telecommunication lines or to convert output to a form compatible with two-byte character sets.

Note: The PCBIOS terminal driver fully supports all screen and keyboard functionality of the default terminal driver. This includes the ability to save and restore screens and support for all keys on the standard 101-key keyboard.

Installing PCBIOS Terminal Files

The PCBIOS terminal driver is supplied as the file, PCBIOS.LIB. The Clipper installation program installs the driver file in the \CLIPPER5\LIB subdirectory on the drive that you specify, so you need not install it manually.

Linking the PCBIOS Terminal Driver

To link the PCBIOS alternate terminal driver into an application program, you must specify both GT.OBJ and PCBIOS.LIB to the linker in addition to your application object (.OBJ) modules.

1. To link with .RTLink using positional syntax:

   C>RTLINK <appObjectList> GT,,, PCBIOS;

2. To link with .RTLink using freeformat syntax:

   C>RTLINK FI <appObjectList>, GT LIB PCBIOS

3. To link with .RTLink using PCBIOS.PLL and freeformat syntax:

   C>RTLINK FI <appObjectList> /PLL:PCBIOS

Note: These link commands assume you have set the LIB, OBJ, and PLL environment variables to the standard locations. They also assume that the Clipper programs were compiled without the /R option.

Important! You cannot link the PCBIOS driver with BASE52.PLL. An application linked with both PCBIOS.LIB and BASE52.PLL may cause the user’s computer to freeze when the user executes it.

Performance Concerns

Because the PCBIOS terminal driver uses buffered screen writes for all screen painting, some operations, especially those that scroll the screen, are slow. These include:

1. All box drawing commands and functions

2. All console commands and functions when scrolling

3. All clear screen commands and functions

4. All restore screen commands and functions

5. Standard out functions (OUTSTD() and OUTERR()) whether the screen is scrolling or not

Screen Output from C and Assembly Language

The PCBIOS terminal driver also overwrites all output from C and Assembly Language when it refreshes the screen from the screen buffer. Therefore, you should perform all screen output from Clipper.

The PCBIOS terminal driver also virtualizes the cursor. This means that BIOS functions that report the location of the hardware cursor do not always return the correct value. To obtain the cursor position, use Clipper’s ROW() and COL() functions.

Summary

This chapter has introduced you to the Alternate Terminal Driver concept, giving you specific information on the architecture used to implement them in Clipper. Each of the alternate terminal drivers supplied with Clipper was discussed, including how to link and use it into your application and the implications of doing so.

PICTURE function / template

What is PICTURE function – template ?

@…SAY comand display data at a specified screen or printer row and column with syntax :

@ <nRow>, <nCol> SAY <exp> [PICTURE <cSayPicture>] [COLOR <cColorString>]

@…SAY command output can be formatted using the PICTURE clause with a <cSayPicture>. This performs the same action as the TRANSFORM() function. A <cSayPicture> may consist of a function and/or a template. A PICTURE function imposes a rule on the entire @…SAY output. A PICTURE template defines the length of the @…SAY output and the formatting rule for each position within the output.

Function string:

A PICTURE function string specifies formatting rules which apply to the SAY’s entire display value, rather than to particular character positions within it.

The function string consists of the @ character, followed by one or more additional characters, each of which has a particular meaning (see table below).

The function string must not contain spaces.

A function string may be specified alone or with a template string. If both are present, the function string must precede the template string, and the two must be separated by a single space.

SAY and TRANSFORM() PICTURE Format Functions
---------------------------------------------------------------------
Function Action
---------------------------------------------------------------------
B Displays numbers left-justified
C Displays CR after positive numbers
D Displays dates in SET DATE format
E Displays dates and numbers in British format
R Nontemplate characters are inserted
X Displays DB after negative numbers
Z Displays zeros as blanks
( Encloses negative numbers in parentheses
! Converts alphabetic characters to uppercase
---------------------------------------------------------------------

 Template string:

A PICTURE template string specifies formatting rules on a character-by-character basis. The template string consists of a series of characters, some of which have special meanings (see table below). Each position in the template string corresponds to a position in the displayed SAY value. Characters in the template string that do not have assigned meanings are copied verbatim into the displayed SAY value. If you use the @R picture function, characters without special PICTURE template string meaning are inserted between characters of the display value; otherwise, they overwrite the corresponding characters of the display value. You may specify a template string alone or with a function string. If both are present, the function string must precede the template string, and the two must be separated by a single space.

SAY and TRANSFORM() Template Symbols
---------------------------------------------------------------------
Template Action
---------------------------------------------------------------------
A,N,X,9,# Displays digits for any data type
L Displays logicals as "T" or "F"
Y Displays logicals as "Y" or "N"
! Converts alphabetic characters to uppercase
$ Displays a dollar sign in place of a leading space in a number
* Displays an asterisk in place of a leading space in a number
. Specifies a decimal point position
, Specifies a comma position
---------------------------------------------------------------------

Examples :

This example uses an @…SAY with a PICTURE clause to display formatted output:

nNetIncome = 7125.50
nNetLoss = -125.50
cPhone = "2134567890"
cName = "Kate Mystic"

@ 1, 1 SAY nNetIncome PICTURE "@E 9,999.99" // Result: 7.125,50

@ 2, 1 SAY nNetLoss PICTURE "@)" // Result: (125.50)

@ 3, 1 SAY cPhone PICTURE "@R (999)999-9999" // Result: (213)456-7890

@ 4, 1 SAY cName PICTURE "@!" // Result: KATE MYSTIC

This example is a small label printing program that uses SET DEVICE to direct output to the printer and SETPRC() to suppress automatic EJECTs:

USE Salesman INDEX Salesman NEW
SET DEVICE TO PRINTER
DO WHILE !EOF() // Print all records
   @ 2, 5 SAY RTRIM(FirstName) + ", " + LastName
   @ 3, 5 SAY Street
   @ 4, 5 SAY RTRIM(City) + ", " + State + " " + PostalCode
   @ 6, 0 SAY SPACE(1) // Move to label bottom
   SETPRC(0, 0) // Suppress page eject
   SKIP // Next record
ENDDO
SET DEVICE TO SCREEN
CLOSE Salesman

General Terms

ASCII :

An acronym for the American Standard Code for Information Interchange, the agreed upon standard for representing characters (alphabetic, symbolic, etc.) in the memory of the computer.

Binary :

The numerical base upon which computer programs are modeled. Also referred to as base 2, it is a mathematical way of representing the electrical circuitry upon which computers operate. A 0 represents an off state, and a 1 indicates an on state. A combination of eight ons and offs are used to express bytes of program or data in memory.

See Also: Byte

Buffer :

A temporary data storage location in memory. As an example, a disk input-output buffer is an area of memory that stores data read from the disk to temporary locations while processing it.

Byte :

Eight bits of data, the smallest unit of information stored in the computer’s memory. As an example, one byte is required to represent one ASCII character.

Character :

A letter, digit, punctuation mark, or special symbol stored and processed by the computer.

See Also: ASCII String

Delimiter :

A character or other symbol that marks a boundary.

Destination :

The work area, file, or device to which data is sent.

Device :

Either an actual physical component of the computer system such as printer or a DOS handle that refers to it (e.g., PRN:), or a logical device that behaves and is addressed the same way as a physical device (e.g., a print spooler).

Disk :

A magnetic storage medium designed for long-term storage. Disks come in two varieties: hard disks (fast but fixed) or floppy disks (slow but removable). A disk can be partitioned into multiple volumes, each containing a tree-structured directory system that holds files accessible by programs.

See Also: Directory, File, Volume

Dynamic :

Used generically to refer to data or algorithms that change with time. Often used specifically to describe algorithms that automatically adjust to prevailing conditions.

Formfeed :

A special character (CHR(12)) that by convention causes most printers to move the printhead to the top of the next page.

See Also: Hard Carriage Return Linefeed

Hard Carriage Return :

An explicit carriage return character at the end of a line in a text file, as opposed to a soft carriage return that might be inserted into text by a program designed to handle word wrapping. A hard carriage return character is generated by the expression (CHR(13)) where a soft carriage return character is generated with the expression (CHR(141)).

Hexadecimal :

A representation of a value in base 16 rather than decimal which is base 10. Hexadecimal values are easily converted to and from binary (base 2) which is the form of data the computer actually uses. Hexadecimal values are represented by digits zero through nine and A through F for values between 10 and 15.

Extended Character Set :

The character set built into the ROM of the PC. This character set is a superset of ASCII, containing additional special characters (such as a line drawing character set) that may be used to enhance your program screens.

Linefeed :

A special character (CHR(10)) that by convention causes the cursor or printhead to move to the next line or to terminate a line in a text file. It is usually used in combination with a hard carriage return.

See Also: Formfeed, Hard Carriage Return

Port :

A designation for the hardware that allows the processor to communicate with peripheral devices.

Query :

A query is also a general term used when you want to interrogate a setting or an exported instance variable for its current value.

Queue :

A data structure of variable length where elements are added to one end and retrieved from the other. A queue is often described as first in, first out.

See Also: Print Spooler, Stack

Soft Carriage Return :

A carriage return that is introduced into text usually in order to implement some sort of wrap operation, as opposed to a Hard Carriage Return that was specifically entered into the text when it was created.

Stack :

A data structure of variable length whose elements are added and retrieved from the same end. A stack is often described as first in, last out.

See Also: Queue