This function is used to get a numeric average of selected or all elements of an array.

This routine requires ft_ASum().

ft_RestArr() restores an array which was saved to a disc file using ft_SaveArr().

[1992-10-01 Librarian note:

This function does not appear to work with multi-dimensional arrays. If you'd care to modify it to support this feature, please do and send it to Glenn Scott 71620,1521.]

ft_SaveArr() saves any Clipper array, except those containing compiled code blocks, to a disc file. The array can be restored from the disc file using ft_RestArr().

[1992-10-01 Librarian note:

This function does not appear to work with multi-dimensional arrays. If you'd care to modify it to support this feature, please do and send it to Glenn Scott 71620,1521.]

Can be used to show results of bit manipulation, both before and after. Binary representation follows right-to-left convention of bit position numbering, 0 through 7. Space between high and low nibbles for clarity and easy comparison to hexadecimal notation.

This function is presented to illustrate that bit-wise operations are possible with Clipper code. For greater speed, write .c version and use the Clipper Extend system.

Can be used to show results of bit manipulation, both before and after.

This function is presented to illustrate that bit-wise operations are possible with Clipper code. For greater speed, write .c version and use the Clipper Extend system.

Translates numeric input to a text string.

ft_NToW() is intended to be used with integers only. Since I don't know what your application will be, I cannot assume the type of fraction you want returned (ninety nine cents, 99/100, .99, etc). If you want the fraction in words, just pass it as an integer.

Do not pass a negative number! Handle negative numbers any way you need to in your code. (i.e.: CR, DB, Negative, Minus, etc.)

Also, numeric 0 is returned as a null string. You will need to make a decision how to output it (zero dollars, no dollars, etc).

The ft_Unsqzn() function returns the numeric value from the compressed string. The compression is 50% the storage space of the original number. The original number must have been compressed using the ft_Sqzn() function.

This function, along with ft_Sqzn() can be used to reduce disk storage requirements for numeric fields in a database file.

Called by other ft_Acct*() functions. The algorithm is:

Beginning of period mode:

End of period mode:

ft_AcctMonth() creates an array containing data about the accounting month containing the given date.

An accounting period has the following characteristics:

If the first week of the period contains 4 or more 'work' days, it is included in the period; otherwise, the first week was included in the prior period.

If the last week of the period contains 4 or more 'work' days it is included in the period; otherwise, the last week is included in the next period. This results in 13 week 'quarters' and 4 or 5 week 'months'. Every 5 or 6 years, a 'quarter' will contain 14 weeks and the year will contain 53 weeks.

ft_AcctQtr() creates an array containing data about the accounting quarter containing the given date.

An accounting period has the following characteristics:

If the first week of the period contains 4 or more 'work' days, it is included in the period; otherwise, the first week was included in the prior period.

If the last week of the period contains 4 or more 'work' days it is included in the period; otherwise, the last week is included in the next period. This results in 13 week 'quarters' and 4 or 5 week 'months'. Every 5 or 6 years, a 'quarter' will contain 14 weeks and the year will contain 53 weeks.

ft_AcctWeek() returns an array containing data about the accounting week containing the given date.

An accounting period has the following characteristics:

If the first week of the period contains 4 or more 'work' days, it is included in the period; otherwise, the first week was included in the prior period.

If the last week of the period contains 4 or more 'work' days it is included in the period; otherwise, the last week is included in the next period. This results in 13 week 'quarters' and 4 or 5 week 'months'. Every 5 or 6 years, a 'quarter' will contain 14 weeks and the year will contain 53 weeks.

ft_AcctYear() creates an array containing data about the accounting year containing the given date.

An accounting period has the following characteristics:

If the first week of the period contains 4 or more 'work' days, it is included in the period; otherwise, the first week was included in the prior period.

If the last week of the period contains 4 or more 'work' days it is included in the period; otherwise, the last week is included in the next period. This results in 13 week 'quarters' and 4 or 5 week 'months'. Every 5 or 6 years, a 'quarter' will contain 14 weeks and the year will contain 53 weeks.

Let's say you are given the problem:

"All invoices are due 10 working days from the date they are printed. Please display the due date on the invoice."

When is the due date? Assuming you are printing the invoices today, your answer is:

A work day is defined as Monday through Friday. Unfortunately this routine does not account for holidays.

This documentation was written by Glenn Scott so if it's wrong, blame him.

ft_Calendar() simply displays today's date, time and Julian day in a two line display with an optional box shadow. Cursor keys may be used to page through the calendar by day, week, month or year increments. Returns an 8 element array of calendar data:

WARNING: ft_Calendar() uses ft_Shadow() and ft_XBox()

from the NanForum Toolkit!

ft_DateCnfg() is called internally by many of the date functions in the library to determine the beginning of year date and beginning of week day.

The default beginning of the year is January 1st and the default beginning of the week is Sunday (day 1). Either or both of these settings may be changed by calling ft_DateCnfg() with the proper arguments. They will retain their values for the duration of the program or until they are changed again by a subsequent call to ft_DateCnfg().

It is not necessary to call ft_DateCnfg() unless you need to change the defaults.

ft_DateCnfg() affects the following library functions:

ft_Week() ft_AcctWeek() ft_DayToBoW() ft_Month() ft_AcctMonth() ft_DayOfYr() ft_Qtr() ft_AcctQtr() ft_AcctAdj() ft_Year() ft_AcctYear()

ft_DayOfYr() returns an array containing data about a day in the calendar or fiscal year containing the given date.

The beginning of year date defaults to January 1st but may be changed with ft_DateCnfg().

Returns the date of Easter for any year after 1582 up to Clipper's limit which the manual states is 9999, but the Guide agrees with the actual imposed limit of 2999.

This function can be useful in calendar type programs that indicate when holidays occur.

ft_Elapsed() calculates the elapsed time between two Date/Time events.

It returns an array which contains the following data:

ft_MAdd() adds or subtracts months to/from a given date.

If lMakeEOM is passed and dGivenDate is the last day of a month, it will return the EOM of calculated month. Otherwise it will return the same day as the day of the passed date.

ft_Month() returns an array containing data about the month containing the given date.

Normally the return data will be based on a year beginning on January 1st with weeks beginning on Sunday.

The beginning of year date and/or beginning of week day can be changed by using ft_DateCnfg(), which will affect all subsequent calls to ft_Month() until another call to ft_DateCnfg().

The beginning of year date and beginning of week day may be reset to January 1 and Sunday by calling ft_DateCnfg() with no parameters.

ft_Qtr() returns an array containing data about the quarter containing the given date.

Normally the return data will be based on a year beginning on January 1st with weeks beginning on Sunday.

The beginning of year date and/or beginning of week day can be changed by using ft_DateCnfg(), which will affect all subsequent calls to ft_Qtr() until another call to ft_DateCnfg().

The beginning of year date and beginning of week day may be reset to January 1 and Sunday by calling ft_DateCnfg() with no parameters.

ft_Week() returns an array containing data about the week containing the given date.

Normally the return data will be based on a year beginning on January 1st with weeks beginning on Sunday.

The beginning of year date and/or beginning of week day can be changed by using ft_DateCnfg(), which will affect all subsequent calls to ft_Week() until another call to ft_DateCnfg().

The beginning of year date and beginning of week day may be reset to January 1 and Sunday by calling ft_DateCnfg() with no parameters.

Considers a full week as starting on Sunday, ending on Saturday. First week of year (week 1) may start on any day, and thus

contain any number of days.

Final week of year (week 53) may contain any number of days. Handles dates with CENTURY ON|OFF, to allow for 21st century. Date validation must be external to this function.

ft_Year() returns an array containing data about the year containing the given date.

Normally the return data will be based on a year beginning on January 1st.

The beginning of year date can be changed by using ft_DateCnfg(), which will affect all subsequent calls to ft_Year() until another call to ft_DateCnfg().

The beginning of year date may be reset to January 1 by calling ft_DateCnfg() with no parameters.

ft_DosVer() invokes DOS interrupt 21h, service 30 in order to return the current DOS version. It does this by setting up an array corresponding to machine registers and then calling the toolkit function ft_int86().

It returns a character string corresponding to the DOS version, as follows: The major version, a period ("."), then the minor version.

Function to return the available space on the passed drive letter or the default drive if no drive is passed.

Uses ft_int86() through the internal function _ftDiskInfo().

ft_FlopTst() is designed as a full replacement for ISDRIVE(). Where ISDRIVE() returns just .T. or .F. depending if the diskette drive is ready or not, ft_FlopTst() returns a numeric code designating the diskette drive's status.

ft_FlopTst() is particularly useful in backup and restore programs that need to test the floppy drive before writing/reading from a floppy disk.

No testing has been performed on systems with more than 2 floppy drives. If the third drive is "C" and the fourth "D" then there should be no problems.

It is occasionally useful to be able to call interrupts directly from Clipper, without having to write a separate routine in C or ASM. This function allows you that capability.

Given Clipper's high-level orientation, this function is necessarily somewhat messy to use. First, declare an array of ten elements to hold the eight values for the CPU registers and two string parameters. Then initialize the array elements with the values that you want the CPU registers to contain when the interrupt is executed. You need not initialize all the elements. For example, if the interrupt requires you to specify values for AX, DX, and DS, you would only need to initialize elements 1, 4, and 8.

Once you have done the required register setup, call ft_int86(), passing the interrupt number and the register array as parameters. The function will load the CPU with your specified values, execute the interrupt, and then store the contents of the CPU registers back into your array. This will allow you to evaluate the results of the interrupt.

Some interrupt services require you to pass the address of a string in a pair of registers. This function is capable of handling these sorts of situations, but it will take a little work on your part. If you need to pass a string that uses the DS register, store the string in element 8; if you need to pass a string that uses the ES register, store the string in element 9. ft_int86() will detect that you've supplied a string instead of a numeric value and will behave accordingly.

That takes care of obtaining the segment portion of the pointer. To specify which register is to contain the offset, use the values REG_DS and REG_ES which are defined in the ftint86.ch file. When one of these values is found in an array element, it alerts ft_int86() to use the offset portion of a pointer instead of a numeric value. REG_DS tells ft_int86() to use the offset of the string in element 8, while REG_ES tells ft_int86() to use the offset of the string in element 9.

All the CPU registers are sixteen bits in size. Some, however, are also split into two 8-bit registers. This function is only capable of receiving and returning registers that are 16 bits in size. To split a 16-bit register into two 8-bit values, you can use the pseudo-functions HighByte() and LowByte(), contained in the .ch file.

To alter an 8-bit number so it will appear in the high-order byte of a register when passed to the ft_int86() function, use the MakeHI() pseudo-function contained in the .ch file.

When run in real mode, this function is a shell for __ftint86(), which is written in assembler and does the actual work of executing the interrupt. __ftint86() is callable from C, so feel free to incorporate it into any C routines for which it might be useful. The source for __ftint86() can be found in the file AINT86.ASM.

When run in protected mode, this function is a shell for cpmiInt86(), which is written in assembler and makes a DPMI call to drop into real mode and execute the interrupt. cpmiInt86() is also callable from C, so feel free to incorporate it into any C routines for which it might be useful. cpmiInt86() is part of the CPMI API. See the CPMI documentation for more information.

Some multitasking operating environments (e.g. Windows or OS/2) can function more efficiently when applications release the CPU during idle states. This function allows you "announce" to the operating system that your application is idle.

Note that if you use this function in conjunction with ft_OnIdle(), you can cause Clipper to automatically release the CPU whenever Clipper itself detects an idle state.

The Clipper IsPrinter() function is somewhat limited because it only works with LPT1. Furthermore, it talks directly to the hardware, so if you have redirected LPT1 via the DOS MODE command, the IsPrinter() function will return erroneous results.

This function offers a better alternative. Instead of talking to the hardware, it issues a DOS call that checks to see if the device is ready or not. That gives DOS an opportunity to deal with any redirections, and since you pass the device name as a parameter, you can test any device, not just LPT1 (note that the function defaults to PRN if you fail to pass a valid parameter).

The function also temporarily traps the DOS critical error handler so you don't get any nasty error messages if the device isn't ready. It restores the old critical error handler before exiting.

Note that although this function is mainly designed for testing printers, you can also check to see if a drive is ready. Since DOS thinks the NUL device exists on every drive, you can pass a drive letter followed by NUL as a parameter. If DOS is able to open the NUL device, then the drive is ready, otherwise the door is open or something else is wrong.

This function uses DOS Interrupt 21, service 5Ah (Create temporary file) to create a unique filename in a directory you specify. There will be no extension. After the file is created, you may do any I/O you need (see the test driver in the source code).

This function requires ft_int86().

This function would be used in data driven application to determine whether or not a macro compiled function was linked in.

Several functions can be passed, and nested, in cString.

Caveat: Some function calls are converted by the preprocessor into other function calls. You cannot have these types of functions in a macro compiled string as they never exist at runtime. ft_Linked() will correctly tell you that they are invalid.

For instance: there is no function called "SORT()" in any of the Nantucket Libraries, but it is a valid CLIPPER command because the preprocessor will convert it to other function calls.

Often users will install multiple copies of application software, especially on networks and in situations where the user is trying to get around a copy protection scheme.

This function enables you to learn the name and source location of the currently executing file, so that you may take whatever action you need to.

During memory-intensive operations that do not generate much in the way of idle states, the Clipper runtime may not get a chance to perform garbage collection of discarded memory. This can eventually lead to any of a variety of memory-related internal errors.

This function attempts to alleviate the problem by providing a mechanism by which an idle event can be artificially generated at will. The idle event will cause the CA-Cl*pper runtime to perform an incremental memory scavenge.

This function makes use of an undocumented internal routine. If this this fact makes you uncomfortable then don't use this function, you miserable jello-spined lump of human debris.

This function allows you to evaluate code blocks in the background while the foreground is in an idle state.

To halt the evaluation of the code block during idle states, call ft_OnIdle() with no arguments.

This function makes heavy use of several undocumented internal routines. If this fact makes you uncomfortable then don't use this function, you putrid pile of chicken excrement.

This function effectively allows you to run tasks in the background by transparently and periodically calling a designated routine.

To halt the execution of the background function, call ft_OnTick() with no arguments.

This function makes heavy use of several undocumented internal routines. If this fact makes you uncomfortable then don't use this function, you quivering sack of cowardly slime.

Note: make sure you allocate a buffer large enough to hold enough data for the number of lines that you have in the window. Use the following formula as a guideline:

buffer size = (# of line) + 1 * RMargin

This is the smallest you should make the buffer. For normal use, 4096 bytes is recommended

This routine displays a text file within a defined window using as little memory as possible. The text file to display has to be present or an error value of 0 is returned (as a character.)

Assumptions: The routine assumes that all lines are terminated

with a CR/LF sequence (0x0d and 0x0a).

Note: Make sure you allocate a buffer large enough to hold

enough data for the number of lines that you have in the window. Use the following formula as a guideline - buffer size = (# of line) + 1 * RMargin this is the smallest you should make the buffer and for normal use I recommend 4096 bytes.

Cursor Keys: Up, Down - moves the highlight line

Left, Right - moves the window over nColSkip col's Home - moves the window to the far left End - moves the window to the nRMargin column PgUp, PgDn - moves the highlight one page Ctrl+PgUp - moves the highlight to the file top Ctrl+PgDn - moves the highlight to the file bottom Ctrl+Right - moves the window 16 col's to the right Ctrl+Left - moves the window 16 col's to the left

Esc, Return - terminates the function

All other keys are ignored unless they are specified within cExitKeys parameter. This list will tell the routine what keys terminate the function. Special keys must be passed by a unique value and that value can be found by looking in the dhkey.h file.

This function appends a line of text to the file in the currently selected text file workarea. Text lines are delimited with a CRLF/LF. The record pointer is moved to the last appended record.

Multiple lines may be appended with one call to ft_FAppend().

A text file "record" is a line of text terminated by a CRLF/LF. Each line appended with this function will be empty.

NOTE: Occasionally a text file may contain a non-CRLF/LF terminated line, at the end of the file ("stragglers"). This function assumes these stragglers to be the last line of the file, and begins appending the new lines after this line. In other words, if the last line in the text file is not terminated with a CRLF/LF prior to calling ft_FAppend(), the function will terminate that last line before appending any new lines.

This function is similar to the Clipper Bof() function.

A text file "record" is a line of text terminated by a CRLF/LF.

This function is similar to the CLIPPER Eof() function.

A text file "record" is a line of text terminated by a CRLF/LF.

This function returns the DOS error code associated with a file operation on the currently selected text file.

Errors could stem from any open, create, read or write operation, among others.

This function moves the record pointer to the last record of the file in the currently selected text file workarea.

If a read error occurs ft_FError() will contain the error code.

A text file "record" is a line of text terminated by a CRLF/LF.

This function moves the record pointer to a specific record in the file in the currently selected text file workarea. If the record number requested is greater than the number of records in the file, the record pointer will be positioned at the last record.

Internally, the function operates differently depending on how you invoke it. Passing a value for nLine results in what is effectively a skip operation, which is fairly quick. However if you pass 0 for nLine, e.g. ft_FGoto( 0 ), the function internally goes to the top of the file, then skips down the required number of records. Hence if your file is relatively large and the current record is a high number, you may see some delay as ft_FGoto( 0 ) skips through the file.

A text file "record" is a line of text terminated by a CRLF/LF.

This function moves the record pointer to the first record in the currently selected text file workarea.

A text file "record" is a line of text terminated by a CRLF/LF.

This function inserts a line of text in the file in the currently selected text file workarea. Text lines are delimited with a CRLF/LF.

The record pointer is not moved.

A text file "record" is a line of text terminated by a CRLF/LF. Each line inserted with this function will be empty.

This function returns the number of the last record in a text file.

A text file "record" is a line of text terminated by a CRLF/LF.

This function returns a line of text read from the file in the currently selected text file workarea. Text lines are delimited with a CRLF/LF. The record pointer is not moved.

Currently the maximum record size is 4096 characters. You may increase the maximum record size by changing the value of #define BUFFSIZE in the C source and recompiling, however you should consider the performance implications if you do (all read and writes use this buffer size, including ft_FSkip()'s and ft_FGoto()'s).

If a read error occurs ft_FError() will contain the error code.

A text file "record" is a line of text terminated by a CRLF/LF.

This function returns the current record number of the file open in the currently selected text file workarea.

A text file "record" is a line of text terminated by a CRLF/LF.

This function selects a text file "workarea" from 1 to 10. A file may or may not be open in the selected area.

Passing 0 for nNewArea selects the next available workarea, similar to Clipper's SELECT 0 command. If no more workareas are available the current workarea is not changed.

Each file is opened in its own "workarea", similar to the concept used by dbf files. As provided, a maximum of 10 files (in 10 workareas) can be opened (assuming there are sufficient file handles available). That number may be increased by modifying the #define TEXT_WORKAREAS in the C source code and recompiling.

All the ft_F*() file functions operate on the file in the currently selected text file workarea.

Text file workareas are separate from and independent of Clipper's database workareas.

This function moves the text file record pointer, similar to the CLIPPER SKIP command.

Use the return value to determine how many records were actually skipped, for example to write a custom skipper function for TBrowse-ing text files.

If a read error occurs ft_FError() will contain the error code.

A text file "record" is a line of text terminated by a CRLF/LF.

The ft_F*() file functions are for reading text files, that is, files where each line (record) is delimited by a CRLF/LF.

Each file is opened in its own "workarea", similar to the concept use by dbf files. As provided, a maximum of 10 files (in 10 workareas) can be opened (assuming there are sufficient file handles available). That number may be increased by modifying the #define TEXT_WORKAREAS in the C source code and recompiling.

This function writes a line of text to the file in the currently selected text file workarea. Text lines are delimited with a CRLF/LF. The record pointer is not moved.

The contents of the current record are updated to reflect the new new line written, unless the Insert option is selected.

Writing a null string has the effect of clearing the current line if in overstrike mode, else inserting a new line (same as ft_FInsert()).

A text file "record" is a line of text terminated by a CRLF/LF.

It is occasionally useful to force LastKey() to return a known value. This is easily accomplishing by using the KEYBOARD command, but this has undesirable side effects (the keyboard buffer is cleared, and the keystroke is processed whether you needed it to be or not). This function accomplishes the same task but without the side effects. It does so by directly modifying the memory location where Clipper stores the LastKey() value.

Some highly unorthodox programming techniques, not to mention rather strange use of Clipper internals, was necessary to make this function work. If this makes you uncomfortable, then don't use this function, you worthless crybaby.

This function tells the mouse driver to hide the cursor if it is in the given region. The driver hides the cursor by decrementing the cursor flag. A call to ft_MShowCrs() is required to turn the cursor back on. Calling ft_MShowCrs() also disables this function.

See ft_MShowCrs() for a discussion of the cursor display flag.

In text mode the mouse cursor can either be a software generated or the actual hardware cursor. This routine allows one choose between them. The software cursor is the default and its effect on the character it covers is determined by the screen mask and the cursor mask. Both of these masks are 16-bit values (which in Clipper are passed as standard numerical values). The 16-bit masks are arranged in a manner identical to the way information is stored for each character cell on the screen. The low order 8 bits represent the actual character displayed while the high order bits represent the display attributes such as blinking, intensity and foreground and background colors. The mask is represented in the diagram below:

Blinking and high intensity are on when the bit is 1. The background and foreground indicate which colors are used for each. The software mouse cursor uses these two values by taking the mask from the screen cell it is on and performing a logical AND on each bit with the screen mask value. The result is then logically XOR'ed with the cursor mask value. Thus to keep the character the same but invert the foreground and background colors the following values would be used:

The hardware cursor is the text cursor provided by the video board. One specifies the range of scan lines which are on using nScrMask and nCrsMask. The range of values is dependent upon the type of monitor. The first scan line is 0.

Hides the mouse cursor. Make sure to turn the mouse cursor off when redrawing screens. The mouse cursor dutifully saves the screen under it, so if you draw over the mouse cursor it will create a "hole" in your screen when you move the mouse cursor.

Note: A call to ft_MHideCrs() decrements a mouse driver variable which indicates whether the cursor is shown. The cursor is visible only when the variable = 0. Thus multiple calls to ft_MHideCrs() require an equal number of calls to ft_MShowCrs() before the cursor will again be visible. Once the variable is 0 calls to ft_MShowCrs() does not increment the variable above 0.

Resets the mouse driver and returns mouse status. Use ft_MShowCrs() to display the mouse cursor. The mouse is set to allow it to cover the complete screen (as defined by MaxCol() and MaxRow()). This is necessary because at least some versions of the mouse drivers do not operate according to the documentation when confronted with a 43 or 50 line screen.

Normally, ft_MInit() should be used to initialize the mouse since it will not reinitialize if already done.

This function allows one to control the mouse movement sensitivity. The first two arguments control the amount of movement necessary to move the cursor a given amount. The values are the percentage of full sensitivity and the default values after installing the mouse driver is 50 which represents approximately 3.2 inches of horizontal and 2 inches of vertical mouse movement to cover the entire screen. A value of 100 requires about 0.9 inches of horizontal mouse movement to cover the screen from one side to the other.

The third argument changes the threshold above which the mouse moves at twice the normal speed. The value is a percentage of full sensitivity with the default (50) providing doubling at 64 mickeys per second.

NOTE: These values are NOT restored after resetting the mouse driver/ hardware. A well behaved application should reset them to the original value upon exiting.

NOTE: The above description is counter to all of the documentation I have available. However, it does not work the way it is documented with Microsoft drivers versions 6.16, 6.24, 7.04 and 8.20. The above movement values are documented to be the number of mickeys per 8 pixels and the double speed value as the number mickeys per second required to double the speed. Each of these values should range from 1 to 32000 but the driver forces a maximum of 100. Also the documentation states that resetting the mouse will reset these values. This is not the case.

Displays the mouse cursor. Make sure to turn the mouse cursor off when redrawing screens. The mouse cursor dutifully saves the screen under it, so if you draw over the mouse cursor it will create a "hole" in your screen when you move the mouse cursor.

Note: A call to ft_MHideCrs() decrements a mouse driver variable which indicates whether the cursor is shown. The cursor is visible only when the variable = 0. Thus multiple calls to ft_MHideCrs() require an equal number of calls to ft_MShowCrs() before the cursor will again be visible. Once the variable is 0 calls to ft_MShowCrs() does not increment the variable above 0.

This function returns the current values of the mouse driver version number and type. The major version would be 6 and the minor version would be 10 if the driver were version 6.10. The mouse type and IRQ numbers are also returned.

NOTE: It appears that the values reported when one starts the mouse driver actually have the minor version in hexadecimal! Thus on boot-up my screen showed 6.24 but this routine returned 30 for the minor version number!

This function is similar to the KEYBOARD command, with a few exceptions. First, this function does not clear the keyboard buffer before inserting the keystroke. In addition, since it uses the Inkey() value, you can stuff any key, including function keys, into the keyboard buffer. However, this also means that unlike the KEYBOARD command, you can only stuff one keystroke at a time.

You can easily create a User-Defined Command that makes this function even more like the KEYBOARD command. For example,

will create a command called KEYSTROKE that could be used as a companion command to KEYBOARD. The only difference is that it would insert a single keystroke instead of a string.

Be aware that this function makes use of Clipper's internal event handler. If you don't like using internals, then don't use this function, you sniveling coward.

ft_ScanCode() enables you to distinguish the different scan-codes of similar keys (such as Grey minus versus regular minus), thus increasing the number of keys your input routine can recognize.

It works like Inkey(), in that it waits for a key to be pressed. The scan code consists of two bytes, which are returned as a two-character string.

For example, calling ft_ScanCode() and pressing the Grey-minus key will return a two character string:

LastKey() is not updated by ft_ScanCode(), so don't try to test LastKey() to see what was pressed during an ft_ScanCode() call. Simply assign the return value to a variable and test that (see the test driver below).

* This was adapted from a short C routine posted by John Kaster on

NANFORUM. It was written in Clipper to help demonstrate the ft_int86() function of the Nanforum Toolkit.

This program requires ft_int86().

ft_SInkey() is similar to the function provided by Nantucket in keyboard.prg, with one significant difference: you can pass NIL to Inkey(), which will be treated as a zero (i.e., wait indefinitely for key-press). Therefore, it is necessary to differentiate between an explicit NIL and one that is a result of a formal parameter not being received.

ft_SInkey() differs from the standard Inkey() in that it will respond to any keys set with SET KEY TO or SetKey().

This function calculates the net present value, the difference between the cost of an initial investment and the present value of the expected cash flow(s) from the investment. The present value of the expected cashflow(s) is calculated at the specified interest rate, which is often referred to as the "cost of capital".

This function can be used to evaluate alternative investments. The larger the NPV, the more profitable the investment. See also the FutureValue and PresentValue for further explanations. The formula to calculate the net present value is:

Generates a non-integer random number based on the Linear Congruential Method.

If you need a random number between 1 and nMax inclusive, Int() the result and add 1.

If you need a random number between 0 and nMax inclusive, then you should Round() the result.

This function will allow you to round a number. The following can be specified:

a. Direction (up, down or normal - normal is 4/5 convention) b. Type (whole, decimal, fraction) c. Amount (100's, 5 decimals, 16th, etc.)

ft_Adder() gives you an adding machine inside your Clipper 5.2 application. It has the basic functions add, subtract, multiply, and divide. You may move it from one side of the screen to the other. It even displays a scrollable tape, if you want it.

There are a few HOT Keys while using the Adder:

Decimals - change # of decimals Move - the Adder from right display to left Tape - turn the Tape Display On or Off Scroll - the tape display DEL

+— 2nd Clear adder

ESC - Quit F10 - return a total to the active get

A couple of notes about the adder:

1. It was designed to be used on an Enhanced keyboard with

separate DEL key. DEL is used to clear the adder. However, it will still work on a Standard keyboard.

2. You do not have to display the tape. You may turn it on

at any time by pressing T. You may scroll back through the tape once there are more than 16 entries in the adder, by pressing S.

3. To Quit the Adder just press ESC. To return your Total

to the application press F10. The adder will place the Total in the active GET variable using oGet:varPut(). The adder will only return a Total to a numerical GET!

4. There are many support functions that you might find

interesting. They are part of my personal library, but are necessary to the operation of the adder. You might want to pull these out to reduce the overall size of the adder. Many are worth at least a little time studying.

5. To make ft_Adder() a Hot key from inside your application

at the beginning of your application add the line:

SetKey( K_ALT_A, {|| ft_Adder() } )

This will make ALT+A a key "Hot" and permit you to Pop - Up the adder from anywhere in the application.

6. If you use ft_SInkey(), you can even have active hotkeys

in an Inkey().

ft_Menu1() is a function that displays a pulldown menu for each item on the menu bar and executes the corresponding function for the item selected. When a called function returns false, ft_Menu1() returns control to the calling program.

Valid keystrokes and their corresponding actions:

This function greatly simplifies the process of displaying light-bar menus. All prompts are padded out with spaces so they are the same length, a box is drawn around the prompts, the box is automatically centered on the screen, and the underlying screen is restored after a menu selection has been made.

Additionally, because you can tie action blocks to each menu option, you can save on a lot of DO CASE or IF..ELSEIF code in your main program. See the test code for a succinct demonstration.

This enhanced version of MENU TO requires the inclusion of the header file ftmenuto.ch in any source file that uses it. It may be used in place of the standard Clipper MENU TO command. However, in the interests of functionality it is not 100% compatible (in particular, you should make sure that the target memvar exists before executing the menu — the Clipper version will create a PRIVATE memvar for you if it does not already exist, but this version does not). No whining! If compatibility is such a big deal then use the standard Clipper command.

Note that this command can also be called using function-style syntax. See the entry for ft_MenuTo() for further details.

A good way to display information messages during the running of an application is to send them all to the same line on the screen where users are expected to look for them. In order to give users a chance to read the current message before the next one is displayed we may need to insert a delay after each message.

ft_Pending() function displays messages by keeping track of the time of the last message and providing a delay only if the next pending message is issued much too soon after the current one.

Clipper's @...PROMPT and MENU TO commands are fine as far as they go. But many times you need more flexibility. As you'll no doubt notice if you read the argument list, this function is almost completely flexible. You can adjust locations and colors for every part of the prompt and its associated message. In addition, since you can control the effect of the arrow keys, you can allow both horizontal and vertical movement, or even disable certain arrow keys if you so desire. Support for nested menus is also available, since the prompts are stored in stack-based static arrays.

Note that this command can also be called using function-style syntax. See the entry for ft_Prompt() for further details.

This enhanced version of @...PROMPT requires the inclusion of the header file ftmenuto.ch in any source file that uses it. It is may be used in place of the standard Clipper @...PROMPT command. However, in the interests of functionality it is not 100% compatible. No whining! If compatibility is such a big deal then use the standard Clipper commands.

This routine will wait a specified period of time. It provides resolution based upon the execution of the Seconds() function. It does not use an input state such as Inkey(). The specified time is the minimum time sleeping and will usually be slightly longer.

The second optional argument allows one to begin timing an event prior to executing some operation. This is useful when, for example, you input a key or mouse click and wish to do something but still want to note if the user double entered (mouse or key) within a certain time which in turn may have meaning within your program's context.

The routine correctly handles passing through midnight but will not work for more than 24 hours.

ft_XBox() allows the programmer to display a message box on the screen without needing to calculate the dimensions of the box. Only the upper left corner needs to be defined. The function will calculate the lower right corner based on the number and length of strings passed.

A maximum of eight strings can be displayed. If a string is too long to fit on the screen it is truncated.

The first seven parameters are optional. The default settings are:

Lines of text are centered. Control is returned to the calling routine immediately. A single line border is painted. The border is black on white. The text is white on black. The box is centered both vertically and horizontally.

In order to find out information about a particular node logged in to a NetWare server, you will need the logical station number, also known as a "connection number." This function will return that number. This will be a number from 1 to 100 under NetWare 286, or from 1 to 250 under NetWare 386. This is not the same as a physical station number.

This function requires ft_int86().

This function does not test for the existence of the NetWare shell. The behavior is undefined if no shell is loaded.

ft_NWSemLock() uses the Nanforum Toolkit's NetWare Semaphore API functions in order to provide a general purpose "lock" you can use in a NetWare environment.

An interesting byproduct of NetWare's semaphore functions is the "open count" which tells you how many connections have this semaphore open. This is different from the semaphore's value, which is set when the semaphore is opened and changed with Signal() and wait().

The point of semaphores is that you don't care how many users are using the resource; you merely wait on a semaphore until the resource becomes available or you give up. When you're done, you signal it and off you go.

Back to the open count. ft_NWSemLock() opens the semaphore as named in cSemaphore. After it is opened, the open count is checked. If it is anything other than 1, that means someone else has it (or you failed in your open) so the semaphore is closed and the "lock" is refused. If the value is 1, then your app is that 1 station so the "lock" is granted.

You can use a semaphore lock to control access to anything that Clipper's RLock() and FLock() cannot help you with, such as text files written with the low-level file I/O functions, etc.

A semaphore is simply a label that indirectly controls network activity. There is a semaphore name, which can be up to 127 characters, and an associated value, which can range from 0 to 127.

A semaphore can be used for many things, but is most often used to limit the number of users in an application, and to control access to a network resource.

A semaphore essentially allows you to place locks on resources other than files.

An application begins the process by calling ft_NWSemOpen(). If the semaphore doesn't exist, NetWare will create it. ft_NWSemOpen() returns a handle that is used in other semaphore calls.

Applications use ft_NWSemWait() to wait for a semaphore to become available. ft_NWSemWait() decrements the semaphore's value by 1. If the value > 0, then the application should be allowed to access the semaphore's resource. If the value goes negative, then the application is placed in a queue. How long your app is in the queue is determined by how you set the timeout parameter. If you cannot get the resource in the time you allot, you're let out of the queue and the value increments by 1 again.

When an application finishes with a semaphore, it should call ft_NWSemSig() to increment the value, and then ft_NWSemClose() to close the semaphore. When the semaphore's open count goes to 0, NetWare deletes it.

ft_NWSemEx() can be used to examine the value and open count without affecting them.

For an interesting discussion on the operating system aspects of semaphores, check "Operating Systems Design and Implementation" by A. Tanenbaum, page 60. For more details on NetWare's semaphore facilities, refer to Charles Rose's "Programmer's Guide to NetWare". The "Programmer's Guide" will make an excellent companion guide to the source code for all NetWare functions in the Nanforum Toolkit.